---
name: dev-story
description: "Read a story file and implement it. Loads the full context (story, CDD requirement, ADR guidelines, control manifest), routes to the right programmer agent for the system and technology stack, implements the code and required evidence, 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
---

## User Guide

- When to use: Read a story file and implement it. Loads the full context (story, CDD requirement, ADR guidelines, control manifest), routes to the right programmer agent for the system and technology stack, implements the code and required evidence, and confirms each acceptance criterion. The core implementation skill — run after /story-readiness, before /code-review and /story-done.
- Inputs: Command arguments: `/dev-story [story-path]`; project artifacts referenced below; user decisions and approvals before writes.
- Outputs: Primary artifacts, reports, or conversation guidance described below; write files only after user approval.
- Memory-bank writes: None.
- Next steps: Follow the workflow hand-off or next-step guidance below; recommendations do not auto-run and require explicit user command/approval.

# 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 plus the story's required test, smoke, or evidence artifact.

---

## 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. Run `/create-epics` to generate it." |
| 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**:
  - Game types: Logic / Integration / Visual/Feel / UI / Config/Data
  - Product types: API / CLI / Data/Migration / Auth/Permission / Workflow / UI / Integration / Ops/Deployment / Config
- **TR-ID** — the CDD 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
CDD 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 Technology Compatibility section: Engine Compatibility (game) or Technology/Stack Compatibility (product) — 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]: read the manifest carefully for new rules anyway, and note the version mismatch in the Phase 6 summary under "Deviations".
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 update [dependency path] Status to Complete?" before continuing.
   - If [A]: note in Phase 6 summary under "Deviations": "Implemented with incomplete dependency: [dependency title] — [status]."

If a dependency file cannot be found: warn "Dependency story not found: [path]. Verify the path or create the story file."

---

### Technology reference
Read `standards/technical-preferences.md`:
- **[游戏专用]** `Engine:` value — determines game programmer agents
- **[通用产品]** `Language:` and `Framework:` values — determines product specialists
- Naming conventions
- Performance budgets
- Forbidden patterns

For product stories, map the `Language:` field to the closest available specialist:

| Language / stack hint | Specialist agent |
|---|---|
| Python, Django, Flask, FastAPI | `python-specialist` |
| TypeScript, JavaScript, Node, React, Vue | `typescript-specialist` |
| Rust, Cargo | `rust-specialist` |
| Go, Gin, Echo, Cobra | `go-specialist` |
| Unknown or mixed stack | `lead-programmer` |

---

## Phase 3: Route to the Right Programmer

Based on the story's **Layer**, **Type**, and **system name**, determine which
specialist to spawn via Task.

**[通用产品] Product routing** (when story type is API, CLI, Data/Migration, Auth/Permission, Workflow, UI, Integration, Ops/Deployment, or Config):
| Story Type | Agent(s) |
|---|---|
| API | `lead-programmer` + mapped language specialist |
| CLI | mapped language specialist |
| Data/Migration | mapped language specialist + `performance-analyst` |
| Auth/Permission | `security-engineer` + mapped language specialist |
| Workflow | `lead-programmer` + mapped language specialist |
| UI | `ui-programmer` + `ux-designer` |
| Integration | `lead-programmer` + `devops-engineer` |
| Ops/Deployment | `devops-engineer` |
| Config | mapped language specialist |

If the story matches a product type above, use this table and skip the game
primary routing table and game engine specialist step. Product routing examples:
- **API**: implement endpoint, request/response validation, and contract test.
- **Data/Migration**: implement schema or migration script plus fresh-instance
  migration test.
- **CLI**: implement command behavior plus smoke evidence for `--help` and the
  core command path.

**[游戏专用] Game routing** (when story type is Logic, Integration, Visual/Feel, UI, or Config/Data):

**Config/Data stories — skip agent spawning entirely:**
If the story's Type is `Config/Data`, no programmer agent or engine specialist is needed. Jump directly to Phase 4 (Config/Data note). The implementation is a data file edit — no routing table evaluation, no engine specialist.

### Primary agent routing table

