dev-story skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys automation,workflow,storygranularity,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

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 in tests/. Resolve the code root from engine.name (src/ Godot, Assets/ Unity, Source// 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; automationalwaysask 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/.md → ), 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.

storygranularity — it sets the expected implementation cycle: multi-day at coarse (give the programmer subagent longer working context), 1–2 days at balanced (default), 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

Before loading any context, resolve the workflow tier for this story's system (see the Workflow tier note above), then verify required files exist. Extract the ADR path from the story's ADR Governing Implementation field. The "If missing — full" column is the baseline; the tier columns relax it:

At full, 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. At standard/minimal, only a story that references an ADR whose file is missing or Proposed is set BLOCKED; a missing TR registry, or an absent-by-design ADR, does not block — implement against the story's acceptance criteria + the GDD/brief.

Read the story file and the TR registry simultaneously — these two are genuinely independent, unconditional reads. The governing ADR is not part of this batch — do not include it in the same parallel tool-call group as these two. Its own section below is a gate, not a read: whether the ADR gets opened at all depends on a freshness check that itself depends on the story file already being read. Do not start implementation until this phase is fully resolved:

The story file

Extract and hold:

guidance; this is the primary source for what the ADR decided

• Story title, ID, layer, type (Logic / Integration / Visual/Feel / UI / Config/Data)
• TR-ID — the GDD requirement identifier
• Governing ADR reference
• ADR Version stamp embedded in story header (absent on pre-stamp stories)
• ADR Decision Summary and Implementation Notes — the distilled ADR

• 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

Grep the story's TR-ID from docs/architecture/tr-registry.yaml (Grep pattern="id: " path="docs/architecture/tr-registry.yaml" output_mode="content" -A 6) rather than reading the whole cross-system registry. Read the matched entry's 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

Do not open the ADR by default. /create-stories already distilled it into this story's ADR Decision Summary + ## Implementation Notes, and its template states the contract outright: "This is what the programmer reads instead of the ADR." Re-reading the source here discards that work and, on an ADR past the 25k Read cap, costs a failed read plus offset/limit retries before implementation even starts.

Check freshness with one line, not one file. Resolve the ADR path from the story, then:

Grep pattern="^## Last Verified" path="docs/architecture/[adr-file].md" output_mode="content" -A 1

Compare that date against the story's ADR Version field:

Never treat an absent stamp as a stale one. A missing field means "unknown", and the fallback for unknown is the story, not a 35k-token re-read — the two staleness gates that already exist (/story-readiness on Manifest Version, /code-review post-implementation) are what make that safe.

On mismatch, use AskUserQuestion — same shape as the Manifest Version check below:

v[current-date]. Its decision may have changed. How do you want to proceed?"

• Prompt: "Story was written against ADR v[story-date]. The ADR is now

• Options:
• [A] Re-read the changed ADR sections and implement against current guidance (Recommended)
• [B] Implement from the story's summary — I accept the drift risk
• [C] Stop — I want to review the ADR diff first

If [A]: first check the ADR's size — Bash: wc -c "docs/architecture/[adr-file].md":

branch: at this size one read is cheaper than the multi-grep path (48.4k vs 52.1k tokens on a 16KB fixture) — per-call overhead outweighs the content saved. Targeted reading only pays for itself on files big enough to threaten the 25k-token Read cap.

• Under ~50KB — read the whole file with one Read call. Measured on this

never the whole file:

• ~50KB or larger — read only the sections that govern implementation,

Grep pattern="^## (Decision|Engine Compatibility|ADR Dependencies)" path="docs/architecture/[adr-file].md" output_mode="content" -A 40

Escalate to a bounded Read(offset, limit) on one section only if a scanned section cross-references material outside itself.

Then update the story's ADR Version to the current date so the next run is clean. If [B]: proceed on the summary; record it in the Phase 6 "Deviations" summary. If [C]: stop. Do not spawn any agent.

The control manifest

Read only this story's layer from docs/architecture/control-manifest.md — grep that one section (Grep pattern="^## Layer Rules" path="docs/architecture/control-manifest.md" output_mode="content" -A 40) rather than a full read of every layer. 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 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."

Engine reference

Read from project.yaml first, falling back to .claude/docs/technical-preferences.md for any key absent or empty:

engine.name when selecting an agent (see Phase 3)

• specialists. — the project's chosen specialist agents; read before**

the fallback when specialists is absent