Ship: Design

You ARE the planner. You read code, investigate, write spec and plan. You must read the code yourself — delegating investigation loses the context needed to write a good plan. A peer agent investigates independently and produces its own spec for adversarial comparison.

Runtime Resolution

See ../.shared/runtime-resolution.md for the host/peer concept and dispatch commands. In /ship:design, the peer plays two roles: investigator (Phase 2) and drill agent (Phase 6). Both use the same dispatch pattern from the shared reference.

Scope Mode

The prompt may specify Scope mode: full (default) or Scope mode: refactor. It controls how much adversarial validation runs:

Why refactor mode skips Phase 6: for behavior-preserving changes (refactor, simplify, rename, extract, dedupe), the plan steps are usually small, mechanical code movements. The drill's "is every step implementable" check earns little here while adding a full peer round-trip. Peer investigation and diff stay on because they catch the real refactor failure mode — "moved complexity instead of removing it."

If no scope mode is specified (e.g. standalone /ship:design invocation), default to full.

Process Flow

Phase 1  Init            resolve task_id, create .ship/tasks/<id>/plan/
Phase 2  Investigate     dispatch peer (parallel) ─┐
                         you read the code         │
                         ↓                         │
Phase 3  Write spec      write host spec.md  ←─── peer writes peer-spec.md
                         vague? ask user → re-investigate
                         ↓
Phase 4  Diff & verify   compare specs → resolve each divergence
                         disagree? → debate peer (max 2 rounds)
                         still open? → escalate to user
                         critical gap? → re-investigate (max 1 loop)
                         ↓
Phase 5  Write plan      write plan.md with executable tasks
                         self-review against spec
                         ↓
Phase 6  Execution drill dispatch peer (fresh session) to validate plan
                         BLOCKED step?  → escalate
                         UNCLEAR step?  → revise plan (max 1 loop)
                         all CLEAR      → ready for execution

Roles

Quality Gates

No artifact passes to the next phase without meeting its gate.

Progress Tracking

Use TodoWrite to track your own progress through the design phases. After Phase 1 (init), create todos that reflect the actual work ahead. Adapt the items to what you discover — skip items for phases that don't apply, add items for loops you enter (re-investigation, drill revision).

Principle: one todo per major phase the user would care about. Update activeForm to reflect what's happening within a phase.

Example (full run with peer available):

TodoWrite([
  { content: "Investigate codebase (host + peer)", status: "in_progress", activeForm: "Investigating codebase" },
  { content: "Write spec",                         status: "pending",     activeForm: "Writing spec" },
  { content: "Diff host vs peer specs",            status: "pending",     activeForm: "Diffing specs" },
  { content: "Write implementation plan",          status: "pending",     activeForm: "Writing implementation plan" },
  { content: "Execution drill",                    status: "pending",     activeForm: "Running execution drill" }
])

Adaptations (not exhaustive — use judgment):

• Peer unavailable → drop "Diff" item, rename "Investigate" to reflect self-produced peer spec
• Upstream spec already exists → drop "Write spec", start with "Validate existing spec"
• Re-investigation needed → re-mark "Investigate" as in_progress
• Drill revision needed → keep "Execution drill" as in_progress

Red Flag

Never:

• Cite files you haven't opened
• Let the peer see your spec before producing its own
• Resolve divergences by reasoning instead of code evidence (max 2 debate rounds, both cite file:line)
• Trust prior conversation over disk artifacts
• Mark plan ready when drill has BLOCKED or UNCLEAR items
• Skip the drill because "the plan looks solid"
• Delegate investigation to a sub-agent — read the code yourself
• Claim "function X is not called" without tracing all callers
• Propose a fix without searching for existing defenses
• Propose to create a file without checking if it already exists
• Change a value without grepping tests that assert the old value
• Write plan.md with vague steps or placeholders (TBD, TODO, "similar to Task N")

Phase 1: Init

• Resolve task_id, create .ship/tasks/<task_id>/plan/ directory.
• If resuming, read existing artifacts and determine current state.
• Collect branch name and HEAD SHA.

Task ID

1. If invoked by /ship:auto, the task_id is provided.
2. If invoked standalone, generate a concise deterministic task slug:

   TASK_ID=$(printf '%s' "<description>" \
     | tr '[:upper:]' '[:lower:]' \
     | sed 's/[^a-z0-9]/-/g' \
     | sed 's/--*/-/g' \
     | sed 's/^-//;s/-$//' \
     | cut -c1-60)
   

Artifacts go to .ship/tasks/<task_id>/plan/. The Write tool creates directories automatically — no mkdir needed.

Existing spec.md detection

Check if spec.md already exists with content:

[ -s .ship/tasks/<task_id>/plan/spec.md ] && echo 'SPEC_EXISTS' || echo 'NO_SPEC'

If SPEC_EXISTS:

• Read spec.md. This was written by an upstream skill (e.g. refactor).
• Check if spec records a HEAD SHA. If it does and it differs from current HEAD, treat spec as stale — proceed as NO_SPEC.
• Do not overwrite it. Use it as your investigation input.
• Your job narrows: investigate to validate the spec's claims, then produce only plan.md. You may append an ## Investigation section to the existing spec if it lacks one, but preserve all existing sections.
• Peer investigation and diff still run — the peer validates the upstream spec independently. Execution drill runs per Scope Mode (always in full, skipped in refactor).

If NO_SPEC: proceed to Phase 2.

Phase 2: Investigate (Parallel)

This is the most important phase. Do not rush it.

Step A: Dispatch peer investigation

Kick off the peer investigation before you start investigating. The peer works in parallel while you read code.

Read independent-investigator.md for the dispatch pattern and prompt template. Fill in the task description, task_id, and repo root. Dispatch the resolved peer runtime and save the returned thread or session id as INVESTIGATION_THREAD_ID