Command Reference

Most routed commands support --json when structured output is useful. The exceptions are slipway init, which is setup-only (--tools/--refresh, no --json), and slipway validate / slipway done, which emit JSON without a separate --json flag. validate --format shapes --list-focuses output, not the main report.

Generated host command surfaces cover registered commands that opt into host prompts. Public CLI-only helper namespaces, such as slipway tool and slipway hook, are registered here and in the surface manifest, but they do not generate $slipway-tool, $slipway-hook, or host prompt wrappers; generated skills and host hook configuration invoke their helper subcommands directly.

Core Lifecycle

Command	Class	Purpose
slipway new [description]	mutation	Create a governed change starting at intake.
slipway intake	mutation	Run S0 intake clarification and authorization.
slipway plan	mutation	Run S1 plan artifact authoring or same-intent change amendment.
slipway implement	mutation	Run S2 implementation wave orchestration.
slipway review	mutation	Run S3 review convergence and reviewer feedback repair.
slipway fix	mutation	Dispatch fresh-context fixes for S3 review findings.
slipway done	mutation	Finalize a done-ready change and archive it.
slipway next	query	Inspect the next actionable skill or blocker without advancing state.
slipway run	mutation	Shortcut-drive the current lifecycle stage until a skill, blocker, or done-ready outcome is surfaced.
slipway status	query	Show lifecycle state, blockers, progress, and next actions.

When a governed change has stale evidence, slipway next remains read-only and reports recovery guidance. Prefer the explicit current-stage command when the state is known: intake, plan, implement, review, or done. run is an auto-driver shortcut that delegates to the current stage and reports delegated_to in JSON. Same-intent scope changes are change amendments inside the current change; intent conflicts open a new governed change. Planning freshness is keyed on the structural task-plan hash. Plan-audit reviews the plan bundle before S2 may start; it does not certify wave-plan.yaml as a planning authority. wave-plan.yaml is an S2 execution projection/cache materialized from the current tasks.md, and its generated_at is materialization time for display/audit rather than freshness authority. The input_context.wave_plan field on slipway next --json is a separate diagnostic-only projection: it carries view-only fields (wave_count, advisories) that the persisted wave-plan.yaml cache does not define, so it must never be copied into the cache. wave-plan.yaml is an engine-owned cache regenerated by tooling (slipway repair) and never hand-edited; if it cannot be read, regenerate it with slipway repair rather than editing tasks.md.

slipway fix is the S3 review-finding repair surface. It discovers reviewer findings and alignment blockers, then returns a repair_batch_id and a contract that includes contract.subagent when a fix slot is configured. Hosts should use that directive when present, otherwise default to a native fresh-context repair subagent. Ordinary discovery does not advance lifecycle state; slipway fix --start-reexecution is the explicit review-driven mode that reopens S2 and materializes a fresh execution run boundary for implementation repairs. The host first collects the selected review batch findings, consolidates them by root cause into one repair brief, and must not repair findings inline or one-by-one while other selected reviewers are still reporting. After the subagent changes code, artifacts, tests, or same-intent scope evidence, rerun the affected selected reviewers and record both context_origin:stage=review=<handle> and context_origin:stage=fix=<handle> before slipway review closes the batch. slipway repair remains local integrity only.

Configured subagent delegation targets live under subagents.* in .slipway.yaml. The slots are default, plan_audit, executor, review, fix, and verify, and each slot can choose type: native|mcp|skills, name, session_instructions, and timeout. See Subagent Configuration for the schema and JSON surfaces.

Creation Options

slipway new "add install docs" --preset standard
slipway new "docs-only change" --profile docs
slipway new --from-doc docs/installation.md "refresh install docs"
slipway new "small fix" --trivial
slipway new "auth refactor" --discuss   # carry open questions forward into context
slipway new "schema migration" --full   # force fresh ship-verification evidence before ship

Presets control gate strictness: light, standard, or strict.

Workflow profiles shape checks: code, docs, research, config, or meta.

--discuss persists unresolved gray areas into context before execution; --full requires a refreshed ship-verification pass before the ship gate.

Discovery

