heliohq/ship/design

Ship: Design

You ARE the planner. You read code, investigate, write spec and plan. Read the load-bearing code yourself — a plan written from someone else's summary loses the context that makes it executable. On a large repo you may use read-only search agents to scout breadth (locate files, callers, conventions), but scouts locate code; they never replace your own reading of what you cite. A peer agent investigates independently and produces its own spec for adversarial comparison.

Runtime Resolution

_Path note: ../shared/*.md references resolve against this skill's base directory (announced as "Base directory for this skill" when the skill loaded), not your working directory._

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).

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

Track your progress with the harness's task/todo list. After Phase 1 (init), create items that reflect the actual work ahead. Adapt them to what you discover — skip items for phases that don't apply, add items for loops you enter (re-investigation, drill revision).

Principle: one item per major phase the user would care about. Update the in-progress label to reflect what's happening within a phase.

Example (full run with peer available):

[in_progress] Investigate codebase (host + peer)
[pending]     Write spec
[pending]     Diff host vs peer specs
[pending]     Write implementation plan
[pending]     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"
• Write a spec claim from a sub-agent's summary — read-only search

agents may scout breadth on a large repo (where things live, callers, naming conventions), but every claim that enters the spec must trace to file:line YOU read

• 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:

```bash TASK_ID=$(printf '%s' "<description>" \

```

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 when the runtime provides one — needed for debate in Phase 4.

When the peer agent is unavailable

If peer dispatch fails, self-produce the second spec:

1. Run a second-pass review of your spec using only: placeholder scan,

contradiction scan, coverage scan, ambiguity scan

1. Search for code paths, callers, or consumers you did not trace
2. Write peer-spec.md with any changed conclusions or additions
3. Add a warning: WARNING: Second spec was self-generated, not independent

Step B: Your investigation

Read write-spec.md for investigation methodology and spec authoring.

Investigate the codebase, then write spec.md. The reference covers investigation strategy (bug fixes, new features, all tasks), vagueness checks, spec structure, and self-review.

If investigation reveals hidden dependencies or cross-cutting concerns not apparent from the task description, note them for the spec.

Phase 3: Write Spec

Covered by write-spec.md — follow the spec writing and self-review guidance there.

Phase 4: Diff & Verify

Read peer-spec.md (written by the peer investigation dispatched in Phase 2). Compare it against your spec.md.

For each divergence point:

1. Identify the divergence — what does your spec say vs the peer spec?
2. Verify against code — read the actual code to determine which

is correct. Do NOT resolve by reasoning about which "sounds better."

1. If still disagree — debate with the peer agent. Continue on the

same peer thread or session when possible using that runtime's follow-up mechanism. Present your code evidence and ask the peer to present counter-evidence. If the runtime cannot continue the same session, dispatch a fresh peer session with the prior evidence quoted verbatim. Maximum 2 debate rounds. Both sides must cite file:line references.

1. Assign disposition after debate:

• patched → Your spec updated based on evidence. Show the diff.
• proven-false → The peer claim is wrong. Cite the code evidence.
• conceded → The peer convinced you with code evidence. Update spec.
• escalated → 2 debate rounds exhausted, still unresolved. Needs user input.

Record in diff-report.md

Only record divergences and their resolutions. If both specs agree on something, there's nothing to record — move on.

For each divergence, write what happened: what each side claimed, what code evidence was cited during debate, and the final disposition (patched / proven-false / conceded / escalated).

After diff resolution:

• Update spec.md with all patched and conceded items.
• If any escalated items exist:
• Standalone mode: ask user via AskUserQuestion before proceeding.

Record the user's ruling in diff-report.md with disposition user-resolved and what they decided. Update spec.md accordingly.

• /ship:auto mode: do NOT ask user. Treat escalated items as BLOCKED

and return. /ship:auto owns the only user-approval gate.

• If diff reveals a critical investigation gap (e.g., the peer found

important code you missed entirely), go back to Phase 2 for targeted re-investigation. Maximum 1 re-investigation loop.

Phase 5: Write Plan

Read write-plan.md for plan structure, task granularity, no-placeholder rules, and self-review.

Translate the validated spec.md into an executable plan.md. The reference covers the plan template, bite-sized steps, code completeness guidance, and the self-review checklist.

Phase 6: Execution Drill

Skip this phase when `Scope mode: refactor`. Record in the report card that the drill was skipped due to refactor scope, then finish.

For full scope (default), run the drill as below.

The final gate. Give the plan to the peer agent and ask it to validate every step is implementable.