Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/pipeline/dev-story.md

# Skill Test Spec: /dev-story

## Skill Summary

`/dev-story` implements one story. It finds the story (argument, else the active
story in `production/session-state/active.md`), resolves the workflow tier for the
story's system, verifies required inputs per tier (TR registry, governing ADR,
control manifest), reads the ADR's `## Status`, `## Last Verified` and `## Date` in
one grep — a `Proposed`, `Deprecated` or `Superseded` status blocks the story at
every tier, while a story whose ADR field reads `N/A` references none — and checks ADR
freshness by comparing the story's `ADR Version` with the ADR's current version
(`Last Verified`, else `Date`, else `unversioned` — the rule `/create-stories`
stamps with). It checks the story's `Manifest Version` and its dependencies, asks
to mark the story `In Progress`, and routes implementation to a programmer agent
plus the project's engine specialist. It does not write source code itself, and
every file it does write — story fields, `sprint-status.yaml`, a dependency's
`Status`, a Config/Data file, Unity's `ScreenshotOnArg.cs` — follows an ask that
names it; only the session-state checkpoint is written without one.

After the agent returns it verifies the agent finished, runs the engine parse
check, launches the build to observe anything player-visible (`Run result:`
line), prints an "Implementation Complete" summary and overwrites the CHECKPOINT
block in `active.md`, whose **Next step** follows the result: `/story-done` after
Implementation Complete, `/dev-story` to resume after INCOMPLETE, the unblocking
action after BLOCKED. It never closes the story it implements — `/story-done`
does that; `/code-review` is recommended first at `standard`/`full`. At
`qa.level: minimal` a Logic or Integration story's test requirement is waived and
the waiver is printed; a UI or Visual/Feel story's screenshot is never waived, and
the run-and-observe step runs at every level.

---

## Static Assertions (Structural)

Checked against the SKILL.md by `/skill-test spec` — no fixture needed.

- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
- [ ] Has ≥2 phase headings
- [ ] Contains status keywords: BLOCKED, INCOMPLETE, In Progress, NOT VERIFIED
- [ ] Contains "May I write" collaborative protocol language (its own asks for the files it writes; source and tests delegated to sub-agents)
- [ ] Has a next-step handoff at the end (`/story-done`, with `/code-review` first at standard/full)
- [ ] Documents per-tier input requirements (`full` / `standard` / `minimal`)
- [ ] Notes that implementation is delegated to specialist agents (not done directly)

---

## Director Gate Checks

No director gates. `/dev-story` spawns implementation agents (a primary programmer
and the engine specialist), not director review gates, and does not resolve
`review_mode`. Code review is the separate `/code-review` skill, named as the next
step at `standard`/`full`.

---

## Test Cases

### Case 1: Happy Path — Logic story implemented at full workflow

**Fixture:**
- `project.yaml`: `engine.name: Godot`, `specialists.code: godot-gdscript-specialist`,
  `modes.workflow: full`, `qa.level: standard`
- `production/epics/combat/story-001-damage-calc.md`: `Status: Ready`, Layer Core,
  Type Logic, `Requirement: TR-combat-001`, `ADR Governing Implementation: ADR-0003`,
  an `ADR Version` equal to ADR-0003's `## Last Verified` date, a `Manifest Version`
  equal to the manifest header date, Dependencies None, Test Evidence
  `tests/unit/combat/combat_damage_calc_test.gd`
- `docs/architecture/tr-registry.yaml` has `TR-combat-001`; ADR-0003 exists and is
  Accepted; `docs/architecture/control-manifest.md` exists
- `production/sprint-status.yaml` does not exist

**Input:** `/dev-story production/epics/combat/story-001-damage-calc.md`

**Expected behavior:**
1. Reads the story and greps `id: TR-combat-001` from the registry
2. Greps ADR-0003's `^## (Status|Last Verified|Date)` — Status is Accepted and its
   current version (the `Last Verified` date) matches the story, so the ADR is not read
3. Greps `^## Core Layer Rules` from the manifest; Manifest Version matches, no ask
4. Asks "May I mark this story In Progress?", naming the story file (and not the
   absent `sprint-status.yaml`); on yes sets the story's `Status:` to `In Progress`
   and its `Last Updated:`; prints "Sprint status not updated:
   production/sprint-status.yaml absent"
5. Spawns `gameplay-programmer` with `godot-gdscript-specialist` as secondary,
   briefing the story path, TR-ID lookup, the story's ADR Decision Summary and
   Implementation Notes inline, the Core layer rules, and the test file path
   with the test requirement
6. Confirms the agent finished, runs the Godot parse check and reports its exit code
7. Prints "Implementation Complete: [title]" with files, test function count,
   Verification and a `Run result:` line; next step `/code-review` then `/story-done`
8. Overwrites the `<!-- CHECKPOINT -->` block in `active.md`

**Assertions:**
- [ ] ADR-0003 is not read in full when its `Last Verified` matches the story's `ADR Version`
- [ ] The In Progress ask names the story file; `Status:` becomes `In Progress` only after it and before any agent is spawned, and the sprint-status-absent line is printed
- [ ] Primary is `gameplay-programmer`; secondary comes from `specialists.code`, not the roster table
- [ ] The ADR guidance is passed inline, not as the ADR path
- [ ] The brief names `tests/unit/combat/combat_damage_calc_test.gd` (`[system]_[feature]_test.gd`) and requires one test per acceptance criterion
- [ ] The parse check's command and exit code are reported, and exactly one `Run result:` line appears
- [ ] Story is NOT marked Complete; the handoff is `/code-review` then `/story-done`
- [ ] The CHECKPOINT block in `active.md` is overwritten, not appended to

---

### Case 2: Failure Path — Referenced ADR is Proposed

**Fixture:**
- `project.yaml`: `modes.workflow: standard`
- Story file with `Status: Ready` and `ADR Governing Implementation: ADR-0005`
- `docs/architecture/adr-0005-*.md` exists with `## Status` Proposed

**Input:** `/dev-story production/epics/[epic-slug]/story-[NNN]-[slug].md`

**Expected behavior:**
1. Skill reads the story and resolves the `standard` tier
2. Skill determines that the referenced ADR-0005 is Proposed
3. Story is set BLOCKED in session state; no programmer agent is spawned
4. Output names ADR-0005 and recommends `/architecture-decision accept ADR-0005`
5. A partial report is produced; the story file's `Status:` is not changed

**Assertions:**
- [ ] The Proposed status is read from ADR-0005's `## Status` section, not inferred
- [ ] No programmer or engine-specialist agent is spawned
- [ ] Output names ADR-0005 and recommends `/architecture-decision`
- [ ] The story header stays `Status: Ready`, and no "May I mark this story In Progress?" ask is shown
- [ ] BLOCKED is recorded in session state, and the checkpoint's **Next step** names `/architecture-decision accept ADR-0005` — not `/story-done`

---

### Case 2b: Failure Path — Proposed ADR at the `full` tier

The `full` column of the file-check table has its own STOP rule, so the
`standard` case above does not exercise it.

**Fixture:**
- `project.yaml`: `modes.workflow: full`
- Story file with `Status: Ready`, `ADR Governing Implementation: ADR-0005` and an
  `ADR Version` older than ADR-0005's `## Last Verified` date
- `docs/architecture/adr-0005-*.md` exists with `## Status` Proposed;
  `docs/architecture/tr-registry.yaml` and the control manifest exist

**Input:** `/dev-story production/epics/[epic-slug]/story-[NNN]-[slug].md`

**Expected behavior:**
1. Skill greps ADR-0005's `^## (Status|Last Verified|Date)` and reads `Proposed`
2. It stops before the freshness comparison: "ADR [path] is still Proposed. Accept
   it with `/architecture-decision accept ADR-0005` before implementing."
3. Story is set BLOCKED in session state; no programmer agent is spawned

**Assertions:**
- [ ] The stop happens at `full`
- [ ] The Status decides before the freshness check: no ADR-version mismatch prompt is shown although the versions differ, and the ADR is not read beyond the one Grep
- [ ] No programmer or engine-specialist agent is spawned, and the story stays `Status: Ready`

---

### Case 3: ADR changed since the story was written

**Fixture:**
- `project.yaml`: `engine.name: Godot`, `modes.workflow: full`
- Story file with `Status: Ready`, Type Logic, `Requirement: TR-combat-002`,
  `ADR Governing Implementation: ADR-0004`, an `ADR Version` older than ADR-0004's
  `## Last Verified` date, a `Manifest Version` equal to the manifest header date,
  Dependencies None
- `docs/architecture/tr-registry.yaml` has `TR-combat-002`; ADR-0004 exists with
  `## Status` Accepted and is under 50KB; `docs/architecture/control-manifest.md`
  exists
- User picks `[A]` at the prompt

**Input:** `/dev-story production/epics/[epic-slug]/story-[NNN]-[slug].md`

**Expected behavior:**
1. `Grep "^## (Status|Last Verified|Date)"` on ADR-0004 reads Accepted and a
   `Last Verified` date different from the story's `ADR Version`
2. `AskUserQuestion`: "Story was written against ADR v[story-date]. The ADR is now
   v[current-date]. Its decision may have changed. How do you want to proceed?"
   with `[A] Re-read the changed ADR sections…` (naming the refresh of this story's
   ADR summary and ADR Version) / `[B] Implement from the story's summary…` /
   `[C] Stop…`
3. On [A]: checks the size with `wc -c`; under ~50KB, reads the ADR with one `Read`
4. Sets the story's `ADR Version` to ADR-0004's `Last Verified` date and replaces
   its ADR Decision Summary and Implementation Notes with the re-read guidance
5. Spawns the programmer with that guidance inline

**Assertions:**
- [ ] The mismatch prompt is shown before any agent is spawned
- [ ] All three options ([A] re-read / [B] accept drift / [C] stop) are offered, and [A] names the story edit it makes
- [ ] On [A] the size is checked and a sub-50KB ADR is read in a single `Read`
- [ ] The story's `ADR Version` becomes ADR-0004's `Last Verified` date — not today's date — before the programmer is spawned
- [ ] The programmer brief carries the freshly read Decision guidance inline, not the summary the story held before [A]

**Fixture (Date fallback):**
- As above, but ADR-0004 has no `## Last Verified` section; its `## Date` equals the
  story's `ADR Version` (the value `/create-stories` stamped from it)

**Expected behavior (Date fallback):**
1. The same Grep finds no `Last Verified`, so the ADR's current version is its `## Date`
2. That matches the story's `ADR Version`: the story is trusted, no prompt is shown,
   and the ADR is not read

**Assertions (Date fallback):**
- [ ] No mismatch prompt is shown — an ADR stamped from its `## Date` is not treated as stale for lacking `## Last Verified`
- [ ] ADR-0004 is not read beyond the one Grep

---

### Case 4: Edge Case — No argument; reads from session state

**Fixture:**
- No argument is provided
- `production/session-state/active.md` references an active story file
- That story file exists with `Status: In Progress`

**Input:** `/dev-story` (no argument)

**Expected behavior:**
1. Skill detects no argument is provided
2. Skill reads `production/session-state/active.md`
3. Skill finds the active story reference
4. Skill confirms with user: "Continuing work on [story title] — is that correct?"
5. After confirmation, skill proceeds with that story

**Assertions:**
- [ ] Skill reads session state when no argument is provided
- [ ] Skill confirms the active story with the user before proceeding
- [ ] Skill does NOT silently assume the active story without confirmation

**Fixture (no active story):**
- No argument is provided
- `production/session-state/active.md` names no active story
- `production/epics/` holds two stories with `Status: Ready` and one `In Progress`

**Expected behavior (no active story):**
1. Skill asks "Which story are we implementing?"
2. It globs `production/epics/**/*.md` and lists the two `Status: Ready` stories

**Assertions (no active story):**
- [ ] The question is asked instead of guessing a story
- [ ] Only the `Status: Ready` stories are listed

---

### Case 5: Minimal tier, Logic story — tests waived

**Fixture:**
- `project.yaml`: `engine.name: Godot`, `modes.workflow: minimal`, `qa.level: minimal`
- Story Type Logic with `Requirement: Brief MVP feature 1` and ADR fields
  `N/A (minimal — no ADRs)`
- No TR registry, no ADRs, no control manifest
- `docs/engine-reference/godot/VERSION.md` rates the pinned version HIGH risk

**Input:** `/dev-story production/epics/[slug]/story-001-[slug].md`

**Expected behavior:**
1. Phase 2 does not stop or set BLOCKED for the absent registry, ADR or manifest
2. Before spawning, prints a `Briefing omits: …` line naming the TR registry, the
   ADR guidance and the control manifest
3. Spawns `gameplay-programmer` plus the engine specialist (VERSION.md risk HIGH)
4. The brief omits the test requirement and tells the agent: "Do not write a test
   file for this story — test evidence is waived at `qa.level: minimal`."
5. Phase 5 is skipped; the summary prints "Test evidence: waived at
   `qa.level: minimal` — no test was required or written for this story."
6. Run-and-observe still runs and prints one `Run result:` line
7. Next step is `/story-done [story-path]` directly — no `/code-review`

**Assertions:**
- [ ] No STOP or BLOCKED for the absent TR registry, ADR or manifest at `minimal`
- [ ] The `Briefing omits:` line names all three dropped inputs, the ADR included
- [ ] The engine specialist is spawned because VERSION.md rates the risk HIGH
- [ ] The test waiver is stated to the agent and printed in the summary; no tests row or "run your test suite" paragraph appears
- [ ] A `Run result:` line is printed — run-and-observe is not waived
- [ ] The handoff is `/story-done` with no `/code-review` step

---

### Case 5b: Minimal tier, UI story — the screenshot is still required

**Fixture:**
- `project.yaml`: `engine.name: Godot`, `modes.workflow: minimal`, `qa.level: minimal`
- Story Type UI with `Requirement: Brief MVP feature 2` and ADR fields
  `N/A (minimal — no ADRs)`
- No TR registry, no ADRs, no control manifest

**Input:** `/dev-story production/epics/[slug]/story-002-[slug].md`

**Expected behavior:**
1. Spawns `ui-programmer`; the brief has no test item and no "Do not write a test
   file" sentence — the test requirement only ever covered Logic and Integration
2. The summary prints "Retained screenshot required under
   `production/qa/evidence/[story-slug]/` before this story can be closed…"
3. Run-and-observe retains a screenshot under `production/qa/evidence/[story-slug]/`
   and prints `Run result: OBSERVED — …` with the path
4. Next step is `/story-done [story-path]`

**Assertions:**
- [ ] The UI story is not told its evidence is waived — neither in the brief nor as a "Test evidence: waived" line in the summary
- [ ] The screenshot-required line is printed at `qa.level: minimal`
- [ ] `Run result: OBSERVED` names a retained screenshot; a `NOT VERIFIED` result would be reported as a blocker, not a note
- [ ] The handoff is `/story-done` with no `/code-review` step

---

### Case 6: Unity — code under `Assets/`, capture script asked for

**Fixture:**
- `project.yaml`: `engine.name: Unity`, `specialists.code: unity-specialist`,
  `specialists.ui: unity-ui-specialist`, `commands.smoke` and `commands.run` set,
  `modes.workflow: minimal`, `qa.level: minimal`
- Story Type UI (an inventory screen) with `Requirement: Brief MVP feature 3` and
  ADR fields `N/A (minimal — no ADRs)`
- The project has `Assets/` and no `src/`; no `ScreenshotOnArg.cs` exists under `Assets/`
- `docs/engine-reference/unity/VERSION.md` rates the pinned version HIGH risk

**Input:** `/dev-story production/epics/[slug]/story-003-[slug].md`

**Expected behavior:**
1. Spawns `ui-programmer` with `unity-specialist` (`specialists.code`) and
   `unity-ui-specialist` (`specialists.ui`, for a UI story)
2. The brief sends the code to `Assets/Scripts/<System>/`, the Unity code root
3. Verification runs `commands.smoke` and reports its exit code
4. Before launching, globs `Assets/**/ScreenshotOnArg.cs`, finds none and asks
   "May I write `Assets/Scripts/ScreenshotOnArg.cs`?"; on yes writes the script
   verbatim from `.claude/docs/run-and-observe.md`
5. Launches the built player with `--scene`/`--screenshot` and prints
   `Run result: OBSERVED — …` with the retained path

**Assertions:**
- [ ] No file is written under `src/` — the Godot row is not a default
- [ ] Both specialists come from the `specialists` block, not the roster table
- [ ] `ScreenshotOnArg.cs` is written only after its ask, at `Assets/Scripts/`, exactly as run-and-observe.md gives it
- [ ] If the user declines that ask, the result is `Run result: NOT VERIFIED — ScreenshotOnArg.cs not written`, not an observation
- [ ] Verification names `commands.smoke` and its exit code

---

### Case 7: Engine unset — the code root is unresolved, nothing is written

**Fixture:**
- `project.yaml` has no `engine` block; `.claude/docs/technical-preferences.md`
  reads `Engine: [TO BE CONFIGURED]`
- The project has none of `src/`, `Assets/` or `Source/`
- `modes.workflow: minimal`; the story is Type Logic

**Input:** `/dev-story production/epics/[slug]/story-001-[slug].md`

**Expected behavior:**
1. The code root cannot be resolved (`.claude/docs/code-root-resolution.md`: no
   `engine.name`, no legacy `Engine:` value, no single unambiguous root in the tree)
2. No source file is written, and the output says the code root is unresolved

**Assertions:**
- [ ] No file is created under `src/` or any other guessed root
- [ ] The output names the unresolved code root as the reason nothing was written
- [ ] "Implementation Complete" is not printed

---

### Case 8: Dependency marked Complete through option [C]

**Fixture:**
- `project.yaml`: `engine.name: Godot`, `modes.workflow: minimal`, `qa.level: minimal`
- `story-003` lists `story-002` under Dependencies; `story-002` has
  `Status: In Progress`
- At the dependency prompt the user picks `[C]`, then approves the update

**Input:** `/dev-story production/epics/[slug]/story-003-[slug].md`

**Expected behavior:**
1. Reads story-002's `Status:` and asks: "Story '[story-003 title]' depends on
   '[story-002 title]' which is currently In Progress, not Complete. How do you
   want to proceed?" with `[A] Proceed anyway` / `[B] Stop` / `[C] The dependency
   is done but status wasn't updated — mark it Complete and continue`
2. On [C] asks "May I update `production/epics/[slug]/story-002-[slug].md` Status
   to Complete?"
3. On yes sets story-002's `Status:` to `Complete`, then continues with story-003

**Assertions:**
- [ ] The dependency prompt comes before any agent is spawned
- [ ] story-002 is edited only after the "May I update … Status to Complete?" ask, and only its `Status:` changes
- [ ] story-003 itself is not marked Complete — it is set In Progress, after its own ask
- [ ] Had the user picked `[B]`, story-003 would be BLOCKED in session state and no agent spawned

### Case 9: The agent stops early — INCOMPLETE, and the checkpoint says resume

**Fixture:**
- `project.yaml`: `engine.name: Godot`, `modes.workflow: minimal`, `qa.level: minimal`
- Story Type Logic, `Status: Ready`, ADR fields `N/A (minimal — no ADRs)`
- The programmer agent reports that it hit its turn limit after adding
  `src/combat/damage.gd`, which calls a helper it never defined

**Input:** `/dev-story production/epics/[slug]/story-001-[slug].md`

**Expected behavior:**
1. Phase 6 treats the story as INCOMPLETE: the headline says so, lists what exists,
   names the undefined helper, and offers to resume the agent
2. "Implementation Complete" is not printed and the story's `Status:` is not advanced
3. The checkpoint's **Next step** reads `/dev-story [story-path] — resume: [the
   undefined helper]`

**Assertions:**
- [ ] No "Implementation Complete" and no `Status:` change past `In Progress`
- [ ] The checkpoint's **Next step** is `/dev-story [story-path]` to resume — never `/story-done`, which `/help` reads as "the work is written"

---

### Case 10: `full` tier, a story with no governing ADR (`ADR: N/A`)

**Fixture:**
- `project.yaml`: `engine.name: Godot`, `modes.workflow: full`
- Story `Status: Ready`, Type Logic, `ADR Governing Implementation: N/A — no
  architectural pattern required` (what `/create-stories` writes for a
  requirement `/create-epics` flagged as untraced)
- `docs/architecture/tr-registry.yaml` has the story's TR-ID; the control manifest exists

**Input:** `/dev-story production/epics/[slug]/story-004-[slug].md`

**Expected behavior:**
1. Phase 2 reads the ADR field as `N/A`: the story references no ADR, so the `full`
   column's "ADR file [path] not found" STOP does not fire and no ADR is grepped
2. The story is not set BLOCKED; implementation proceeds, with the ADR guidance
   named in the `Briefing omits:` line

**Assertions:**
- [ ] No STOP and no BLOCKED for the `N/A` ADR field at `full`
- [ ] No ADR file is looked up for `N/A`
- [ ] Variant — the story names `ADR-0006`, whose `## Status` reads `Superseded by ADR-0009`: the story is BLOCKED at every tier, naming ADR-0009 and saying to edit its ADR field (`/create-stories` never rewrites an existing story)

---

## Protocol Compliance

- [ ] Does NOT write source code directly — delegates to specialist agents
- [ ] Resolves the workflow tier and verifies required inputs before any agent is spawned
- [ ] Mismatch and dependency prompts (`AskUserQuestion`) come before implementation
- [ ] Every file the skill itself writes — story fields, `sprint-status.yaml`, a dependency's `Status`, a Config/Data file, `ScreenshotOnArg.cs` — follows an ask that names it; only the `active.md` checkpoint is written without one
- [ ] Code is written only under the resolved code root; an unresolved root writes nothing
- [ ] Skipped phases and dropped briefing items are announced in the output
- [ ] Never emits "Implementation Complete" for an agent that stopped early (INCOMPLETE)
- [ ] Overwrites the CHECKPOINT block in `production/session-state/active.md`
- [ ] Ends with next-step handoff: `/story-done` (`/code-review` first at standard/full)

---

## Coverage Notes

- The code root is covered for Godot (`src/`) and Unity (`Assets/`, Case 6) and for
  an unresolved engine (Case 7). Unreal (`Source/<Module>/<System>/`, with the
  editor-target build as the parse check) is not given a fixture.
- The INCOMPLETE path is Case 9; `parse NOT VERIFIED` when the engine binary is
  unavailable is not given a fixture.
- The Manifest Version mismatch prompt (`[A]` update / `[B]` keep old rules, which
  records a `Manifest-Note` / `[C]` stop) follows Case 3's ask-before-spawn pattern
  and is not separately tested.
- Config/Data stories (no agent spawned) and `testing.strict` per-type overrides
  are not covered.