Command	Class	Purpose
slipway codebase-map	mutation	Create or refresh advisory repo-scoped context under artifacts/codebase/.

codebase-map --json reports status: "baseline" when documents contain only CLI-detected repository facts. Baseline docs are useful starting context, not authored brownfield analysis; callers should refine them with source-backed findings before relying on them for planning or review.

Codebase maps under artifacts/codebase/ are git-tracked by default — durable brownfield context is meant to be reviewed and shared, not hidden as local-only state. Existing repositories auto-migrate the next time slipway new, slipway codebase-map, or slipway init rewrites the managed .gitignore block (next/run/status/repair do not reconcile it); bundle-local events/, verification/, legacy per-change evidence/, and .worktrees/ paths stay ignored. Runtime task evidence lives under .git/slipway/runtime/changes/<slug>/evidence/.

Situational Commands

Command	Class	Purpose
slipway preset <level>	mutation	Confirm or change the active change preset.
slipway validate	query	Recompute evidence and gate readiness without advancing.
slipway abort	mutation	Abort the active execution session without archiving the change.
slipway cancel	mutation	Cancel an active change and archive terminal state.
slipway delete	mutation	Discard an abandoned governed change: its bundle, runtime binding, optional worktree, or an archived record (dry-run by default).
slipway repair	mutation	Run bounded local integrity repairs.
slipway evidence task	mutation	Record supported runtime task evidence for wave execution.

slipway cancel and slipway delete are not the same operation. cancel takes an active change to a terminal cancelled status and archives it under artifacts/changes/archived/<slug> so the decision stays in the audit trail. delete instead discards local governed state for an abandoned, accidental, or partially-deleted change — its bundle, its runtime binding, and (with --worktree) the bound git worktree — and with --archived can purge an already-archived record. delete is dry-run by default: a bare slipway delete --change <slug> prints the removal plan and deletes nothing; pass --yes to execute. It fails closed — it refuses to remove a worktree with uncommitted tracked changes or untracked files outside generated Slipway paths unless --force, and never deletes the implementation or pushed PR branch. When a change is abandoned, broken, or bound to another worktree, slipway status/ slipway next and recovery output route to the exact slipway delete --change <slug> command.

Helpers

Command	Class	Purpose
slipway tool <helper>	mutation	Run helper tools used by generated skills; helpers fail closed on missing explicit backends or domain tools.
slipway hook <event>	mutation	Run generated host hook helpers such as session-start; hooks fail silent so they cannot block host automation.

slipway tool and slipway hook are intentionally CLI-only. They have no $slipway-tool, $slipway-hook, or generated host prompt wrappers; generated skills and host configuration call the specific helper subcommands directly.

Diagnostics

Command	Class	Purpose
slipway health	query	Show repo-local integrity and repairability findings.
slipway instructions <artifact>	query	Show the template, quality bar, and — inside a change — resolved output path + dependency graph for a governed artifact or codebase-map doc.

slipway instructions <artifact> serves the artifact template plus its quality bar so an authoring skill writes the real file directly — the engine owns structure, the skill owns substance, and there is no seeded body to replace. Inside a governed change it also returns the resolved output path, the dependency/unlock graph, and tagged background (context/rules) the skill must honor but never copy into the artifact. It covers the six governed bundle artifacts (intent, requirements, decision, research, tasks, assurance) and the repo-scoped codebase-map docs (stack, architecture, structure, conventions, integrations, testing, concerns). In --json, context_is_baseline: true marks codebase-map baseline context that should be preserved and extended into the authored doc; when absent or false, context is background to honor but not copy.

next --json and run --json include input_context.codebase_map_status (and per-doc input_context.codebase_map_doc_states) in the default, non---diagnostics handoff so callers can tell whether the referenced map is durable. Values mirror the slipway codebase-map assessment (missing, scaffold_only, baseline, partial, populated); a missing map reports "missing" with each doc missing rather than an omitted field. When a map-consuming planning skill (research-orchestration or plan-audit) is next and the status is scaffold_only or baseline, warnings carries a non-blocking codebase-map advisory.

Setup

