dev-story

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,story_granularity,qa.level,testing.strict,system_overrides` Resolved above — use as-is. No block → defaults in `.claude/docs/config-resolution.md`. # 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 ``` **At `workflow: minimal`** the loop is `/dev-story [path]` → `/story-done [path]`: no QA plan, readiness check or sprint. `/story-done` names the next story. **With a sprint plan, 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 under the project's **code root** + test file under the engine's **test root** (`tests/` Godot, `Assets/Tests/` Unity, `Source/<Module>/Private/Tests/` Unreal — `.claude/docs/directory-structure.md`). Resolve the code root from `engine.name` (`src/` Godot, `Assets/` Unity, `Source/<Module>/` Unreal) per `.claude/docs/code-root-resolution.md`. --- Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt). **Workflow tier**: resolved per the story's system (per `.claude/docs/workflow-modes.md`) — **the GDD filename stem** of the story's `GDD:` path (`design/gdd/<stem>.md` → `<stem>`), with the `[system]` segment of its `TR-[system]-NNN` ID accepted only as a fallback alias: use the `system_overrides` row for that system if the block lists one, else the project value. Resolve it at the start of Phase 2 (the story header is read there) and apply it to the prerequisite gate. **`story_granularity`** — it sets the expected implementation cycle: **multi-day** at `coarse` (the default, via `rigor: minimal`; give the programmer subagent longer working context), **1–2 days** at `balanced` (`rigor: standard`), **hours** at `fine` (tighter context). It does not change the prerequisite gate. **`qa.level`**: controls whether the programmer brief carries a test requirement. At `minimal`, omit the "Test requirement" line (Phase 4 item 7) — tests are not required; at `standard`, include the per-type test requirement; at `full`, also pass a coverage target. Distinct from `workflow: minimal`. When tests are not required (`minimal`), the Phase 5 `testing.strict` gate is a no-op. ## 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 **Read `references/2-load-context.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase. ## Phase 3: Route to the Right Programmer **Read `references/3-route.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase. ## Phase 4: Implement **Read `references/4-implement.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase. ## Phase 5: Test Evidence Requirements **Read `references/5-test-evidence.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase. ## Phase 6: Collect and Summarise **Read `references/6-collect.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase. ## Phase 7: Update Session State **Read `references/7-session-state.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase. ## Error Recovery Protocol **First, verify the artifact.** If the return contract named a path, check the path exists before treating the phase as done — **a named artifact that is not on disk is a failed phase, however fluent the response reads.** An agent can burn a full phase and return a plausible preamble having written nothing, which is neither BLOCKED nor an error nor "cannot complete", so the trigger below never fires. Resume it naming the unmet contract; the context is usually still there. If any spawned agent returns BLOCKED, errors, or cannot complete: **surface it immediately, don't proceed past a dependency it blocks, and always produce a partial report.** Full procedure: `.claude/docs/error-recovery-protocol.md`. Common blockers: - Input file missing (story not found, GDD absent) → redirect to the skill that creates it - A *referenced* ADR's status is Proposed → do not implement; accept it with `/architecture-decision accept ADR-NNNN` once decided (a story that references no ADR is not blocked on this — see Phase 2) - 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 **Applies in `collaborative` mode (the default).** For `guided` and `autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below describe what collaborative mode requires, not universal behavior. - **File writes are delegated** — all source code, test files, and evidence docs are written by sub-agents spawned via `Agent`. Each sub-agent enforces the "May I write to [path]?" protocol individually. This orchestrator writes only the following, each after an ask that names it: - the story's `Status:` / `Last Updated:` and its `production/sprint-status.yaml` entry — the one "May I mark this story In Progress?" ask (Phase 2) - the story's `ADR Version`, `**ADR Decision Summary**` and `## Implementation Notes` (ADR mismatch option [A]), and its `Manifest Version:` / `Manifest-Note:` (manifest option [A] or [B]) — each option names that edit, so choosing it is the ask - a dependency story's `Status: Complete` (dependency option [C], then "May I update [dependency path] Status to Complete?") - a Config/Data story's data file ("May I write to [path]?") - on Unity, `Assets/Scripts/ScreenshotOnArg.cs`, written verbatim from `.claude/docs/run-and-observe.md` ("May I write `Assets/Scripts/ScreenshotOnArg.cs`?", Phase 6) The session-state checkpoint in `production/session-state/active.md` is the one write made without an ask. - **Load before implementing** — do not start coding until all context is loaded (story, TR-ID, ADR, manifest, engine prefs). 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?" - **Test is not optional for Logic/Integration** (at `qa.level: standard`/`full`) — do not mark implementation complete without the test file existing. At `qa.level: minimal` tests are not required and this does not apply. - **Visual/Feel and UI looks are observed, not deferred** — the Phase 6 run retains the screenshot (each screen touched for UI; Visual/Feel also needs a lead sign-off before `/story-done`), and `qa.level` never waives either. Only the *feel* half of a Visual/Feel criterion — timing, weight, responsiveness — is marked DEFERRED, for `/team-qa` - **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 - At `standard`/`full`, run `/code-review [file1] [file2]` to review the implementation before closing the story (not part of the minimal loop) - Run `/story-done [story-path]` to verify acceptance criteria and mark the story complete - With a sprint plan, after all sprint stories are done: run `/team-qa sprint` for the full QA cycle before advancing the project stage. At `minimal`, `/story-done` names the next story instead