Commands

Every flag is listed in the Command reference. This page is about when to reach for each command, and why.

Hand over a plan

Write the plan to a file, then delegate it:

# Against an issue that already exists
ship delegate plan SHIP-412 --file docs/plan.md

# No issue yet: create one and start in the same call
ship delegate plan --title "Rate-limit the search endpoint" --file docs/plan.md

The planner is skipped entirely: the fleet builds from your spec as written, rather than re-deriving a plan from the ticket. That is the point of this hand-off: you have already made the decisions, and you want them implemented rather than reconsidered.

Name the files the plan expects to touch with --file-plan <path.json> (a JSON array of {path, action, description}) when you know them. Without it the builder decides for itself.

Hand over a branch

Open the pull request yourself, because the platform never pushes or opens PRs on your behalf, then delegate it. --pr is auto-detected from the current branch when the gh CLI is available.

ship delegate pr SHIP-412              # review, then test, then merge
ship delegate pr SHIP-412 --at qa      # already reviewed; just test it
ship delegate pr                       # no ticket: the mission is named after the PR

If CI is failing on that PR, the fleet takes over fixing it before review. That is expected, not an error.

Pin the harness or model

--harness and --model change how this mission runs without touching your ship.yml. They apply to the role you are delegating to: the builder for delegate plan, the reviewer (or QA with --at qa) for delegate pr.

ship delegate plan SHIP-412 --file docs/plan.md --harness codex
ship delegate pr SHIP-412 --at qa --model claude-opus-5

Reach for these when you want a specific agent or model, or when comparing two of them on the same work. Otherwise leave them off, because the project's configuration is the setting your team already agreed on.

Give one role extra instructions

Sometimes a single mission needs instructions the repository does not carry: review this one for security specifically, or enforce a rule you have just decided on. --prompt-file sends instructions from a local file, applied to the role you are delegating to, for this mission only. Nothing is committed.

ship delegate pr SHIP-412 --prompt-file security-review.md

Use --prompt-path instead when the instructions already live in the repository, optionally at a specific ref:

ship delegate pr SHIP-412 --prompt-path .ship/lanes/security.md
ship delegate pr SHIP-412 --prompt-path .ship/lanes/security.md --prompt-ref main

Replace or extend

If your repository already has a .ship/agents/<role>.md (see Agent prompts), --prompt-mode decides what happens to it:

# Just this lane, ignoring the repo's reviewer conventions
ship delegate pr SHIP-412 --prompt-file security-review.md

# The repo's conventions, plus this lane on top
ship delegate pr SHIP-412 --prompt-file security-review.md --prompt-mode extend

extend is usually what you want when the repository's conventions are worth keeping and you are adding emphasis rather than replacing a way of working. replace is the right choice when the mission is genuinely a different job, because a security audit reads a diff differently than a normal review does.

Either way, SHIP's own charter for that role still applies. Neither mode can switch it off; both layer on top of it.

Both layers are recorded separately. The mission's Prompt tab labels the repository's file and your override as distinct blocks, so you can see exactly what the agent read, and cost and outcome comparisons treat "repo layer only", "override only", and "both" as different configurations rather than averaging across them.

Steer a running mission

When you decide something about work already delegated, whether that is answering a question, passing on review comments or correcting a choice, send it as an instruction. It reaches the agents and puts the builder back on the mission's open pull request.

ship instruct SHIP-412 -m "Keep the current Node range, override nopt instead"
ship instruct SHIP-412 --file review-notes.md
ship instruct SHIP-412 -m "FYI staging is down until 14:00" --note

--note records context for whatever runs next without starting any work.

Use this rather than re-running the mission. A re-run re-checks an unchanged pull request against the verdicts it already has, finds nothing changed, and correctly does nothing, so it looks like it worked while your feedback goes nowhere.

Check on it

ship status SHIP-412
ship status SHIP-412 --json

Every command takes --json for machine-readable output, and exits with a distinct code so scripts can branch on the outcome.