| Story context | Primary agent |
|---|---|
| Foundation layer — any type | `engine-programmer` |
| Any layer — Type: UI | `ui-programmer` |
| Any layer — Type: Visual/Feel | `gameplay-programmer` (implements) |
| Core or Feature — gameplay mechanics | `gameplay-programmer` |
| Core or Feature — AI behaviour, pathfinding | `ai-programmer` |
| Core or Feature — networking, replication | `network-programmer` |
| Config/Data — no code | No agent needed (see Phase 4 Config note) |

### Game engine specialist — spawn as secondary for game code stories

Read the `Engine Specialists` section of `standards/technical-preferences.md`
to get the configured primary specialist. Spawn them alongside the primary agent
when the story involves engine-specific APIs, patterns, or the ADR has HIGH
engine risk.

| Engine | Specialist agents available |
|--------|----------------------------|
| Godot 4 | `godot-specialist`, `godot-gdscript-specialist`, `godot-shader-specialist` |
| Unity | `unity-specialist`, `unity-ui-specialist`, `unity-shader-specialist` |
| Unreal Engine | `unreal-specialist`, `ue-gas-specialist`, `ue-blueprint-specialist`, `ue-umg-specialist`, `ue-replication-specialist` |

**When engine risk is HIGH** (from the ADR or VERSION.md): always spawn the engine
specialist, even for non-engine-facing stories. High risk means the ADR records
assumptions about post-cutoff engine APIs that need expert verification.

---

## Phase 4: Implement

Spawn the chosen programmer agent(s) via Task with the full context package:

Provide the agent with:
1. The complete story file content
2. The current CDD requirement text (from TR registry)
3. The ADR Decision + Implementation Guidelines (verbatim — do not summarise)
4. The control manifest rules for this layer
5. The technology naming conventions and performance budgets:
   - Game: engine, signal/event names, frame and memory budgets
   - Product: language, framework, runtime, database, API/CLI naming conventions, latency or throughput budgets
6. Any technology-specific notes from the ADR compatibility section:
   - Game: Engine Compatibility
   - Product: Technology Compatibility or Stack Compatibility
7. The required test, smoke, or evidence path from the story's Test Evidence section
8. Explicit instruction: **implement this story and produce the required evidence**

The agent should:
- Create or modify files in `src/` following the ADR guidelines
- Respect all Required and Forbidden patterns from the control manifest
- Stay within the story's Out of Scope boundaries (do not touch unrelated files)
- Write clean, doc-commented public APIs

### Config/Data stories (no agent needed)

For Type: Config/Data stories, no programmer agent is required. The implementation
is editing a data file. Read the story's acceptance criteria and make the specified
changes to the data file directly. Note which values were changed and what they
changed from/to.

### Visual/Feel stories

Spawn `gameplay-programmer` to implement the code/animation calls. Note that
Visual/Feel acceptance criteria cannot be auto-verified — the "does it feel right?"
check happens in `/story-done` via manual confirmation.

---

## Phase 5: Write the Test

For story types with blocking automated evidence, the test must be written as
part of this implementation — not deferred to later.

- Game: Logic / Integration
- Product: API / Data/Migration / Auth/Permission / Workflow / Integration

Remind the programmer agent:

> "The required evidence for this story is at: `[path from Test Evidence section]`.
> The story cannot be closed via `/story-done` without it. Write the test
> or evidence alongside the implementation, not after."

Test requirements (from coding-standards.md):
- **[游戏专用]** File name: `[system]_[feature]_test.[ext]` (example:
  `combat_damage_test.gd`)
- **[通用产品]** File name: `test_[module]_[feature].py`,
  `[feature].test.ts`, `[feature]_test.rs`, or `[feature]_test.go` (example:
  `test_invoice_approval.py`)
- Function names: `test_[scenario]_[expected_outcome]`
- Each acceptance criterion must have at least one test function covering it
- No random seeds, no time-dependent assertions, no external I/O
- Test formula bounds, state transitions, schema constraints, API contracts, or
  permission boundaries from the CDD section that owns the story.

For **Visual/Feel** and game **UI** stories: no automated test is required unless
the story's Test Evidence section names one. Remind the agent to note what manual
evidence will be needed:
"Game playtest/sign-off evidence required at `production/qa/evidence/[slug]-evidence.md`."