Command	Class	Purpose
slipway init	mutation	Initialize .slipway.yaml, the repo-local runtime layout, and optional AI-tool adapters.
slipway config [list|get|set]	mutation	Inspect and update repo-level .slipway.yaml keys; config list --env [--json] lists runtime/secret environment variables with ownership, value syntax, accepted values, examples, and unset behavior. CLI-only; no generated adapter prompt surface.

docs/SURFACE-MANIFEST.json is the committed generated-surface inventory for adapter, command, skill, JSON, and documentation rows. The manifest is rebuilt from Slipway-owned Go authorities and checked in CI-facing Go tests:

go run ./internal/toolgen/cmd/gen-surface-manifest --check
go run ./internal/toolgen/cmd/gen-surface-manifest --write

When adding a command, skill, JSON output contract, or docs-facing surface, run --write and keep the manifest row’s documentation token present in the named docs file. A stale manifest or missing docs token fails go test ./internal/toolgen.

Output And Hydration Flags

Query and review commands share a consistent output-and-hydration surface, kept aligned with the CLI by a reverse flag-contract test:

• --format <text|yaml|json> — status supports the full set; review, validate, repair, and health use --format only to shape --list-focuses output (text|json). --json is shorthand for --format json where supported.
• --hydrate / --hydrate-ref <skill-id>/<name> — status, review, and health append selected hydrate reference bodies to text output; --hydrate-ref restricts hydration to a named reference (repeatable).
• --focus <alias> / --list-focuses — status, health, review, validate, and repair accept a public focus override; run <command> --list-focuses to enumerate. Known aliases: status/health → incident; review → sast, calibration; validate → sast, property, mutation, spec-trace; repair currently exposes none.
• status --root prints the canonical Slipway scope root; status --stats shows workspace diagnostics (active count, stale summaries, integrity issues).
• next --no-auto-pass reports skill eligibility instead of auto-passing.
• done --all-ready archives every active change that is currently done-ready.
• Same-intent scope changes are handled as change amendments by the current stage command: update the owning artifacts and evidence, then continue forward. Executor agents must not silently write outside declared task scope; they propose the amendment or return a blocker. If the objective changed, start a new governed change.

Useful JSON Invocations

slipway new --json "refresh docs"
slipway intake --json
slipway plan --json
slipway implement --json
slipway fix --json
slipway next --json --diagnostics
slipway run --json --diagnostics
slipway status --json
slipway validate
slipway handoff show --json
slipway config list --json
slipway evidence task --result-file task-result.json [--result-file next-task-result.json ...] --json
slipway health --doctor --json

Stable manifest tokens for JSON contract coverage:

Contract	Token
abort JSON	slipway abort --json
cancel JSON	slipway cancel --json
codebase-map JSON	slipway codebase-map --json
config JSON	slipway config list --json
delete JSON	slipway delete --change <slug> --json
done JSON	slipway done
evidence skill JSON	slipway evidence skill --skill <name> --verdict pass --json
evidence skill refresh-current JSON	slipway evidence skill --skill <selected-review-skill> --verdict pass --refresh-current --reference "context_origin:stage=review=<handle>" --notes-file artifacts/changes/<slug>/verification/<selected-review-skill>-notes.md --json
evidence task JSON	slipway evidence task --result-file task-result.json [--result-file next-task-result.json ...] --json
fix JSON	slipway fix --json
handoff JSON	slipway handoff show --json
health JSON	slipway health --json
implement JSON	slipway implement --json
instructions JSON	slipway instructions <artifact> --json
intake JSON	slipway intake --json
new JSON	slipway new --json
next JSON	slipway next --json
plan JSON	slipway plan --json
preset JSON	slipway preset <level> --json
repair JSON	slipway repair --json
review JSON	slipway review --json
run JSON	slipway run --json
status JSON	slipway status --json
validate JSON	slipway validate

next --json includes next_skill.name for AI-tool handoff. The host tool derives the local SKILL.md path from its own adapter conventions.

When diagnostics are enabled, review-state handoff JSON can also include:

