Dev Story

🌱 ShiningPlague-adopted. Originally Donchitos; battle-tested on a shipped Godot project. Upstream procedure preserved + project path corrections + engine-conditional routing.

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 /qa-plan [sprint] to execute the full QA cycle.

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

If an artifact named here is absent: say so plainly in one line, skip that step, and continue. Never invent the file to satisfy a checklist, and never fail a close because an optional artifact was never created.

Project Paths

Project Context

• Engine: {{ENGINE}} (from .claude/docs/technical-preferences.md) — routes to the matching engine specialist (e.g. godot-gdscript-specialist for Godot 4 + GDScript)
• Technical preferences at .claude/docs/technical-preferences.md
• Coding standards/gotchas at .claude/docs/ (e.g. godot-gotchas.md for Godot projects)
• Architecture principles in CLAUDE.md § Architecture principles

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 ADR path from story's ADR Governing Implementation field, then check:

"Missing" includes "seeded but unwritten." The installer seeds the TR registry and the control manifest, so existence proves nothing — a copy still carrying the scaffold-seed: unwritten marker (or a tr-registry.yaml whose requirements: list is still empty) is the blank skeleton. Treat it as missing and take the row's action.

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

Read all of the following simultaneously:

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
• Out of Scope boundaries
• Test Evidence — required test file path
• Dependencies — what must be DONE before this story

The TR registry

Read docs/architecture/tr-registry.yaml. Look up story's TR-ID. Read current requirement text — source of truth.

The governing ADR

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

• Full Decision section
• Implementation Guidelines section
• Engine Compatibility section (post-cutoff APIs, known risks)
• ADR Dependencies section

The control manifest

Read docs/architecture/control-manifest.md. Extract rules for this layer:

• Required patterns
• Forbidden patterns
• Performance guardrails

Check: does story's embedded Manifest Version match current manifest header date?

If they differ, use AskUserQuestion:

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

Dependency validation

After extracting Dependencies, validate each:

1. Glob production/epics/**/*.md to find each dependency story file
2. Read its Status: field
3. If any dependency Status not Complete/Done:
   • Use AskUserQuestion: "Story depends on [dependency] which is [status], not Complete. How proceed?"
   • Options: [A] Proceed anyway / [B] Stop — complete dependency first / [C] Mark dependency Complete and continue

Engine reference

Read .claude/docs/technical-preferences.md:

• Engine: — {{ENGINE}} (e.g. Godot 4.x)
• Naming conventions
• Performance budgets
• Forbidden patterns

Phase 3: Route to the Right Programmer

Based on story's Layer, Type, and system name:

Config/Data stories — skip agent spawning entirely. Jump directly to Phase 4. The implementation is a data file edit.

Primary agent routing table

Engine specialist — always spawn as secondary for code stories

Route by {{ENGINE}} (from .claude/docs/technical-preferences.md). For Godot 4 projects, default secondary = godot-gdscript-specialist.

When engine risk is HIGH (from ADR or VERSION.md): always spawn engine specialist, even for non-engine-facing stories.

Phase 4: Implement

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

1. The complete story file content
2. The current GDD requirement text (from TR registry)
3. The ADR Decision + Implementation Guidelines (verbatim — don't summarise)
4. The control manifest rules for this layer
5. The engine naming conventions and performance budgets
6. Any engine-specific notes from ADR Engine Compatibility
7. The test file path that must be created
8. Explicit instruction: implement this story and write the test

Agent should:

• Create or modify files in src/ following ADR guidelines
• Respect all Required and Forbidden patterns from control manifest
• Stay within story's Out of Scope boundaries
• Write clean, doc-commented public APIs

Config/Data stories (no agent needed)

For Type: Config/Data, implementation is editing a data file. Read story's acceptance criteria and make specified changes directly. Note values changed.

Visual/Feel stories

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

Phase 5: Write the Test

For Logic and Integration stories, test must be written as part of this implementation — not deferred.

Remind the programmer agent:

"Test file for this story is required at: [path from Test Evidence section]. Story cannot be closed via /story-done without it. Write the test alongside implementation."

Test requirements (the naming and structure rules live in .claude/rules/test-standards.md):

• File name: [system]_[feature]_test.[engine test extension] (e.g. .gd for Godot, .cs for Unity)
• Function names: test_[system]_[scenario]_[expected_result] — the pattern in .claude/rules/test-standards.md
• Each acceptance criterion must have at least one test function
• No random seeds, no time-dependent assertions, no external I/O
• Test the formula bounds from GDD Formulas section

For Visual/Feel and UI stories: no automated test. Remind agent to note: "Evidence doc required at production/qa/evidence/[slug]-evidence.md."

For Config/Data stories: no test file. A smoke check serves as evidence.

Phase 6: Collect and Summarise

After programmer agent(s) complete, collect:

• Files created/modified (with paths)
• Test file created (path + number of test functions)
• Any deviations from story's Out of Scope boundary
• Any questions or blockers
• Any engine-specific risks the specialist flagged

Present concise 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 (Visual/Feel)

**Deviations from scope**: [None] or [list files touched outside boundary]
**Engine 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]
- Test written: [path, or "None — Visual/Feel/Config story"]
- Blockers: [None, or description]
- Next: /code-review [files] then /story-done [story-path]

Error Recovery Protocol

If any spawned agent returns BLOCKED, errors, or cannot complete:

1. Surface immediately: "[AgentName]: BLOCKED — [reason]"
2. Assess dependencies: If output required by subsequent phases, don't proceed
3. Offer options via AskUserQuestion: skip / retry narrower scope / stop and resolve
4. Always produce partial report — never discard work

Common blockers:

• Input file missing → redirect to skill that creates it
• ADR status is Proposed → run /architecture-decision first
• Scope too large → split via /create-stories
• Conflicting ADR/story instructions → surface, don't guess
• Manifest version mismatch → show diff, ask

Collaborative Protocol

• File writes are delegated — all source code, test files, evidence docs written by sub-agents spawned via Task. Each sub-agent enforces "May I write to [path]?" individually.
• Load before implementing — don't start coding until all context loaded
• The ADR is the law — implementation must follow ADR Implementation Guidelines. If guidelines conflict with what seems "better," flag in summary
• Stay in scope — Out of Scope is a contract. If implementing requires touching out-of-scope file, stop and surface
• Test is not optional for Logic/Integration — don't mark complete without test file
• Visual/Feel criteria are deferred, not skipped
• Ask before large structural decisions — if story requires pattern not covered by ADR, surface

Recommended Next Steps

• Run /code-review [file1] [file2] to review before closing
• Run /story-done [story-path] to verify acceptance criteria and mark complete
• After all sprint stories done: run /qa-plan [sprint] for the full QA cycle