/dev-story

name: dev-story
description: "Read a story file and implement it. Loads the full context (story, GDD requirement, ADR guidelines, control manifest), routes to the right programmer agent for the system and engine, implements the code and test, and confirms each acceptance criterion. The core implementation skill — run after /story-readiness, before /code-review and /story-done."
argument-hint: "[story-path]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash, Task, AskUserQuestion
model: sonnet

Dev Story

This skill bridges planning and code. It reads a story file in full, assembles all the context a programmer needs, routes to the correct specialist agent, and drives implementation to completion — including writing the test.

**The loop for every story:**

/qa-plan sprint           ← define test requirements before sprint begins
/story-readiness [path]   ← validate before starting
/dev-story [path]         ← implement it  (this skill)
/code-review [files]      ← review it
/story-done [path]        ← verify and close it

**After all sprint stories are done:** run `/team-qa sprint` to execute the full QA cycle and get a sign-off verdict before advancing the project stage.

**Output:** Source code + test file in the project's `src/` and `tests/` directories.

---

Phase 1: Find the Story

**If a path is provided**: read that file directly.

**If no argument**: check `production/session-state/active.md` for the active story. If found, confirm: "Continuing work on [story title] — is that correct?" If not found, ask: "Which story are we implementing?" Glob `production/epics/**/*.md` and list stories with Status: Ready.

---

Phase 2: Load Full Context

**Before loading any context, verify required files exist.** Extract the ADR path from the story's `ADR Governing Implementation` field, then check:

| File | Path | If missing | |------|------|------------| | TR registry | `docs/architecture/tr-registry.yaml` | **STOP** — "TR registry not found at `docs/architecture/tr-registry.yaml`. Run `/architecture-review` to bootstrap the registry from your GDDs and ADRs." | | Governing ADR | path from story's ADR field | **STOP** — "ADR file [path] not found. Run `/architecture-decision` to create it, or correct the filename in the story's ADR field." | | Control manifest | `docs/architecture/control-manifest.md` | **WARN and continue** — "Control manifest not found — layer rules cannot be checked. Run `/create-control-manifest`." |

If the TR registry or governing ADR is missing, set the story status to **BLOCKED** in the session state and do not spawn any programmer agent.

Read all of the following simultaneously — these are independent reads. Do not start implementation until all context is loaded:

The story file

Extract and hold:

• **Story title, ID, layer, type** (Logic / Integration / Visual/Feel / UI / Config/Data)
• **TR-ID** — the GDD requirement identifier
• **Governing ADR** reference
• **Manifest Version** embedded in story header
• **Acceptance Criteria** — every checkbox item, verbatim
• **Implementation Notes** — the ADR guidance section in the story
• **Out of Scope** boundaries
• **Test Evidence** — the required test file path
• **Dependencies** — what must be DONE before this story

The TR registry

Read `docs/architecture/tr-registry.yaml`. Look up the story's TR-ID. Read the current `requirement` text — this is the source of truth for what the GDD requires now. Do not rely on any inline text in the story file (may be stale).

The governing ADR

Read `docs/architecture/[adr-file].md`. Extract:

• The full Decision section
• The Implementation Guidelines section (this is what the programmer follows)
• The Engine Compatibility section (post-cutoff APIs, known risks)
• The ADR Dependencies section

The control manifest

Read `docs/architecture/control-manifest.md`. Extract the rules for this story's layer:

• Required patterns
• Forbidden patterns
• Performance guardrails

Check: does the story's embedded Manifest Version match the current manifest header date? If they differ, use `AskUserQuestion` before proceeding:

• Prompt: "Story was written against manifest v[story-date]. Current manifest is v[current-date]. New rules may apply. How do you want to proceed?"
• Options:
• `[A] Update story manifest version and implement with current rules (Recommended)`
• `[B] Implement with old rules — I accept the risk of non-compliance`
• `[C] Stop here — I want to review the manifest diff first`

If [A]: edit the story file's `Manifest Version:` field to the current manifest date before spawning the programmer. Then read the manifest carefully for new rules. If [B]: edit the story file's `Manifest Version:` field to the current manifest date AND add a `Manifest-Note: Proceeded with old manifest rules on [date] — non-compliance risk accepted.` line to the story header. Read the manifest for new rules anyway. Note the decision in the Phase 6 summary under "Deviations". `/story-done` will include the Manifest-Note in its deviations section without re-checking staleness. If [C]: stop. Do not spawn any agent. Let the user review and re-run `/dev-story`.

Dependency validation

After extracting the **Dependencies** list from the story file, validate each:

1. Glob `production/epics/**/*.md` to find each dependency story file. 2. Read its `Status:` field. 3. If any dependency has Status other than `Complete` or `Done`:

• Use `AskUserQuestion`:
• Prompt: "Story '[current story]' depends on '[dependency title]' which is currently [status], not Complete. How do you want to proceed?"
• Options:
• `[A] Proceed anyway — I accept the dependency risk`
• `[B] Stop — I'll complete the dependency first`
• `[C] The dependency is done but status wasn't updated — mark it Complete and continue`
• If [B]: set story status to **BLOCKED** in session state and stop. Do not spawn any programmer agent.
• If [C]: ask "May I up