• next_skill.display_name, next_skill.blocking_name, and next_skill.resolution_reason when the conceptual stage differs from the actionable missing skill.
• next_skill.review_context.required_artifact_layers and next_skill.review_context.required_implementation_layers, which map to exact gate tokens such as layer:R0=pass, layer:R3=pass, layer:IR1=pass, and layer:IR3=pass.
• top-level confirmation_requirement, which reports whether a hard stop needs fresh user confirmation, whether prior authorization is sufficient, the next operator action as human prose (next_action), a machine-readable next_action_kind (skill_handoff | review_batch | preset_confirmation | command | blocker_resolution | confirmation | none), and the exact next_command to run when one is runnable as-is. Branch on next_action_kind/next_command; treat next_action as display prose only.
• freshness_diagnostics, which reports stale source/evidence pairs, field-level execution input mismatches, path authority, and the next regeneration action.

run --auto / run --no-auto override execution.auto for one invocation. Config-level execution.auto also applies to intake, plan, and implement; those stage commands have no override flags. Auto only crosses routine run_slipway_run_to_advance command boundaries after a successful advance. Skill handoffs and review batches still stop the run/stage loop for host work; non-sensitive/non-guardrail handoffs may be reported as evidence_continuation instead of hard_stop. security-review boundaries, sensitive/guardrail confirmations, the intake Approved Summary, done finalization, and evidence gates remain hard stops.

validate is the active-readiness authority: it answers whether the current governed state can advance now and mirrors actionable review handoff through actionable_next_skill, including required_tokens for the exact layer references the actionable skill must supply. run --json is the mutating transition surface: advanced reports what this invocation changed, while blockers reports the current stop condition after any transition. A successful advance can therefore be followed by error-severity blockers for the next required skill. health --governance --json is diagnostic health feedback; use it to inspect controls and traceability details, not as the lifecycle authority for whether run just advanced.

status --json includes freshness_diagnostics when execution evidence is known stale and marks each artifact_dag node with blocking plus blocking_reason so draft planning artifacts are not mistaken for current review blockers.

validate --change <slug> selects an explicit active change. If the slug names an archived terminal change, the command fails with archived_change_not_validatable and returns the terminal status plus archived change.yaml path instead of the generic no-active diagnostic. This is an active-readiness contract: validate proves the currently active governed state before done; it is not a post-archive audit surface for frozen bundles. If the explicit slug does not name an active or archived change, validate --change <slug> fails closed with exit code 3 and error_code=change_not_found. By contrast, unscoped validate with no active change is a diagnostics view: it exits 0 and reports invocation_route.kind=no_active with next_command=slipway new.

