heliohq/ship/dev

Ship: Implement

HOST IMPLEMENTS. PEER CROSS-VALIDATES.
EVERY FINDING NEEDS FILE:LINE + EVIDENCE.

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:dev, the host is the primary implementer and the peer is the independent reviewer — the reviewer MUST differ from whoever implemented the story. Prefer a non-host provider for cross-model validation; if unavailable, use a fresh same-provider session and record the weaker independence in the report.

Two wave shapes, different dispatch patterns (fix routing — whoever implemented, fixes — is specified in Step C):

Quality Gates

Red Flag

Never:

• Skip the peer review — every story goes through peer review (or fallback)

before the wave merges. This is the only cross-validation in the pipeline until /ship:review runs.

• Parallelize stories that share files without dependency analysis
• Re-implement a full story on FAIL — make targeted surgical fixes
• Advance to next story without getting a reviewer verdict
• Soften a test assertion to make it pass instead of fixing the code
• Reuse a reviewer dispatch across stories — fresh peer call each time
• Let the peer reviewer become your coder — if the reviewer suggests a

fix, YOU apply it; don't ask the reviewer to write patches

• Tell a reviewer what not to flag, or pre-rate a finding's severity.

Tripwire: if the dispatch you are composing contains "do not flag", "don't treat X as a defect", or "at most minor" — stop; you are pre-judging, usually to spare yourself a review round. Let the reviewer raise it and adjudicate the verdict yourself.

• Re-implement a story the dev ledger already marks complete — after a

compaction or resume, trust dev-ledger.md and git log over your own recollection

Progress Tracking

Track your progress with the harness's task/todo list. Build the list after Phase 1 (setup), once you know the actual wave/story structure. The items should reflect the real work — don't use a canned template.

Principle: one item per wave (not per story) to keep the list short. Set the item's in-progress label to show which story within a wave is active. Always end with a regression test item when there are multiple stories.

Example (3-wave normal run):

[in_progress] Wave 1: "Add User model", "Add Product model"  (implementing Story 1)
[pending]     Wave 2: "User API", "Product API"
[pending]     Wave 3: "Auth middleware"
[pending]     Cross-story regression test

Adaptations (not exhaustive — use judgment):

• Fix mode (invoked with findings) → single item: "Fix <review/QA> findings"
• Targeted fix within a wave → update that wave's in-progress label:

"Fixing Story N (round R)"

Phase 1: Setup

1. Check for a ledger. If <task_dir>/dev-ledger.md exists, stories

listed there as complete are DONE — do not re-implement or re-review them; resume at the first story not marked complete. The commits the ledger names exist in git even when your context no longer remembers creating them.

1. Read acceptance criteria (from spec file, or derived from user request).
2. Read implementation stories (from plan file, or single story for small tasks).

Accept any heading format: ## Story N, ## Step N, ## N. Title, or numbered/bulleted lists. Normalize as ordered stories. Note the plan's ## Global Constraints section if present — copy it verbatim into every implementer and reviewer dispatch; it is the reviewer's attention lens for what this project's spec demands.

1. Detect the repo's test command by inspecting project root

(Makefile, package.json, pyproject.toml, go.mod, Cargo.toml, CI configs, CLAUDE.md/AGENTS.md). If none found, AskUserQuestion. Record as TEST_CMD.

1. Extract code conduct from CLAUDE.md, AGENTS.md, lint/formatter

configs, and existing code patterns. Record as CODE_CONDUCT.

1. Build pattern references. For each story, find the closest

analogous implementation before anyone writes code:

• Search adjacent directories, feature folders, test folders, and

shared component/module areas for similar files. Read the full files, not just matching snippets.

• Record 1-3 references in <task_dir>/dev-context.md with:

file path, why it is analogous, patterns to mirror, and intentional deviations. Capture the conventions listed in implementer-prompt.md (import/export shape, file organization, naming, test setup, error handling, styling/theme usage, framework-specific conventions).

• If no analogous file exists, record the searches performed and

none found; this is allowed, but silent skipping is not.

Pattern references are evidence, not copy-paste licenses. Mirror the local structure and conventions, but do not clone product-specific logic, stale bugs, or unrelated behavior.

1. Build story dependency graph. When the plan carries per-task

**Interfaces:** blocks (consumes/produces) and **Files:** lists, build the graph from those declarations — that is what they exist for, and declared beats guessed. Otherwise derive per story:

• Files/modules it will create or modify (from plan text)
• Explicit dependencies (e.g., "uses the model from story 1")
• Shared resources (e.g., two stories both modify the same config file)