For **Config/Data**, product **CLI**, product **Ops/Deployment**, and product
**Config** stories: create or update the smoke/evidence artifact named by the
story's Test Evidence section when the implementation changes behavior.

---

## Phase 6: Collect and Summarise

After the programmer agent(s) complete, collect:

- Files created or modified (with paths)
- Test, smoke, or evidence artifact created (path and number of tests/checks written)
- Any deviations from the story's Out of Scope boundary (flag these)
- Any questions or blockers the agent surfaced
- Any technology-specific risks the specialist flagged

Present a concise implementation summary:

```
## Implementation Complete: [Story Title]

**Files changed**:
- `src/[path]` — created / modified ([brief description])
- `tests/[path]` — test file ([N] test functions)

**Acceptance criteria covered**:
- [x] [criterion] — implemented in [file:function]
- [x] [criterion] — covered by test [test_name]
- [ ] [criterion] — DEFERRED: requires playtest, user test, deployment smoke, or manual evidence

**Deviations from scope**: [None] or [list files touched outside story boundary]
**Technology risks flagged**: [None] or [specialist finding]
**Blockers**: [None] or [describe]

Ready for: `/code-review [file1] [file2]` then `/story-done [story-path]`
```

---

## Phase 7: Update Session State

Silently append to `production/session-state/active.md`:

```
## Session Extract — /dev-story [date]
- Story: [story-path] — [story title]
- Files changed: [comma-separated list]
- Evidence written: [test/smoke/evidence path, or "None — manual evidence deferred"]
- Blockers: [None, or description]
- Next: /code-review [files] then /story-done [story-path]
```

Create `active.md` if it does not exist. Confirm: "Session state updated."

---

## Error Recovery Protocol

If any spawned agent (via Task) returns BLOCKED, errors, or cannot complete:

1. **Surface immediately**: Report "[AgentName]: BLOCKED — [reason]" to the user before continuing to dependent phases
2. **Assess dependencies**: Check whether the blocked agent's output is required by subsequent phases. If yes, do not proceed past that dependency point without user input.
3. **Offer options** via AskUserQuestion with choices:
   - Skip this agent and note the gap in the final report
   - Retry with narrower scope
   - Stop here and resolve the blocker first
4. **Always produce a partial report** — output whatever was completed. Never discard work because one agent blocked.

Common blockers:
- Input file missing (story not found, CDD absent) → redirect to the skill that creates it
- ADR status is Proposed → do not implement; run `/architecture-decision` first
- Scope too large → split into two stories via `/create-stories`
- Conflicting instructions between ADR and story → surface the conflict, do not guess
- Manifest version mismatch → show diff to user, ask whether to proceed with old rules or update story first

## Collaborative Protocol

- **File writes are delegated** — all source code, test files, and evidence docs are written by sub-agents spawned via Task. Each sub-agent enforces the "May I write to [path]?" protocol individually. This orchestrator does not write files directly.
- **Load before implementing** — do not start coding until all context is loaded
  (story, TR-ID, ADR, manifest, technology preferences). Incomplete context produces code
  that drifts from design.
- **The ADR is the law** — implementation must follow the ADR's Implementation
  Guidelines. If the guidelines conflict with what seems "better," flag it in the
  summary rather than silently deviating.
- **Stay in scope** — the Out of Scope section is a contract. If implementing
  the story requires touching an out-of-scope file, stop and surface it:
  "Implementing [criterion] requires modifying [file], which is out of scope.
  Shall I proceed or create a separate story?"
- **Required evidence is not optional** — do not mark implementation complete
  without the story type's required test, smoke, or evidence artifact
- **Visual/Feel criteria are deferred, not skipped** — mark them as DEFERRED
  in the summary; they will be manually verified in `/story-done`
- **Ask before large structural decisions** — if the story requires an
  architectural pattern not covered by the ADR, surface it before implementing:
  "The ADR doesn't specify how to handle [case]. My plan is [X]. Proceed?"

---

## Recommended Next Steps

- Run `/code-review [file1] [file2]` to review the implementation before closing the story
- Run `/story-done [story-path]` to verify acceptance criteria and mark the story complete
- After all sprint stories are done: run `/team-qa sprint` for the full QA cycle before advancing the project stage