The durable codebase map under artifacts/codebase/** is exempt from scope-contract changed-file accounting. When only those context files are dirty, they stay out of scope_contract.changed_files and scope_contract.out_of_scope_files, and scope_contract.status stays pass — a refreshed codebase map alone does not trip scope-contract drift. To keep that filtering visible rather than inferred from a git diff disagreement, the exempted files are disclosed explicitly in the scope_contract.exempt_context_files field, surfaced by slipway validate, slipway status --json, and slipway review --json. A pass code task that honestly changed zero files carries a no_op_justification; the scope contract exempts it from the changed-files requirement and discloses it — task id and justification — in the scope_contract.no_op_justified_tasks field on the same three surfaces, so a reviewer sees why a zero-change task passed without reading raw evidence.

slipway evidence task writes the flat runtime task JSON under .git/slipway/runtime/changes/<slug>/evidence/tasks/ for wave-orchestration sync. The default S2 coordinator path is --result-file <path>, repeated when the coordinator wants one atomic batch import. Each executor result JSON contains task_id, verdict, evidence_ref, changed_files, optional no_op_justification (only for a pass code task that changed zero files), blockers, and optional session_id. A batch preflights every file, rejects duplicate task_id entries, and writes no task evidence if any member is invalid. Executor result files must not include ledger-owned fields (run_summary_version, task_kind, target_files, captured_at, freshness_inputs, or input_hash); Slipway derives them from the active wave plan and current task evidence run. Manual flag mode remains available for host-internal or recovery fallback use; use slipway evidence task --help for the current flag contract. The command computes freshness_inputs, validates task kind/verdict/blockers, and refuses unknown or path-unsafe task IDs instead of relying on hand-written JSON. freshness_inputs includes the current task-derived tasks_plan_hash so task evidence cannot be reused after tasks.md semantically changes.

slipway evidence skill --skill wave-orchestration is the S2 bootstrap for execution-summary evidence. Before execution-summary.yaml exists, it derives the wave run version from the current flat task evidence ledger, requires all task evidence to use a single valid run_summary_version, and stamps the wave-orchestration digest from that ledger. Later run-summary-bound skills such as spec-compliance-review, code-quality-review, and the terminal ship-verification gate still require an existing execution summary and fail closed with evidence_skill_run_summary_missing when it is absent.

Accepted governance skill evidence is additionally bound by verification/evidence-digests.yaml, an engine-owned local file that records the content digest of the inputs each passing skill certified. The entry also stores the accepted verification verdict timestamp so a newer host re-run verdict can replace a stale digest during mutating advancement. Read-only commands only compare the stored digest with current inputs; mutating advancement paths stamp the file when passing evidence is accepted. Diff-class review digests certify the current working diff (git diff HEAD plus non-ignored untracked reviewable files, excluding Slipway governed/runtime artifacts under artifacts/changes/**), so a commit between review and finalization can make read-only projections report the review stale until the owning review stage is run again through slipway run against the new diff boundary. If required digest evidence is missing or stale, the owning governance skill is reported stale and must be re-run.

The selected S3 review peers (spec-compliance-review, independent-review, code-quality-review when the workflow profile requires it, and security-review when selected by policy) assert their verdicts against the current diff, planning artifacts, and run-summary version; they do not consume a shared suite-result keystone. The one authoritative full-suite run — plus any guardrail SAST baseline — is owned by the terminal ship-verification gate, which runs it once, after the peers converge, and never from a peer-shared record. There is no slipway evidence suite-result subcommand: ship-verification runs and records the suite itself as part of its single terminal evidence pass.

repair --json separates applied_repairs from unrepaired_drift. Applied repairs are bounded local fixes that were actually performed; unrepaired drift includes a target, reason, and next_action for evidence or artifact work that Slipway did not mutate automatically. Ready execution summaries that are stale only because runtime task evidence is newer can be rebuilt from current wave-backed task evidence; stale planning-source drift remains unrepaired. Empty orphan active-bundle directories left behind after archive cleanup are removed as empty_orphan_bundle applied repairs; non-empty orphan bundles remain operator-reviewed integrity findings. Legacy repo-level handoff files such as .git/slipway/runtime/handoff.md are reported for manual migration to .git/slipway/runtime/changes/<slug>/handoff.md. Empty unheld lock anchors are reported as cleaned_lock_anchor; change-create.lock and repair.lock remain workspace/scope-level coordination locks rather than per-change locks. Missing task-evidence blockers include the runtime task evidence path, record_command=slipway evidence task --result-file <path> --json, and the compact result schema: task_id,verdict,evidence_ref,changed_files,no_op_justification,blockers,session_id; repeat --result-file for atomic batch import. health --json findings include active_change_blocking and active_change_impact; advisory codebase-map warnings are marked non-blocking for the active change.

done archives done-ready worktree-bound changes even when source files or non-active governance artifacts are still uncommitted, returning a non-blocking worktree_dirty_warning with worktree_dirty_files so operators commit those files together with the archived bundle. done never removes the worktree, and git worktree remove already refuses to drop a dirty worktree, so the advisory replaces a hard block. The active artifacts/changes/<slug>/ bundle is excluded from the advisory because done rewrites it into artifacts/changes/archived/<slug>/; sibling or archived bundles are listed.

Resume Execution

If an execution session is resumable:

slipway run --resume --json

Use health --doctor before repair or resume when state looks interrupted or inconsistent.

run --resume only applies to resumable execution states such as S2_IMPLEMENT. If the active change is already in S3 review or done-ready, JSON errors include current_state, resumable_states, and a next_action directing the operator back to the S3 review/done-ready flow.