/dev

name: dev
version: 0.7.0
description: >
  Implement from a spec or plan: extract stories, build in safe waves, test,
  commit, and get peer review per story. Use for "implement", "build/code this
  plan", or targeted fix findings. If no plan exists, use /ship:design first.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
  - mcp__codex__codex
  - mcp__codex__codex-reply

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

| Wave shape | Implementer | Reviewer | |---|---|---| | **Single-story** (most common) | Host (you), on current branch | Peer agent | | **Multi-story parallel** | Fresh Agent subagents per story, all on the current branch (dependency analysis guarantees their file scopes don't overlap — no worktrees needed) | Peer per story | | **Fix mode** (/ship:auto review_fix/qa_fix/e2e_fix dispatch) | Host — you | (next phase re-runs its own verification) |

Quality Gates

| Gate | Condition | Fail action | |------|-----------|-------------| | Spec + plan read | Acceptance criteria extracted, TEST_CMD found | AskUserQuestion | | Implement → Review | Story produced at least one commit (from subagent report, or HEAD moved since WAVE_BASE_SHA for single-story waves) | BLOCKED | | Review → Next story | Verdict is PASS or PASS_WITH_CONCERNS | Targeted fix (progress-governed — see Step C) | | All stories → Done | Full test suite passes | Targeted fix for regression |

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

0. **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. 3. 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`. 4. Extract code conduct from `CLAUDE.md`, `AGENTS.md`, lint/formatter configs, and existing code patterns. Record as `CODE_CONDUCT`. 5. **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 deviatio