A story depends on another if it consumes what the other produces, or both modify the same file. Build a DAG and topologically sort into waves — groups of stories with no dependencies between them.

``` Example: 5 stories Story 1: add User model → no deps Story 2: add Product model → no deps Story 3: add API for User → depends on 1 Story 4: add API for Product → depends on 2 Story 5: add auth middleware → depends on 3, 4

Waves: Wave 1: [Story 1, Story 2] ← parallel Wave 2: [Story 3, Story 4] ← parallel Wave 3: [Story 5] ← sequential ```

If the plan does not provide enough information to determine file overlap, default to sequential (single story per wave). Do not guess — false parallelism causes merge conflicts.

dev-context.md format

Write <task_dir>/dev-context.md during setup and update it if fix mode adds new pattern evidence:

# Dev Context
 
## Test Command
<TEST_CMD>
 
## Code Conduct
<CODE_CONDUCT>
 
## Pattern References
### Story <i>: <title>
-Reference: `<path>`
  -Why analogous: <short reason>
  -Mirror: <structure/test/style/error-handling conventions>
  -Deviations: <intentional differences, or "none">
 
## Waves
<wave grouping and dependency notes>

Locating input

1. Caller provides paths → use them directly.
2. Caller provides a task directory → look for spec/plan files inside.
3. No formal plan or spec exists → derive acceptance criteria from

user request + source files, confirm via AskUserQuestion, break into stories if multi-file. Do not ask the user to write a plan.

1. Caller provides review/QA findings (fix mode) → this is a targeted

fix, not a full implementation. See Fix Mode below.

Fix Mode

When invoked by /ship:auto with review findings or QA issues to fix, operate in fix mode instead of the full wave loop:

1. Read the findings/issues provided by the caller.
2. For each finding, identify the affected file(s) and the fix needed.
3. Read the existing <task_dir>/dev-context.md if present. If the fix

touches a file or subsystem not covered by the recorded pattern references, read the nearest analogous file and append a short pattern note before editing.

1. **You apply the fixes directly — no dispatch; the caller already did

the analysis.**

1. Run TEST_CMD after fixes to verify no regressions.
2. Commit the fixes with Conventional Commit messages.

Fix mode skips: wave construction, full pattern-reference inventory, dependency analysis, story-based peer review. The fixes are re-validated by /ship:auto's next-phase dispatch (/ship:review, /ship:qa, or the post_qa_fix → e2e-recheck gate), not by dev's internal reviewer.

Return: which findings were fixed, what verification ran, any remaining concerns.

Pre-flight plan review

Before Wave 1 (skip in fix mode), scan the plan once for:

• stories that contradict each other or the plan's Global Constraints
• anything the plan explicitly mandates that review treats as a defect

(a test that asserts nothing, verbatim duplication of a logic block)

Present everything you find as ONE batched AskUserQuestion — each finding beside the plan text that mandates it, asking which governs — before execution begins, not one interrupt per discovery mid-run. If the scan is clean, proceed without comment. (Under /ship:auto's no-questions mode, record the conflicts in concerns.md, choose the spec-compliant reading, and continue.) The review loop remains the net for conflicts that only emerge from implementation.

Phase 2: Per-Wave Loop

For each wave, run all stories in the wave through Steps A→B→(C)→D. All work happens on the current branch — no worktrees, no story- specific branches.

Why no worktrees

Waves are built so stories in them don't share files (Phase 1 step 6) — two stories touching one file is a wave-construction error, not a merge conflict to solve. Git's .git/index.lock serializes concurrent commits to the branch.

Record WAVE_BASE_SHA once at wave start so you can compute per-story file scope later:

WAVE_BASE_SHA=$(git rev-parse HEAD)

Step A: Implement

Single-story wave (and all fix rounds where host is the implementer) — you implement directly.

Use implementer-prompt.md as your own checklist: read the story text, acceptance criteria, Global Constraints, the interfaces earlier stories produce (from the ledger), CODE_CONDUCT, pattern references, and TEST_CMD, then write the code in the current branch. Commit using Conventional Commits as you go. Run TEST_CMD before declaring the story complete.

Multi-story parallel wave — dispatch Agent subagents in parallel.

You cannot fork yourself, so multi-story parallelism needs sub-agents. Dispatch one Agent per story, all in a single message so they run in parallel. All subagents share the same cwd (the current branch); the wave's dependency analysis guarantees their file scopes don't overlap.

Hand each subagent its inputs as file paths, not pasted text — everything you paste into a dispatch stays resident in your context and is re-read on every later turn. Generate the story brief first: