mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios
synced 2026-04-21 13:27:18 +00:00
Split /create-epics-stories into /create-epics + /create-stories; add /dev-story
- NEW /create-epics (agent: technical-director): architect-level epic scoping, one epic per architectural module. Does not create stories. - NEW /create-stories (agent: lead-programmer): decomposes a single epic into story files with embedded TR-IDs, ADR guidance, and test evidence paths. - NEW /dev-story: the missing implementation skill — reads a story, loads full context (TR registry, ADR, control manifest, engine prefs), routes to the correct programmer agent via Task, and drives implementation to completion including writing the test. - DEPRECATED /create-epics-stories: added redirect notice; original content preserved for reference. - Updated /gate-check: Pre-Prod→Production artifact check and follow-up actions now reference the two new skills. - Updated workflow-catalog.yaml: replaced create-epics-stories step with two separate steps; implement step now references /dev-story with command field. Story loop is now explicit: /story-readiness → /dev-story → /code-review → /story-done Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
parent
db416aa494
commit
4ca6500a21
6 changed files with 723 additions and 13 deletions
|
|
@ -160,14 +160,25 @@ phases:
|
|||
min_count: 1
|
||||
description: "Build throwaway prototypes in isolated worktree to validate core mechanic"
|
||||
|
||||
- id: create-epics-stories
|
||||
name: "Epics and Stories"
|
||||
command: /create-epics-stories
|
||||
- id: create-epics
|
||||
name: "Create Epics"
|
||||
command: /create-epics
|
||||
required: true
|
||||
repeatable: true
|
||||
artifact:
|
||||
glob: "production/stories/*.md"
|
||||
glob: "production/epics/*/EPIC.md"
|
||||
min_count: 1
|
||||
description: "Break GDDs + ADRs + control manifest into implementable story files"
|
||||
description: "Translate GDDs + ADRs into epics — one per architectural module. Run per layer: /create-epics layer: foundation, then /create-epics layer: core"
|
||||
|
||||
- id: create-stories
|
||||
name: "Create Stories"
|
||||
command: /create-stories
|
||||
required: true
|
||||
repeatable: true
|
||||
artifact:
|
||||
glob: "production/epics/**/*.md"
|
||||
min_count: 2
|
||||
description: "Break each epic into implementable story files. Run per epic: /create-stories [epic-slug]"
|
||||
|
||||
- id: sprint-plan
|
||||
name: "First Sprint Plan"
|
||||
|
|
@ -208,11 +219,12 @@ phases:
|
|||
|
||||
- id: implement
|
||||
name: "Implement Stories"
|
||||
command: /dev-story
|
||||
required: true
|
||||
repeatable: true
|
||||
artifact:
|
||||
note: "Check src/ for active code and production/stories/ for In Progress stories"
|
||||
description: "Pick the next ready story and implement it. Then run /story-done."
|
||||
note: "Check src/ for active code and production/epics/**/*.md for In Progress stories"
|
||||
description: "Pick the next ready story and implement it with /dev-story [story-path]. Routes to the correct programmer agent. Then run /code-review and /story-done."
|
||||
|
||||
- id: story-done
|
||||
name: "Story Done Review"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: create-epics-stories
|
||||
description: "Translate approved GDDs + architecture + ADRs into implementable epics and stories. Each story embeds the GDD requirement it satisfies, the ADR governing implementation, acceptance criteria, engine compatibility notes, and control manifest rules. Programmers need nothing else to implement a story correctly."
|
||||
description: "DEPRECATED — use /create-epics then /create-stories instead. This skill has been split into two focused skills: /create-epics (architect-level scoping, one per layer) and /create-stories (lead-programmer story breakdown, one per epic)."
|
||||
argument-hint: "[system-name | layer: foundation|core|feature|presentation | all]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write, Task
|
||||
|
|
@ -8,7 +8,22 @@ context: fork
|
|||
agent: technical-director
|
||||
---
|
||||
|
||||
# Create Epics & Stories
|
||||
# Create Epics & Stories — DEPRECATED
|
||||
|
||||
> **This skill has been superseded.** Use the two-skill workflow instead:
|
||||
>
|
||||
> 1. `/create-epics layer: foundation` — define Foundation epics (technical-director)
|
||||
> 2. `/create-stories [epic-slug]` — break each epic into stories (lead-programmer)
|
||||
> 3. `/create-epics layer: core` — define Core epics
|
||||
> 4. `/create-stories [epic-slug]` — break each Core epic into stories
|
||||
>
|
||||
> **Why the split?** Epics are architectural scope decisions (technical-director's domain).
|
||||
> Stories are implementation decomposition (lead-programmer's domain). Mixing them in one
|
||||
> skill caused the wrong agent to own the wrong decisions.
|
||||
>
|
||||
> **To implement a story** once stories exist, use `/dev-story [story-path]`.
|
||||
|
||||
---
|
||||
|
||||
This skill translates the approved design and architecture into implementable
|
||||
work units. Each **epic** maps to one architectural module. Each **story** is a
|
||||
|
|
|
|||
195
.claude/skills/create-epics/SKILL.md
Normal file
195
.claude/skills/create-epics/SKILL.md
Normal file
|
|
@ -0,0 +1,195 @@
|
|||
---
|
||||
name: create-epics
|
||||
description: "Translate approved GDDs + architecture into epics — one epic per architectural module. Defines scope, governing ADRs, engine risk, and untraced requirements. Does NOT break into stories — run /create-stories [epic-slug] after each epic is created."
|
||||
argument-hint: "[system-name | layer: foundation|core|feature|presentation | all]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write
|
||||
context: fork
|
||||
agent: technical-director
|
||||
---
|
||||
|
||||
# Create Epics
|
||||
|
||||
An epic is a named, bounded body of work that maps to one architectural module.
|
||||
It defines **what** needs to be built and **who owns it architecturally**. It
|
||||
does not prescribe implementation steps — that is the job of stories.
|
||||
|
||||
**Run this skill once per layer** as you approach that layer in development.
|
||||
Do not create Feature layer epics until Core is nearly complete — the design
|
||||
will have changed.
|
||||
|
||||
**Output:** `production/epics/[epic-slug]/EPIC.md` + `production/epics/index.md`
|
||||
|
||||
**Next step after each epic:** `/create-stories [epic-slug]`
|
||||
|
||||
**When to run:** After `/create-control-manifest` and `/architecture-review` pass.
|
||||
|
||||
---
|
||||
|
||||
## 1. Parse Arguments
|
||||
|
||||
**Modes:**
|
||||
- `/create-epics all` — process all systems in layer order
|
||||
- `/create-epics layer: foundation` — Foundation layer only
|
||||
- `/create-epics layer: core` — Core layer only
|
||||
- `/create-epics layer: feature` — Feature layer only
|
||||
- `/create-epics layer: presentation` — Presentation layer only
|
||||
- `/create-epics [system-name]` — one specific system
|
||||
- No argument — ask: "Which layer or system would you like to create epics for?"
|
||||
|
||||
---
|
||||
|
||||
## 2. Load Inputs
|
||||
|
||||
### Step 2a — Summary scan (fast)
|
||||
|
||||
Grep all GDDs for their `## Summary` sections before reading anything fully:
|
||||
|
||||
```
|
||||
Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
|
||||
```
|
||||
|
||||
For `layer:` or `[system-name]` modes: filter to only in-scope GDDs based on
|
||||
the Summary quick-reference. Skip full-reading anything out of scope.
|
||||
|
||||
### Step 2b — Full document load
|
||||
|
||||
Read for in-scope systems:
|
||||
|
||||
- `design/gdd/systems-index.md` — authoritative system list, layers, priority
|
||||
- In-scope GDDs (Approved or Designed status)
|
||||
- `docs/architecture/architecture.md` — module ownership and API boundaries
|
||||
- All Accepted ADRs — read the "GDD Requirements Addressed", "Decision", and "Engine Compatibility" sections
|
||||
- `docs/architecture/control-manifest.md` — manifest version date from header
|
||||
- `docs/architecture/tr-registry.yaml` — for tracing requirements to ADR coverage
|
||||
- `docs/engine-reference/[engine]/VERSION.md` — engine name, version, risk levels
|
||||
|
||||
Report: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."
|
||||
|
||||
---
|
||||
|
||||
## 3. Processing Order
|
||||
|
||||
Process in dependency-safe layer order:
|
||||
1. **Foundation** (no dependencies)
|
||||
2. **Core** (depends on Foundation)
|
||||
3. **Feature** (depends on Core)
|
||||
4. **Presentation** (depends on Feature + Core)
|
||||
|
||||
Within each layer, use the order from `systems-index.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Define Each Epic
|
||||
|
||||
For each system, map it to an architectural module from `architecture.md`.
|
||||
|
||||
Check ADR coverage against the TR registry:
|
||||
- **Traced requirements**: TR-IDs that have an Accepted ADR covering them
|
||||
- **Untraced requirements**: TR-IDs with no ADR — warn before proceeding
|
||||
|
||||
Present to user before writing anything:
|
||||
|
||||
```
|
||||
## Epic: [System Name]
|
||||
|
||||
**Layer**: [Foundation / Core / Feature / Presentation]
|
||||
**GDD**: design/gdd/[filename].md
|
||||
**Architecture Module**: [module name from architecture.md]
|
||||
**Governing ADRs**: [ADR-NNNN, ADR-MMMM]
|
||||
**Engine Risk**: [LOW / MEDIUM / HIGH — highest risk among governing ADRs]
|
||||
**GDD Requirements Covered by ADRs**: [N / total]
|
||||
**Untraced Requirements**: [list TR-IDs with no ADR, or "None"]
|
||||
```
|
||||
|
||||
If there are untraced requirements:
|
||||
> "⚠️ [N] requirements in [system] have no ADR. The epic can be created, but
|
||||
> stories for these requirements will be marked Blocked until ADRs exist.
|
||||
> Run `/architecture-decision` first, or proceed with placeholders."
|
||||
|
||||
Ask: "Shall I create Epic: [name]?"
|
||||
Options: "Yes, create it", "Skip", "Pause — I need to write ADRs first"
|
||||
|
||||
---
|
||||
|
||||
## 5. Write Epic Files
|
||||
|
||||
After approval, write:
|
||||
|
||||
### `production/epics/[epic-slug]/EPIC.md`
|
||||
|
||||
```markdown
|
||||
# Epic: [System Name]
|
||||
|
||||
> **Layer**: [Foundation / Core / Feature / Presentation]
|
||||
> **GDD**: design/gdd/[filename].md
|
||||
> **Architecture Module**: [module name]
|
||||
> **Status**: Ready
|
||||
> **Stories**: Not yet created — run `/create-stories [epic-slug]`
|
||||
|
||||
## Overview
|
||||
|
||||
[1 paragraph describing what this epic implements, derived from the GDD Overview
|
||||
and the architecture module's stated responsibilities]
|
||||
|
||||
## Governing ADRs
|
||||
|
||||
| ADR | Decision Summary | Engine Risk |
|
||||
|-----|-----------------|-------------|
|
||||
| ADR-NNNN: [title] | [1-line summary] | LOW/MEDIUM/HIGH |
|
||||
|
||||
## GDD Requirements
|
||||
|
||||
| TR-ID | Requirement | ADR Coverage |
|
||||
|-------|-------------|--------------|
|
||||
| TR-[system]-001 | [requirement text from registry] | ADR-NNNN ✅ |
|
||||
| TR-[system]-002 | [requirement text] | ❌ No ADR |
|
||||
|
||||
## Definition of Done
|
||||
|
||||
This epic is complete when:
|
||||
- All stories are implemented, reviewed, and closed via `/story-done`
|
||||
- All acceptance criteria from `design/gdd/[filename].md` are verified
|
||||
- All Logic and Integration stories have passing test files in `tests/`
|
||||
- All Visual/Feel and UI stories have evidence docs with sign-off in `production/qa/evidence/`
|
||||
|
||||
## Next Step
|
||||
|
||||
Run `/create-stories [epic-slug]` to break this epic into implementable stories.
|
||||
```
|
||||
|
||||
### Update `production/epics/index.md`
|
||||
|
||||
Create or update the master index:
|
||||
|
||||
```markdown
|
||||
# Epics Index
|
||||
|
||||
Last Updated: [date]
|
||||
Engine: [name + version]
|
||||
|
||||
| Epic | Layer | System | GDD | Stories | Status |
|
||||
|------|-------|--------|-----|---------|--------|
|
||||
| [name] | Foundation | [system] | [file] | Not yet created | Ready |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Gate-Check Reminder
|
||||
|
||||
After writing all epics for the requested scope:
|
||||
|
||||
- **Foundation + Core complete**: These are required for the Pre-Production →
|
||||
Production gate. Run `/gate-check production` to check readiness.
|
||||
- **Reminder**: Epics define scope. Stories define implementation steps. Run
|
||||
`/create-stories [epic-slug]` for each epic before developers can pick up work.
|
||||
|
||||
---
|
||||
|
||||
## Collaborative Protocol
|
||||
|
||||
1. **One epic at a time** — present each epic definition before asking to create it
|
||||
2. **Warn on gaps** — flag untraced requirements before proceeding
|
||||
3. **Ask before writing** — per-epic approval before writing any file
|
||||
4. **No invention** — all content comes from GDDs, ADRs, and architecture docs
|
||||
5. **Never create stories** — this skill stops at the epic level
|
||||
234
.claude/skills/create-stories/SKILL.md
Normal file
234
.claude/skills/create-stories/SKILL.md
Normal file
|
|
@ -0,0 +1,234 @@
|
|||
---
|
||||
name: create-stories
|
||||
description: "Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic."
|
||||
argument-hint: "[epic-slug | epic-path]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write
|
||||
context: fork
|
||||
agent: lead-programmer
|
||||
---
|
||||
|
||||
# Create Stories
|
||||
|
||||
A story is a single implementable behaviour — small enough to complete in one
|
||||
focused session, self-contained, and fully traceable to a GDD requirement and
|
||||
an ADR decision. Stories are what developers pick up. Epics are what architects
|
||||
define.
|
||||
|
||||
**Run this skill per epic**, not per layer. Run it for Foundation epics first,
|
||||
then Core, and so on — matching the dependency order.
|
||||
|
||||
**Output:** `production/epics/[epic-slug]/story-NNN-[slug].md` files
|
||||
|
||||
**Previous step:** `/create-epics [system]`
|
||||
**Next step after stories exist:** `/story-readiness [story-path]` then `/dev-story [story-path]`
|
||||
|
||||
---
|
||||
|
||||
## 1. Parse Argument
|
||||
|
||||
- `/create-stories [epic-slug]` — e.g. `/create-stories combat`
|
||||
- `/create-stories production/epics/combat/EPIC.md` — full path also accepted
|
||||
- No argument — ask: "Which epic would you like to break into stories?"
|
||||
Glob `production/epics/*/EPIC.md` and list available epics with their status.
|
||||
|
||||
---
|
||||
|
||||
## 2. Load Everything for This Epic
|
||||
|
||||
Read in full:
|
||||
|
||||
- `production/epics/[epic-slug]/EPIC.md` — epic overview, governing ADRs, GDD requirements table
|
||||
- The epic's GDD (`design/gdd/[filename].md`) — read all 8 sections, especially Acceptance Criteria, Formulas, and Edge Cases
|
||||
- All governing ADRs listed in the epic — read the Decision, Implementation Guidelines, Engine Compatibility, and Engine Notes sections
|
||||
- `docs/architecture/control-manifest.md` — extract rules for this epic's layer; note the Manifest Version date from the header
|
||||
- `docs/architecture/tr-registry.yaml` — load all TR-IDs for this system
|
||||
|
||||
Report: "Loaded epic [name], GDD [filename], [N] governing ADRs, control manifest v[date]."
|
||||
|
||||
---
|
||||
|
||||
## 3. Classify Stories by Type
|
||||
|
||||
**Story Type Classification** — assign each story a type based on its acceptance criteria:
|
||||
|
||||
| Story Type | Assign when criteria reference... |
|
||||
|---|---|
|
||||
| **Logic** | Formulas, numerical thresholds, state transitions, AI decisions, calculations |
|
||||
| **Integration** | Two or more systems interacting, signals crossing boundaries, save/load round-trips |
|
||||
| **Visual/Feel** | Animation behaviour, VFX, "feels responsive", timing, screen shake, audio sync |
|
||||
| **UI** | Menus, HUD elements, buttons, screens, dialogue boxes, tooltips |
|
||||
| **Config/Data** | Balance tuning values, data file changes only — no new code logic |
|
||||
|
||||
Mixed stories: assign the type that carries the highest implementation risk.
|
||||
The type determines what test evidence is required before `/story-done` can close the story.
|
||||
|
||||
---
|
||||
|
||||
## 4. Decompose the GDD into Stories
|
||||
|
||||
For each GDD acceptance criterion:
|
||||
|
||||
1. Group related criteria that require the same core implementation
|
||||
2. Each group = one story
|
||||
3. Order stories: foundational behaviour first, edge cases last, UI last
|
||||
|
||||
**Story sizing rule:** one story = one focused session (~2-4 hours). If a
|
||||
group of criteria would take longer, split into two stories.
|
||||
|
||||
For each story, determine:
|
||||
- **GDD requirement**: which acceptance criterion(ia) does this satisfy?
|
||||
- **TR-ID**: look up in `tr-registry.yaml`. Use the stable ID. If no match, use `TR-[system]-???` and warn.
|
||||
- **Governing ADR**: which ADR governs how to implement this?
|
||||
- `Status: Accepted` → embed normally
|
||||
- `Status: Proposed` → set story `Status: Blocked` with note: "BLOCKED: ADR-NNNN is Proposed — run `/architecture-decision` to advance it"
|
||||
- **Story Type**: from Step 3 classification
|
||||
- **Engine risk**: from the ADR's Knowledge Risk field
|
||||
|
||||
---
|
||||
|
||||
## 5. Present Stories for Review
|
||||
|
||||
Before writing any files, present the full story list:
|
||||
|
||||
```
|
||||
## Stories for Epic: [name]
|
||||
|
||||
Story 001: [title] — Logic — ADR-NNNN
|
||||
Covers: TR-[system]-001 ([1-line summary of requirement])
|
||||
Test required: tests/unit/[system]/[slug]_test.[ext]
|
||||
|
||||
Story 002: [title] — Integration — ADR-MMMM
|
||||
Covers: TR-[system]-002, TR-[system]-003
|
||||
Test required: tests/integration/[system]/[slug]_test.[ext]
|
||||
|
||||
Story 003: [title] — Visual/Feel — ADR-NNNN
|
||||
Covers: TR-[system]-004
|
||||
Evidence required: production/qa/evidence/[slug]-evidence.md
|
||||
|
||||
[N stories total: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data]
|
||||
```
|
||||
|
||||
Ask: "May I write these [N] stories to `production/epics/[epic-slug]/`?"
|
||||
|
||||
---
|
||||
|
||||
## 6. Write Story Files
|
||||
|
||||
For each story, write `production/epics/[epic-slug]/story-[NNN]-[slug].md`:
|
||||
|
||||
```markdown
|
||||
# Story [NNN]: [title]
|
||||
|
||||
> **Epic**: [epic name]
|
||||
> **Status**: Ready
|
||||
> **Layer**: [Foundation / Core / Feature / Presentation]
|
||||
> **Type**: [Logic | Integration | Visual/Feel | UI | Config/Data]
|
||||
> **Manifest Version**: [date from control-manifest.md header]
|
||||
|
||||
## Context
|
||||
|
||||
**GDD**: `design/gdd/[filename].md`
|
||||
**Requirement**: `TR-[system]-NNN`
|
||||
*(Requirement text lives in `docs/architecture/tr-registry.yaml` — read fresh at review time)*
|
||||
|
||||
**ADR Governing Implementation**: [ADR-NNNN: title]
|
||||
**ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]
|
||||
|
||||
**Engine**: [name + version] | **Risk**: [LOW / MEDIUM / HIGH]
|
||||
**Engine Notes**: [from ADR Engine Compatibility section — post-cutoff APIs, verification required]
|
||||
|
||||
**Control Manifest Rules (this layer)**:
|
||||
- Required: [relevant required pattern]
|
||||
- Forbidden: [relevant forbidden pattern]
|
||||
- Guardrail: [relevant performance guardrail]
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
*From GDD `design/gdd/[filename].md`, scoped to this story:*
|
||||
|
||||
- [ ] [criterion 1 — directly from GDD]
|
||||
- [ ] [criterion 2]
|
||||
- [ ] [performance criterion if applicable]
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
*Derived from ADR-NNNN Implementation Guidelines:*
|
||||
|
||||
[Specific, actionable guidance from the ADR. Do not paraphrase in ways that
|
||||
change meaning. This is what the programmer reads instead of the ADR.]
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
*Handled by neighbouring stories — do not implement here:*
|
||||
|
||||
- [Story NNN+1]: [what it handles]
|
||||
|
||||
---
|
||||
|
||||
## Test Evidence
|
||||
|
||||
**Story Type**: [type]
|
||||
**Required evidence**:
|
||||
- Logic: `tests/unit/[system]/[story-slug]_test.[ext]` — must exist and pass
|
||||
- Integration: `tests/integration/[system]/[story-slug]_test.[ext]` OR playtest doc
|
||||
- Visual/Feel: `production/qa/evidence/[story-slug]-evidence.md` + sign-off
|
||||
- UI: `production/qa/evidence/[story-slug]-evidence.md` or interaction test
|
||||
- Config/Data: smoke check pass (`production/qa/smoke-*.md`)
|
||||
|
||||
**Status**: [ ] Not yet created
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on: [Story NNN-1 must be DONE, or "None"]
|
||||
- Unlocks: [Story NNN+1, or "None"]
|
||||
```
|
||||
|
||||
### Also update `production/epics/[epic-slug]/EPIC.md`
|
||||
|
||||
Replace the "Stories: Not yet created" line with a populated table:
|
||||
|
||||
```markdown
|
||||
## Stories
|
||||
|
||||
| # | Story | Type | Status | ADR |
|
||||
|---|-------|------|--------|-----|
|
||||
| 001 | [title] | Logic | Ready | ADR-NNNN |
|
||||
| 002 | [title] | Integration | Ready | ADR-MMMM |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. After Writing
|
||||
|
||||
Tell the user:
|
||||
|
||||
"[N] stories written to `production/epics/[epic-slug]/`.
|
||||
|
||||
To start implementation:
|
||||
1. Run `/story-readiness [story-path]` to confirm the first story is ready
|
||||
2. Run `/dev-story [story-path]` to implement it
|
||||
3. Run `/code-review [changed files]` after implementation
|
||||
4. Run `/story-done [story-path]` to close it
|
||||
|
||||
Work through stories in order — each story's `Depends on:` field tells you
|
||||
what must be DONE before you can start it."
|
||||
|
||||
---
|
||||
|
||||
## Collaborative Protocol
|
||||
|
||||
1. **Read before presenting** — load all inputs silently before showing the story list
|
||||
2. **Ask once** — present all stories for the epic in one summary, not one at a time
|
||||
3. **Warn on blocked stories** — flag any story with a Proposed ADR before writing
|
||||
4. **Ask before writing** — get approval for the full story set before writing files
|
||||
5. **No invention** — acceptance criteria come from GDDs, implementation notes from ADRs, rules from the manifest
|
||||
6. **Never start implementation** — this skill stops at the story file level
|
||||
252
.claude/skills/dev-story/SKILL.md
Normal file
252
.claude/skills/dev-story/SKILL.md
Normal file
|
|
@ -0,0 +1,252 @@
|
|||
---
|
||||
name: dev-story
|
||||
description: "Read a story file and implement it. Loads the full context (story, GDD requirement, ADR guidelines, control manifest), routes to the right programmer agent for the system and engine, implements the code and test, 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, Edit, Bash, Task
|
||||
context: fork
|
||||
---
|
||||
|
||||
# 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:**
|
||||
```
|
||||
/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
|
||||
```
|
||||
|
||||
**Output:** Source code + test file in the project's `src/` and `tests/` directories.
|
||||
|
||||
---
|
||||
|
||||
## 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 everything in this order — do not start implementation until all is loaded:
|
||||
|
||||
### 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 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
|
||||
GDD 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 Engine Compatibility section (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: "Story was written against manifest v[story-date]. Current manifest is
|
||||
v[current-date]. New rules may apply — reviewing the diff before implementing."
|
||||
Read the manifest carefully for any new rules added since the story was written.
|
||||
|
||||
### Engine reference
|
||||
Read `.claude/docs/technical-preferences.md`:
|
||||
- `Engine:` value — determines which programmer agents to use
|
||||
- Naming conventions (class names, file names, signal/event names)
|
||||
- Performance budgets (frame budget, memory ceiling)
|
||||
- Forbidden patterns
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Route to the Right Programmer
|
||||
|
||||
Based on the story's **Layer**, **Type**, and **system name**, determine which
|
||||
specialist to spawn via Task.
|
||||
|
||||
### 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) |
|
||||
|
||||
### Engine specialist — always spawn as secondary for code stories
|
||||
|
||||
Read the `Engine Specialists` section of `.claude/docs/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 GDD 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 engine naming conventions and performance budgets
|
||||
6. Any engine-specific notes from the ADR Engine Compatibility section
|
||||
7. The test file path that must be created
|
||||
8. Explicit instruction: **implement this story and write the test**
|
||||
|
||||
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 **Logic** and **Integration** stories, the test must be written as part of
|
||||
this implementation — not deferred to later.
|
||||
|
||||
Remind the programmer agent:
|
||||
|
||||
> "The test file for this story is required at: `[path from Test Evidence section]`.
|
||||
> The story cannot be closed via `/story-done` without it. Write the test
|
||||
> alongside the implementation, not after."
|
||||
|
||||
Test requirements (from coding-standards.md):
|
||||
- File name: `[system]_[feature]_test.[ext]`
|
||||
- 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 the formula bounds from the GDD Formulas section
|
||||
|
||||
For **Visual/Feel** and **UI** stories: no automated test. Remind the agent to
|
||||
note in the implementation summary what manual evidence will be needed:
|
||||
"Evidence doc required at `production/qa/evidence/[slug]-evidence.md`."
|
||||
|
||||
For **Config/Data** stories: no test file. A smoke check will serve as evidence.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Collect and Summarise
|
||||
|
||||
After the programmer agent(s) complete, collect:
|
||||
|
||||
- Files created or modified (with paths)
|
||||
- Test file created (path and number of test functions written)
|
||||
- Any deviations from the story's Out of Scope boundary (flag these)
|
||||
- Any questions or blockers the agent surfaced
|
||||
- Any engine-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 (Visual/Feel)
|
||||
|
||||
**Deviations from scope**: [None] or [list files touched outside story 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]
|
||||
```
|
||||
|
||||
Create `active.md` if it does not exist. Confirm: "Session state updated."
|
||||
|
||||
---
|
||||
|
||||
## Collaborative Protocol
|
||||
|
||||
- **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** — do not mark implementation
|
||||
complete without the test file existing
|
||||
- **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?"
|
||||
|
|
@ -121,9 +121,10 @@ The project progresses through these stages:
|
|||
- [ ] At least 3 ADRs covering Foundation-layer decisions exist in `docs/architecture/`
|
||||
- [ ] Control manifest exists at `docs/architecture/control-manifest.md`
|
||||
(generated by `/create-control-manifest` from Accepted ADRs)
|
||||
- [ ] Epics and stories defined in `production/epics/` with at least Foundation
|
||||
and Core layer epics present (use `/create-epics-stories layer: foundation`
|
||||
and `/create-epics-stories layer: core` to create them)
|
||||
- [ ] Epics defined in `production/epics/` with at least Foundation and Core
|
||||
layer epics present (use `/create-epics layer: foundation` and
|
||||
`/create-epics layer: core` to create them, then `/create-stories [epic-slug]`
|
||||
for each epic)
|
||||
- [ ] Vertical Slice build exists and is playable (not just scope-defined)
|
||||
- [ ] Vertical Slice has been playtested with at least 3 sessions (internal OK)
|
||||
- [ ] Vertical Slice playtest report exists at `production/playtests/` or equivalent
|
||||
|
|
@ -320,7 +321,8 @@ Based on the verdict, suggest specific next steps:
|
|||
- **ADRs missing engine compatibility sections?** → Re-run `/architecture-decision`
|
||||
or manually add Engine Compatibility sections to existing ADRs
|
||||
- **Missing control manifest?** → `/create-control-manifest` (requires Accepted ADRs)
|
||||
- **Missing epics/stories?** → `/create-epics-stories all` (requires control manifest)
|
||||
- **Missing epics?** → `/create-epics layer: foundation` then `/create-epics layer: core` (requires control manifest)
|
||||
- **Missing stories for an epic?** → `/create-stories [epic-slug]` (run after each epic is created)
|
||||
- **Stories not implementation-ready?** → `/story-readiness` to validate stories before developers pick them up
|
||||
- **Tests failing?** → delegate to `lead-programmer` or `qa-tester`
|
||||
- **No playtest data?** → `/playtest-report`
|
||||
|
|
|
|||
Loading…
Reference in a new issue