Skip to content

Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.

Pipeline integrity + brownfield adoption system

Donchitos0bbf25ec3171
diff --git a/.claude/agent-memory/lead-programmer/MEMORY.md b/.claude/agent-memory/lead-programmer/MEMORY.md
new file mode 100644
index 00000000..fb5a9596
--- /dev/null
+++ b/.claude/agent-memory/lead-programmer/MEMORY.md
@@ -0,0 +1,28 @@
+# Lead Programmer — Agent Memory
+
+## Skill Authoring Conventions
+
+### Frontmatter
+- Fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
+- Read-only analysis skills that run in isolation also carry `context: fork` and `agent:`
+- Interactive skills (write files, ask questions) do NOT use `context: fork`
+- `AskUserQuestion` is a usage pattern described in skill body text — it is NOT listed
+ in `allowed-tools` frontmatter (no existing skill does this)
+
+### File Layout
+- Skills live in `.claude/skills/<name>/SKILL.md` (subdirectory per skill, never flat .md)
+- Section headers use `##` for phases, `###` for sub-sections
+- Phase names follow "Phase N: Verb Noun" pattern (e.g., "Phase 1: Find the Story")
+- Output format templates go in fenced code blocks
+
+### Known Canonical Paths (verify before referencing in new skills)
+- Tech debt register: `docs/tech-debt-register.md` (NOT `production/tech-debt.md`)
+- Sprint files: `production/sprints/`
+- Epic story files: `production/epics/[epic-slug]/story-[NNN]-[slug].md`
+- Control manifest: `docs/architecture/control-manifest.md`
+- Session state: `production/session-state/active.md`
+- Systems index: `design/gdd/systems-index.md`
+- Engine reference: `docs/engine-reference/[engine]/VERSION.md`
+
+### Skills Completed
+- `story-done` — end-of-story completion handshake (Phase 1-8, writes story file)
diff --git a/.claude/docs/workflow-catalog.yaml b/.claude/docs/workflow-catalog.yaml
new file mode 100644
index 00000000..31cbfb44
--- /dev/null
+++ b/.claude/docs/workflow-catalog.yaml
@@ -0,0 +1,295 @@
+# Workflow Catalog
+# Used by /help to determine where a user is and what comes next.
+#
+# Artifact checks:
+# glob: file glob pattern — complete if ≥1 file matches (or min_count)
+# pattern: text pattern that must appear in the file (checked after glob)
+# min_count: minimum matching files required (default: 1)
+# note: human-readable fallback when completion can't be auto-detected
+#
+# required: true → blocks progression to next phase (shown as REQUIRED)
+# required: false → optional enhancement (shown as OPTIONAL)
+# repeatable: true → runs multiple times (one per system, story, etc.)
+
+phases:
+
+ concept:
+ label: "Concept"
+ description: "Develop your game idea into a documented concept"
+ next_phase: systems-design
+ steps:
+ - id: brainstorm
+ name: "Brainstorm"
+ command: /brainstorm
+ required: false
+ description: "Explore the game concept using MDA, verb-first, and player psychology frameworks"
+
+ - id: engine-setup
+ name: "Engine Setup"
+ command: /setup-engine
+ required: true
+ artifact:
+ glob: ".claude/docs/technical-preferences.md"
+ pattern: "Engine: [^[]"
+ description: "Configure engine, pin version, set naming conventions and performance budgets"
+
+ - id: game-concept
+ name: "Game Concept Document"
+ command: /brainstorm
+ required: true
+ artifact:
+ glob: "design/gdd/game-concept.md"
+ description: "Formalize concept with pillars, MDA analysis, and scope tiers"
+
+ - id: design-review-concept
+ name: "Concept Review"
+ command: /design-review
+ required: false
+ description: "Validate the game concept (recommended before proceeding)"
+
+ - id: map-systems
+ name: "Systems Map"
+ command: /map-systems
+ required: true
+ artifact:
+ glob: "design/gdd/systems-index.md"
+ description: "Decompose concept into systems with dependency ordering and priority tiers"
+
+ systems-design:
+ label: "Systems Design"
+ description: "Author a GDD for each system in the systems index"
+ next_phase: technical-setup
+ steps:
+ - id: design-system
+ name: "System GDDs"
+ command: /design-system
+ required: true
+ repeatable: true
+ artifact:
+ note: "Check design/gdd/systems-index.md — each MVP system needs Status: Approved"
+ description: "Author per-system GDDs (guided, section-by-section). Run once per system."
+
+ - id: design-review
+ name: "Per-System Design Review"
+ command: /design-review
+ required: true
+ repeatable: true
+ description: "Validate each GDD (8 required sections, no MAJOR REVISION verdict). Run per system."
+
+ - id: review-all-gdds
+ name: "Cross-GDD Review"
+ command: /review-all-gdds
+ required: true
+ artifact:
+ glob: "design/gdd/gdd-cross-review-*.md"
+ description: "Holistic consistency check + design theory review across all GDDs simultaneously"
+
+ technical-setup:
+ label: "Technical Setup"
+ description: "Architecture decisions, UX foundations, engine validation"
+ next_phase: pre-production
+ steps:
+ - id: create-architecture
+ name: "Architecture Document"
+ command: /create-architecture
+ required: true
+ artifact:
+ glob: "docs/architecture/architecture.md"
+ description: "Author the master architecture document covering all systems"
+
+ - id: architecture-decision
+ name: "Architecture Decisions (ADRs)"
+ command: /architecture-decision
+ required: true
+ repeatable: true
+ artifact:
+ glob: "docs/architecture/adr-*.md"
+ min_count: 3
+ description: "Document key technical decisions as ADRs. Minimum 3 Foundation-layer ADRs required."
+
+ - id: architecture-review
+ name: "Architecture Review"
+ command: /architecture-review
+ required: true
+ artifact:
+ glob: "docs/architecture/architecture-review-*.md"
+ description: "Validate completeness, dependency ordering, engine compatibility"
+
+ - id: control-manifest
+ name: "Control Manifest"
+ command: /create-control-manifest
+ required: true
+ artifact:
+ glob: "docs/architecture/control-manifest.md"
+ description: "Flat programmer rules sheet generated from all Accepted ADRs"
+
+ - id: accessibility-doc
+ name: "Accessibility Requirements"
+ required: true
+ artifact:
+ glob: "design/accessibility-requirements.md"
+ description: "Commit accessibility tier (Basic/Standard/Comprehensive/Exemplary) and feature matrix"
+
+ - id: ux-design
+ name: "UX Specs (key screens)"
+ command: /ux-design
+ required: true
+ repeatable: true
+ artifact:
+ glob: "design/ux/*.md"
+ min_count: 1
+ description: "Author UX specs for main menu, core gameplay HUD, and pause screen"
+
+ - id: ux-review
+ name: "UX Review"
+ command: /ux-review
+ required: true
+ description: "Validate all key screen UX specs for accessibility and GDD alignment"
+
+ pre-production:
+ label: "Pre-Production"
+ description: "Prototype the core mechanic, define stories, validate fun"
+ next_phase: production
+ steps:
+ - id: prototype
+ name: "Prototype"
+ command: /prototype
+ required: true
+ artifact:
+ glob: "prototypes/*/README.md"
+ 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
+ required: true
+ artifact:
+ glob: "production/stories/*.md"
+ min_count: 1
+ description: "Break GDDs + ADRs + control manifest into implementable story files"
+
+ - id: sprint-plan
+ name: "First Sprint Plan"
+ command: /sprint-plan
+ required: true
+ artifact:
+ glob: "production/sprints/sprint-*.md"
+ min_count: 1
+ description: "Plan the first sprint with prioritized stories from epics"
+
+ - id: vertical-slice
+ name: "Vertical Slice (playtested)"
+ required: true
+ artifact:
+ glob: "production/playtests/*.md"
+ min_count: 1
+ description: "Playable end-to-end core loop, playtested with ≥3 sessions. HARD GATE."
+
+ production:
+ label: "Production"
+ description: "Sprint-based feature development — pick, implement, close stories"
+ next_phase: polish
+ steps:
+ - id: sprint-plan
+ name: "Sprint Plan"
+ command: /sprint-plan
+ required: true
+ repeatable: true
+ artifact:
+ glob: "production/sprints/sprint-*.md"
+ description: "Plan the current sprint with prioritized, ready stories"
+
+ - id: story-readiness
+ name: "Story Readiness Check"
+ command: /story-readiness
+ required: false
+ description: "Validate a story is implementation-ready before a developer picks it up"
+
+ - id: implement
+ name: "Implement Stories"
+ 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."
+
+ - id: story-done
+ name: "Story Done Review"
+ command: /story-done
+ required: true
+ repeatable: true
+ description: "Verify all acceptance criteria, check GDD/ADR deviations, close the story"
+
+ - id: sprint-status
+ name: "Sprint Status"
+ command: /sprint-status
+ required: false
+ description: "Quick 30-line snapshot of sprint progress without a full report"
+
+ polish:
+ label: "Polish"
+ description: "Performance, balance, playtesting, bug fixing"
+ next_phase: release
+ steps:
+ - id: perf-profile
+ name: "Performance Profile"
+ command: /perf-profile
+ required: false
+ description: "Profile and optimize CPU/GPU/memory bottlenecks"
+
+ - id: balance-check
+ name: "Balance Check"
+ command: /balance-check
+ required: false
+ description: "Analyze game balance formulas and data for outliers and broken progressions"
+
+ - id: asset-audit
+ name: "Asset Audit"
+ command: /asset-audit
+ required: false
+ description: "Verify naming conventions, file format standards, and size budgets"
+
+ - id: playtest-polish
+ name: "Playtest Sessions (×3)"
+ command: /playtest-report
+ required: true
+ artifact:
+ glob: "production/playtests/*.md"
+ min_count: 3
+ description: "Cover: new player experience, mid-game systems, difficulty curve"
+
+ - id: team-polish
+ name: "Polish Team Pass"
+ command: /team-polish
+ required: true
+ description: "Coordinated polish pass across performance, audio, visual, and UX"
+
+ release:
+ label: "Release"
+ description: "Launch preparation, certification, and ship"
+ next_phase: null
+ steps:
+ - id: release-checklist
+ name: "Release Checklist"
+ command: /release-checklist
+ required: true
+ description: "Pre-release validation across all departments: code, content, store, legal"
+
+ - id: patch-notes
+ name: "Patch Notes"
+ command: /patch-notes
+ required: false
+ description: "Generate player-facing patch notes from git history and sprint data"
+
+ - id: changelog
+ name: "Changelog"
+ command: /changelog
+ required: false
+ description: "Auto-generate internal changelog from commits, sprints, and design docs"
+
+ - id: launch-checklist
+ name: "Launch Checklist"
+ command: /launch-checklist
+ required: true
+ description: "Final launch readiness — last gate before shipping to players"
diff --git a/.claude/skills/adopt/SKILL.md b/.claude/skills/adopt/SKILL.md
new file mode 100644
index 00000000..c07b3e47
--- /dev/null
+++ b/.claude/skills/adopt/SKILL.md
@@ -0,0 +1,369 @@
+---
+name: adopt
+description: "Brownfield onboarding — audits existing project artifacts for template format compliance (not just existence), classifies gaps by impact, and produces a numbered migration plan. Run this when joining an in-progress project or upgrading from an older template version. Distinct from /project-stage-detect (which checks what exists) — this checks whether what exists will actually work with the template's skills."
+argument-hint: "[focus: full | gdds | adrs | stories | infra]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, AskUserQuestion
+context: fork
+agent: technical-director
+---
+
+# Adopt — Brownfield Template Adoption
+
+This skill audits an existing project's artifacts for **format compliance** with
+the template's skill pipeline, then produces a prioritised migration plan.
+
+**This is not `/project-stage-detect`.**
+`/project-stage-detect` answers: *what exists?*
+`/adopt` answers: *will what exists actually work with the template's skills?*
+
+A project can have GDDs, ADRs, and stories — and every format-sensitive skill
+will still fail silently or produce wrong results if those artifacts are in the
+wrong internal format.
+
+**Output:** `docs/adoption-plan-[date].md` — a persistent, checkable migration plan.
+
+**Argument modes:**
+- **No argument / `full`**: Complete audit — all artifact types
+- **`gdds`**: GDD format compliance only
+- **`adrs`**: ADR format compliance only
+- **`stories`**: Story format compliance only
+- **`infra`**: Infrastructure artifact gaps only (registry, manifest, sprint-status, stage.txt)
+
+---
+
+## Phase 1: Detect Project State
+
+Read silently before presenting anything.
+
+### Existence check
+- `production/stage.txt` — if present, read it (authoritative phase)
+- `design/gdd/game-concept.md` — concept exists?
+- `design/gdd/systems-index.md` — systems index exists?
+- Count GDD files: `design/gdd/*.md` (excluding game-concept.md and systems-index.md)
+- Count ADR files: `docs/architecture/adr-*.md`
+- Count story files: `production/epics/**/*.md` (excluding EPIC.md)
+- `.claude/docs/technical-preferences.md` — engine configured?
+- `docs/engine-reference/` — engine reference docs present?
+
+### Infer phase (if no stage.txt)
+Use the same heuristic as `/project-stage-detect`:
+- 10+ source files in `src/` → Production
+- Stories in `production/epics/` → Pre-Production
+- ADRs exist → Technical Setup
+- systems-index.md exists → Systems Design
+- game-concept.md exists → Concept
+- Nothing → Fresh (not a brownfield project — suggest `/start`)
+
+If the project appears fresh (no artifacts at all), stop:
+> "This looks like a fresh project with no existing artifacts. Run `/start`
+> instead — `/adopt` is for projects that already have work to migrate."
+
+Report: "Detected phase: [phase]. Found: [N] GDDs, [M] ADRs, [P] stories."
+
+---
+
+## Phase 2: Format Audit
+
+For each artifact type in scope (based on argument mode), check not just that
+the file exists but that it contains the internal structure the template requires.
+
+### 2a: GDD Format Audit
+
+For each GDD file found, check for the 8 required sections by scanning headings:
+
+| Required Section | Heading pattern to look for |
+|---|---|
+| Overview | `## Overview` |
+| Player Fantasy | `## Player Fantasy` |
+| Detailed Rules / Design | `## Detailed` or `## Core Rules` or `## Detailed Design` |
+| Formulas | `## Formulas` or `## Formula` |
+| Edge Cases | `## Edge Cases` |
+| Dependencies | `## Dependencies` or `## Depends` |
+| Tuning Knobs | `## Tuning` |
+| Acceptance Criteria | `## Acceptance` |
+
+For each GDD, record:
+- Which sections are present
+- Which sections are missing
+- Whether it has any content in present sections or just placeholder text
+ (`[To be designed]` or equivalent)
+
+Also check: does each GDD have a `**Status**:` field in its header block?
+Valid values: `In Design`, `Designed`, `In Review`, `Approved`, `Needs Revision`.
+
+### 2b: ADR Format Audit
+
+For each ADR file found, check for these critical sections:
+
+| Section | Impact if missing |
+|---|---|
+| `## Status` | **BLOCKING** — `/story-readiness` ADR status check silently passes everything |
+| `## ADR Dependencies` | HIGH — dependency ordering in `/architecture-review` breaks |
+| `## Engine Compatibility` | HIGH — post-cutoff API risk is unknown |
+| `## GDD Requirements Addressed` | MEDIUM — traceability matrix loses coverage |
+| `## Performance Implications` | LOW — not pipeline-critical |
+
+For each ADR, record: which sections present, which missing, current Status value
+if the Status section exists.
+
+### 2c: systems-index.md Format Audit
+
+If `design/gdd/systems-index.md` exists:
+
+1. **Parenthetical status values** — Grep for any Status cell containing
+ parentheses: `"Needs Revision ("`, `"In Progress ("`, etc.
+ These break exact-string matching in `/gate-check`, `/create-epics-stories`,
+ and `/architecture-review`. **BLOCKING.**
+
+2. **Valid status values** — check that Status column values are only from:
+ `Not Started`, `In Progress`, `In Review`, `Designed`, `Approved`, `Needs Revision`
+ Flag any unrecognised values.
+
+3. **Column structure** — check that the table has at minimum: System name,
+ Layer, Priority, Status columns. Missing columns degrade skill functionality.
+
+### 2d: Story Format Audit
+
+For each story file found:
+
+- **`Manifest Version:` field** — present in story header? (LOW — auto-passes if absent)
+- **TR-ID reference** — does story contain `TR-[a-z]+-[0-9]+` pattern? (MEDIUM — no staleness tracking)
+- **ADR reference** — does story reference at least one ADR? (check for `ADR-` pattern)
+- **Status field** — present and readable?
+- **Acceptance criteria** — does the story have a checkbox list (`- [ ]`)?
+
+### 2e: Infrastructure Audit
+
+| Artifact | Path | Impact if missing |
+|---|---|---|
+| TR registry | `docs/architecture/tr-registry.yaml` | HIGH — no stable requirement IDs |
+| Control manifest | `docs/architecture/control-manifest.md` | HIGH — no layer rules for stories |
+| Manifest version stamp | In manifest header: `Manifest Version:` | MEDIUM — staleness checks blind |
+| Sprint status | `production/sprint-status.yaml` | MEDIUM — `/sprint-status` falls back to markdown |
+| Stage file | `production/stage.txt` | MEDIUM — phase auto-detect unreliable |
+| Engine reference | `docs/engine-reference/[engine]/VERSION.md` | HIGH — ADR engine checks blind |
+| Architecture traceability | `docs/architecture/architecture-traceability.md` | MEDIUM — no persistent matrix |
+
+### 2f: Technical Preferences Audit
+
+Read `.claude/docs/technical-preferences.md`. Check each field for `[TO BE CONFIGURED]`:
+- Engine, Language, Rendering, Physics → HIGH if unconfigured (ADR skills fail)
+- Naming conventions → MEDIUM
+- Performance budgets → MEDIUM
+- Forbidden Patterns, Allowed Libraries → LOW (starts empty by design)
+
+---
+
+## Phase 3: Classify and Prioritise Gaps
+
+Organise every gap found across all audits into four severity tiers:
+
+**BLOCKING** — Will cause template skills to silently produce wrong results *right now*.
+Examples: ADR missing Status field, systems-index parenthetical status values,
+engine not configured when ADRs exist.
+
+**HIGH** — Will cause stories to be generated with missing safety checks, or
+infrastructure bootstrapping will fail.
+Examples: ADRs missing Engine Compatibility, GDDs missing Acceptance Criteria
+(stories can't be generated from them), tr-registry.yaml missing.
+
+**MEDIUM** — Degrades quality and pipeline tracking but does not break functionality.
+Examples: GDDs missing Tuning Knobs or Formulas sections, stories missing TR-IDs,
+sprint-status.yaml missing.
+
+**LOW** — Retroactive improvements that are nice-to-have but not urgent.
+Examples: Stories missing Manifest Version stamps, GDDs missing Open Questions section.
+
+Count totals per tier. If zero BLOCKING and zero HIGH gaps: report that the project
+is template-compatible and only advisory improvements remain.
+
+---
+
+## Phase 4: Build the Migration Plan
+
+Compose a numbered, ordered action plan. Ordering rules:
+1. BLOCKING gaps first (must fix before any pipeline skill runs reliably)
+2. HIGH gaps next, infrastructure before GDD/ADR content (bootstrapping needs correct formats)
+3. MEDIUM gaps ordered: GDD gaps before ADR gaps before story gaps (stories depend on GDDs and ADRs)
+4. LOW gaps last
+
+For each gap, produce a plan entry with:
+- A clear problem statement (one sentence, no jargon)
+- The exact command to fix it, if a skill handles it
+- Manual steps if it requires direct editing
+- A time estimate (rough: 5 min / 30 min / 1 session)
+- A checkbox `- [ ]` for tracking
+
+**Special case — systems-index parenthetical status values:**
+This is always the first item if present. Show the exact values that need changing
+and the exact replacement text. Offer to fix this immediately before writing the plan.
+
+**Special case — ADRs missing Status field:**
+For each affected ADR, the fix is:
+`/architecture-decision retrofit docs/architecture/adr-[NNNN]-[slug].md`
+List each ADR as a separate checkable item.
+
+**Special case — GDDs missing sections:**
+For each affected GDD, list which sections are missing and the fix:
+`/design-system retrofit design/gdd/[filename].md`
+
+**Infrastructure bootstrap ordering** — always present in this sequence:
+1. Fix ADR formats first (registry depends on reading ADR Status fields)
+2. Run `/architecture-review` → bootstraps `tr-registry.yaml`
+3. Run `/create-control-manifest` → creates manifest with version stamp
+4. Run `/sprint-plan update` → creates `sprint-status.yaml`
+5. Run `/gate-check [phase]` → writes `stage.txt` authoritatively
+
+**Existing stories** — note explicitly:
+> "Existing stories continue to work with all template skills — all new format
+> checks auto-pass when the fields are absent. They won't benefit from TR-ID
+> staleness tracking or manifest version checks until they're regenerated. This
+> is intentional: do not regenerate stories that are already in progress."
+
+---
+
+## Phase 5: Present Summary and Ask to Write
+
+Present a compact summary before writing:
+
+```
+## Adoption Audit Summary
+Phase detected: [phase]
+Engine: [configured / NOT CONFIGURED]
+GDDs audited: [N] ([X] fully compliant, [Y] with gaps)
+ADRs audited: [N] ([X] fully compliant, [Y] with gaps)
+Stories audited: [N]
+
+Gap counts:
+ BLOCKING: [N] — template skills will malfunction without these fixes
+ HIGH: [N] — unsafe to run /create-epics-stories or /story-readiness
+ MEDIUM: [N] — quality degradation
+ LOW: [N] — optional improvements
+
+Estimated remediation: [X blocking items × ~Y min each = roughly Z hours]
+```
+
+Ask: "May I write the full migration plan to `docs/adoption-plan-[date].md`?"
+
+---
+
+## Phase 6: Write the Adoption Plan
+
+If approved, write `docs/adoption-plan-[date].md` with this structure:
+
+```markdown
+# Adoption Plan
+
+> **Generated**: [date]
+> **Project phase**: [phase]
+> **Engine**: [name + version, or "Not configured"]
+> **Template version**: v0.4.0+
+
+Work through these steps in order. Check off each item as you complete it.
+Re-run `/adopt` anytime to check remaining gaps.
+
+---
+
+## Step 1: Fix Blocking Gaps
+
+[One sub-section per blocking gap with problem, fix command, time estimate, checkbox]
+
+---
+
+## Step 2: Fix High-Priority Gaps
+
+[One sub-section per high gap]
+
+---
+
+## Step 3: Bootstrap Infrastructure
+
+### 3a. Register existing requirements (creates tr-registry.yaml)
+Run `/architecture-review` — even if ADRs already exist, this run bootstraps
+the TR registry from your existing GDDs and ADRs.
+**Time**: 1 session (review can be long for large codebases)
+- [ ] tr-registry.yaml created
+
+### 3b. Create control manifest
+Run `/create-control-manifest`
+**Time**: 30 min
+- [ ] docs/architecture/control-manifest.md created
+
+### 3c. Create sprint tracking file
+Run `/sprint-plan update`
+**Time**: 5 min (if sprint plan already exists as markdown)
+- [ ] production/sprint-status.yaml created
+
+### 3d. Set authoritative project stage
+Run `/gate-check [current-phase]`
+**Time**: 5 min
+- [ ] production/stage.txt written
+
+---
+
+## Step 4: Medium-Priority Gaps
+
+[One sub-section per medium gap]
+
+---
+
+## Step 5: Optional Improvements
+
+[One sub-section per low gap]
+
+---
+
+## What to Expect from Existing Stories
+
+Existing stories continue to work with all template skills. New format checks
+(TR-ID validation, manifest version staleness) auto-pass when the fields are
+absent — so nothing breaks. They won't benefit from staleness tracking until
+regenerated. Do not regenerate stories that are in progress or done.
+
+---
+
+## Re-run
+
+Run `/adopt` again after completing Step 3 to verify all blocking and high gaps
+are resolved. The new run will reflect the current state of the project.
+```
+
+---
+
+## Phase 7: Offer First Action
+
+After writing the plan, don't stop there. Pick the single highest-priority gap
+and offer to handle it immediately:
+
+If there are parenthetical status values in systems-index.md:
+> "The most urgent fix is the systems-index.md status values — this breaks
+> multiple skills right now. I can fix these in-place in under 2 minutes.
+> Shall I edit the file now?"
+
+If ADRs are missing Status fields:
+> "The most urgent fix is adding Status fields to your ADRs. Shall I start
+> with `docs/architecture/adr-0001.md` using `/architecture-decision retrofit`?"
+
+If GDDs are missing Acceptance Criteria:
+> "The most important GDD gap is missing Acceptance Criteria — without these,
+> `/create-epics-stories` can't generate stories. Shall I start with
+> `design/gdd/[highest-priority-system].md` using `/design-system retrofit`?"
+
+Use `AskUserQuestion`:
+- "What would you like to do now?"
+ - Options: "Fix [most urgent gap] now", "Review the full plan first",
+ "I'll work through the plan myself", "Run `/project-stage-detect` for broader context"
+
+---
+
+## Collaborative Protocol
+
+1. **Read silently** — complete the full audit before presenting anything
+2. **Show the summary first** — let the user see scope before asking to write
+3. **Ask before writing** — always confirm before creating the adoption plan file
+4. **Offer, don't force** — the plan is advisory; the user decides what to fix and when
+5. **One action at a time** — after handing off the plan, offer one specific next step,
+ not a list of six things to do simultaneously
+6. **Never regenerate existing artifacts** — only fill gaps in what exists;
+ do not rewrite GDDs, ADRs, or stories that already have content
diff --git a/.claude/skills/architecture-decision/SKILL.md b/.claude/skills/architecture-decision/SKILL.md
index daafab89..b352ae31 100644
--- a/.claude/skills/architecture-decision/SKILL.md
+++ b/.claude/skills/architecture-decision/SKILL.md
@@ -8,6 +8,53 @@ allowed-tools: Read, Glob, Grep, Write
When this skill is invoked:
+## 0. Parse Arguments — Detect Retrofit Mode
+
+**If the argument starts with `retrofit` followed by a file path**
+(e.g., `/architecture-decision retrofit docs/architecture/adr-0001-event-system.md`):
+
+Enter **retrofit mode**:
+
+1. Read the existing ADR file completely.
+2. Identify which template sections are present by scanning headings:
+ - `## Status` — **BLOCKING if missing**: `/story-readiness` cannot check ADR acceptance
+ - `## ADR Dependencies` — HIGH if missing: dependency ordering breaks
+ - `## Engine Compatibility` — HIGH if missing: post-cutoff risk unknown
+ - `## GDD Requirements Addressed` — MEDIUM if missing: traceability lost
+3. Present to the user:
+ ```
+ ## Retrofit: [ADR title]
+ File: [path]
+
+ Sections already present (will not be touched):
+ ✓ Status: [current value, or "MISSING — will add"]
+ ✓ [section]
+
+ Missing sections to add:
+ ✗ Status — BLOCKING (stories cannot validate ADR acceptance without this)
+ ✗ ADR Dependencies — HIGH
+ ✗ Engine Compatibility — HIGH
+ ```
+4. Ask: "Shall I add the [N] missing sections? I will not modify any existing content."
+5. If yes:
+ - For **Status**: ask the user — "What is the current status of this decision?"
+ Options: "Proposed", "Accepted", "Deprecated", "Superseded by ADR-XXXX"
+ - For **ADR Dependencies**: ask — "Does this decision depend on any other ADR?
+ Does it enable or block any other ADR or epic?" Accept "None" for each field.
+ - For **Engine Compatibility**: read the engine reference docs (same as Step 0 below)
+ and ask the user to confirm the domain. Then generate the table with verified data.
+ - For **GDD Requirements Addressed**: ask — "Which GDD systems motivated this decision?
+ What specific requirement in each GDD does this ADR address?"
+ - Append each missing section to the ADR file using the Edit tool.
+ - **Never modify any existing section.** Only append or fill absent sections.
+6. After adding all missing sections, update the ADR's `## Date` field if it is absent.
+7. Suggest: "Run `/architecture-review` to re-validate coverage now that this ADR
+ has its Status and Dependencies fields."
+
+If NOT in retrofit mode, proceed to Step 0 below (normal ADR authoring).
+
+---
+
## 0. Load Engine Context (ALWAYS FIRST)
Before doing anything else, establish the engine environment:
diff --git a/.claude/skills/architecture-review/SKILL.md b/.claude/skills/architecture-review/SKILL.md
index a9a8d295..f0f398d8 100644
--- a/.claude/skills/architecture-review/SKILL.md
+++ b/.claude/skills/architecture-review/SKILL.md
@@ -51,6 +51,27 @@ Report a count: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."
## Phase 2: Extract Technical Requirements from Every GDD
+### Pre-load the TR Registry
+
+Before extracting any requirements, read `docs/architecture/tr-registry.yaml`
+if it exists. Index existing entries by `id` and by normalized `requirement`
+text (lowercase, trimmed). This prevents ID renumbering across review runs.
+
+For each requirement you extract, the matching rule is:
+1. **Exact/near match** to an existing registry entry for the same system →
+ reuse that entry's TR-ID unchanged. Update the `requirement` text in the
+ registry only if the GDD wording changed (same intent, clearer phrasing) —
+ add a `revised: [date]` field.
+2. **No match** → assign a new ID: next available `TR-[system]-NNN` for that
+ system, starting from the highest existing sequence + 1.
+3. **Ambiguous** (partial match, intent unclear) → ask the user:
+ > "Does '[new requirement text]' refer to the same requirement as
+ > `TR-[system]-NNN: [existing text]'`, or is it a new requirement?"
+ User answers: "Same requirement" (reuse ID) or "New requirement" (new ID).
+
+For any requirement with `status: deprecated` in the registry — skip it.
+It was removed from the GDD intentionally.
+
For each GDD, read it and extract all **technical requirements** — things the
architecture must provide for the system to work. A technical requirement is any
statement that implies a specific architectural decision.
@@ -251,8 +272,11 @@ If no revision flags are found, write: "No GDD revision flags — all GDD assump
are consistent with verified engine behaviour."
Ask: "Should I flag these GDDs for revision in the systems index?"
-- If yes: update the relevant systems' Status field to "Needs Revision (Architecture Feedback)"
- and note the specific conflict in a comment. Ask for approval before writing.
+- If yes: update the relevant systems' Status field to "Needs Revision"
+ and add a short inline note in the adjacent Notes/Description column explaining the conflict.
+ Ask for approval before writing.
+ (Do NOT use parentheticals like "Needs Revision (Architecture Feedback)" — other skills
+ match the exact string "Needs Revision" and parentheticals break that match.)
---
@@ -334,6 +358,23 @@ Ask: "May I write this review to `docs/architecture/architecture-review-[date].m
Also ask: "May I update `docs/architecture/architecture-traceability.md` with the
current matrix? This is the living index that future reviews update incrementally."
+### TR Registry Update
+
+Also ask: "May I update `docs/architecture/tr-registry.yaml` with new requirement
+IDs from this review?"
+
+If yes:
+- **Append** any new TR-IDs that weren't in the registry before this review
+- **Update** `requirement` text and `revised` date for any entries whose GDD
+ wording changed (ID stays the same)
+- **Mark** `status: deprecated` for any registry entries whose GDD requirement
+ no longer exists (confirm with user before marking deprecated)
+- **Never** renumber or delete existing entries
+- Update the `last_updated` and `version` fields at the top
+
+This ensures all future story files can reference stable TR-IDs that persist
+across every subsequent architecture review.
+
The traceability index format:
```markdown
diff --git a/.claude/skills/create-control-manifest/SKILL.md b/.claude/skills/create-control-manifest/SKILL.md
index e3c8b8fc..a4273788 100644
--- a/.claude/skills/create-control-manifest/SKILL.md
+++ b/.claude/skills/create-control-manifest/SKILL.md
@@ -128,9 +128,15 @@ Format:
> **Engine**: [name + version]
> **Last Updated**: [date]
+> **Manifest Version**: [date]
> **ADRs Covered**: [ADR-NNNN, ADR-MMMM, ...]
> **Status**: [Active — regenerate with `/create-control-manifest update` when ADRs change]
+`Manifest Version` is the date this manifest was generated. Story files embed
+this date when created. `/story-readiness` compares a story's embedded version
+to this field to detect stories written against stale rules. Always matches
+`Last Updated` — they are the same date, serving different consumers.
+
This manifest is a programmer's quick-reference extracted from all Accepted ADRs,
technical preferences, and engine reference docs. For the reasoning behind each
rule, see the referenced ADR.
diff --git a/.claude/skills/create-epics-stories/SKILL.md b/.claude/skills/create-epics-stories/SKILL.md
index 176e1b6d..286d6616 100644
--- a/.claude/skills/create-epics-stories/SKILL.md
+++ b/.claude/skills/create-epics-stories/SKILL.md
@@ -57,12 +57,20 @@ Read everything before generating any output:
Addressed", "Implementation Guidelines", "Engine Compatibility", and
"ADR Dependencies" sections
- `docs/architecture/control-manifest.md` if it exists — extract layer-specific
- rules to embed in stories
+ rules to embed in stories; also extract the `Manifest Version:` date from the
+ header block (this gets embedded in every story)
+
+### TR Registry
+- `docs/architecture/tr-registry.yaml` if it exists — read all active entries,
+ indexed by `id`. Used to resolve TR-IDs for each GDD requirement. If the
+ registry does not exist, note it once; stories will use `TR-[system]-???`
+ placeholders with a warning.
### Engine Reference
- `docs/engine-reference/[engine]/VERSION.md` — engine name + version + risk levels
Report: "Loaded [N] GDDs, [M] ADRs, control manifest: [exists/missing],
+manifest version: [date or N/A], TR registry: [N entries or missing],
engine: [name + version]."
---
@@ -128,8 +136,17 @@ For each epic, decompose the GDD's acceptance criteria into stories:
For each story, map:
- **GDD requirement**: Which specific acceptance criterion does this satisfy?
-- **TR-ID**: The technical requirement ID (from `/architecture-review` traceability matrix, if run)
-- **Governing ADR**: Which Accepted ADR tells the programmer how to implement this?
+- **TR-ID**: Look up the matching entry in `tr-registry.yaml` by normalizing the
+ requirement text (lowercase, trimmed). Use the stable ID from the registry.
+ If no matching entry exists, note `TR-[system]-???` and warn the user to run
+ `/architecture-review` to register the ID before this story is assigned.
+- **Governing ADR**: Which ADR tells the programmer how to implement this?
+ **Important — ADR status gate**: check the ADR's `Status:` field.
+ - If `Status: Accepted` → embed normally.
+ - If `Status: Proposed` → set story `Status: Blocked` and note:
+ `BLOCKED: ADR-NNNN is still Proposed — story cannot be safely implemented
+ until the ADR is Accepted. Run /architecture-decision to advance it.`
+ - Do not embed implementation guidance from a Proposed ADR.
- **Engine risk**: Inherited from the ADR's Knowledge Risk field
- **Control manifest rules**: Which layer rules apply?
@@ -145,11 +162,13 @@ For each story, produce a story file embedding full context:
> **Epic**: [epic name]
> **Status**: Ready
> **Layer**: [Foundation / Core / Feature / Presentation]
+> **Manifest Version**: [date from control-manifest.md header — or "N/A" if manifest not yet created]
## Context
**GDD**: `design/gdd/[filename].md`
-**Requirement**: TR-[GDD]-[NNN]: [requirement text from GDD]
+**Requirement**: `TR-[system]-NNN`
+*(Requirement text is stored in `docs/architecture/tr-registry.yaml` — look up by ID at review time)*
**ADR Governing Implementation**: [ADR-NNNN: title]
**ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]
@@ -296,5 +315,10 @@ After writing all epics for the requested scope, remind the user:
5. **No invention** — all acceptance criteria come from GDDs; all implementation
notes come from ADRs; all rules come from the control manifest. Never invent
requirements or rules that don't trace to a source document.
-6. **Preserve exact quotes** — when embedding GDD requirements and ADR guidelines,
- quote them exactly; do not paraphrase in ways that change meaning
+6. **Reference by TR-ID, not by quote** — embed the stable `TR-[system]-NNN` ID
+ in the story, not the GDD requirement text. The text lives in the registry and
+ is read fresh at review time. This prevents false deviation flags when GDD
+ wording is clarified after the story was written.
+7. **Never embed Proposed ADRs** — if the governing ADR is Proposed, set the
+ story status to Blocked. Embedding implementation guidance from an unaccepted
+ ADR creates silent risk when the ADR changes.
diff --git a/.claude/skills/design-system/SKILL.md b/.claude/skills/design-system/SKILL.md
index 1da85f30..e84abbdf 100644
--- a/.claude/skills/design-system/SKILL.md
+++ b/.claude/skills/design-system/SKILL.md
@@ -10,13 +10,45 @@ When this skill is invoked:
## 1. Parse Arguments & Validate
-A system name argument is **required**. If missing, fail with:
+A system name or retrofit path is **required**. If missing, fail with:
> "Usage: `/design-system <system-name>` — e.g., `/design-system combat-system`
+> Or to fill gaps in an existing GDD: `/design-system retrofit design/gdd/combat-system.md`
> Run `/map-systems` first to create the systems index, then use this skill
> to write individual system GDDs."
-Normalize the system name to kebab-case for the filename (e.g., "combat system"
-becomes `combat-system`).
+**Detect retrofit mode:**
+If the argument starts with `retrofit` or the argument is a file path to an
+existing `.md` file in `design/gdd/`, enter **retrofit mode**:
+
+1. Read the existing GDD file.
+2. Identify which of the 8 required sections are present (scan for section headings).
+ Required sections: Overview, Player Fantasy, Detailed Design/Rules, Formulas,
+ Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.
+3. Identify which sections contain only placeholder text (`[To be designed]` or
+ equivalent — blank, a single line, or obviously incomplete).
+4. Present to the user before doing anything:
+ ```
+ ## Retrofit: [System Name]
+ File: design/gdd/[filename].md
+
+ Sections already written (will not be touched):
+ ✓ [section name]
+ ✓ [section name]
+
+ Missing or incomplete sections (will be authored):
+ ✗ [section name] — missing
+ ✗ [section name] — placeholder only
+ ```
+5. Ask: "Shall I fill the [N] missing sections? I will not modify any existing content."
+6. If yes: proceed to **Phase 2 (Gather Context)** as normal, but in **Phase 3**
+ skip creating the skeleton (file already exists) and in **Phase 4** skip
+ sections that are already complete. Only run the section cycle for missing/
+ incomplete sections.
+7. **Never overwrite existing section content.** Use Edit tool to replace only
+ `[To be designed]` placeholders or empty section bodies.
+
+If NOT in retrofit mode, normalize the system name to kebab-case for the
+filename (e.g., "combat system" becomes `combat-system`).
---
diff --git a/.claude/skills/help/SKILL.md b/.claude/skills/help/SKILL.md
new file mode 100644
index 00000000..309a4b4d
--- /dev/null
+++ b/.claude/skills/help/SKILL.md
@@ -0,0 +1,198 @@
+---
+name: help
+description: "Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now or I'm stuck or I don't know what to do"
+argument-hint: "[optional: what you just finished, e.g. 'finished design-review' or 'stuck on ADRs']"
+user-invocable: true
+allowed-tools: Read, Glob, Grep
+---
+
+# Studio Help — What Do I Do Next?
+
+This skill figures out exactly where you are in the game development pipeline and
+tells you what comes next. It is **lightweight** — not a full audit. For a full
+gap analysis, use `/project-stage-detect`.
+
+---
+
+## Step 1: Read the Catalog
+
+Read `.claude/docs/workflow-catalog.yaml`. This is the authoritative list of all
+phases, their steps (in order), whether each step is required or optional, and
+the artifact globs that indicate completion.
+
+---
+
+## Step 2: Determine Current Phase
+
+Check in this order:
+
+1. **Read `production/stage.txt`** — if it exists and has content, this is the
+ authoritative phase name. Map it to a catalog phase key:
+ - "Concept" → `concept`
+ - "Systems Design" → `systems-design`
+ - "Technical Setup" → `technical-setup`
+ - "Pre-Production" → `pre-production`
+ - "Production" → `production`
+ - "Polish" → `polish`
+ - "Release" → `release`
+
+2. **If stage.txt is missing**, infer phase from artifacts (most-advanced match wins):
+ - `src/` has 10+ source files → `production`
+ - `production/stories/*.md` exists → `pre-production`
+ - `docs/architecture/adr-*.md` exists → `technical-setup`
+ - `design/gdd/systems-index.md` exists → `systems-design`
+ - `design/gdd/game-concept.md` exists → `concept`
+ - Nothing → `concept` (fresh project)
+
+---
+
+## Step 3: Read Session Context
+
+Read `production/session-state/active.md` if it exists. Extract:
+- What was most recently worked on
+- Any in-progress tasks or open questions
+- Current epic/feature/task from STATUS block (if present)
+
+This tells you what the user just finished or is stuck on — use it to personalize
+the output.
+
+---
+
+## Step 4: Check Step Completion for the Current Phase
+
+For each step in the current phase (from the catalog):
+
+### Artifact-based checks
+
+If the step has `artifact.glob`:
+- Use Glob to check if files matching the pattern exist
+- If `min_count` is specified, verify at least that many files match
+- If `artifact.pattern` is specified, use Grep to verify the pattern exists in the matched file
+- **Complete** = artifact condition is met
+- **Incomplete** = artifact is missing or pattern not found
+
+If the step has `artifact.note` (no glob):
+- Mark as **MANUAL** — cannot auto-detect, will ask user
+
+If the step has no `artifact` field:
+- Mark as **UNKNOWN** — completion not trackable (e.g. repeatable implementation work)
+
+### Special case: production phase — read `sprint-status.yaml`
+
+When the current phase is `production`, check for `production/sprint-status.yaml`
+before doing any glob-based story checks. If it exists, read it directly:
+
+- Stories with `status: in-progress` → surface as "currently active"
+- Stories with `status: ready-for-dev` → surface as "next up"
+- Stories with `status: done` → count as complete
+- Stories with `status: blocked` → surface as blocker with the `blocker` field
+
+This gives precise per-story status without markdown scanning. Skip the glob
+artifact check for the `implement` and `story-done` steps — the YAML is authoritative.
+
+### Special case: `repeatable: true` (non-production)
+
+For repeatable steps outside production (e.g. "System GDDs"), the artifact
+check tells you whether *any* work has been done, not whether it's finished.
+Label these differently — show what's been detected, then note it may be ongoing.
+
+---
+
+## Step 5: Find Position and Identify Next Steps
+
+From the completion data, determine:
+
+1. **Last confirmed complete step** — the furthest completed required step
+2. **Current blocker** — the first incomplete *required* step (this is what the
+ user must do next)
+3. **Optional opportunities** — incomplete *optional* steps that can be done
+ before or alongside the blocker
+4. **Upcoming required steps** — required steps after the current blocker
+ (show as "coming up" so user can plan ahead)
+
+If the user provided an argument (e.g. "just finished design-review"), use that
+to advance past the step they named even if the artifact check is ambiguous.
+
+---
+
+## Step 6: Check for In-Progress Work
+
+If `active.md` shows an active task or epic:
+- Surface it prominently at the top: "It looks like you were working on [X]"
+- Suggest continuing it or confirm if it's done
+
+---
+
+## Step 7: Present Output
+
+Keep it **short and direct**. This is a quick orientation, not a report.
+
+```
+## Where You Are: [Phase Label]
+
+**In progress:** [from active.md, if any]
+
+### ✓ Done
+- [completed step name]
+- [completed step name]
+
+### → Next up (REQUIRED)
+**[Step name]** — [description]
+Command: `[/command]`
+
+### ~ Also available (OPTIONAL)
+- **[Step name]** — [description] → `/command`
+- **[Step name]** — [description] → `/command`
+
+### Coming up after that
+- [Next required step name] (`/command`)
+- [Next required step name] (`/command`)
+
+---
+Approaching **[next phase]** gate → run `/gate-check` when ready.
+```
+
+**Formatting rules:**
+- `✓` for confirmed complete
+- `→` for the current required next step (only one — the first blocker)
+- `~` for optional steps available now
+- Show commands inline as backtick code
+- If a step has no command (e.g. "Implement Stories"), explain what to do instead of showing a slash command
+- For MANUAL steps, ask the user: "I can't tell if [step] is done — has it been completed?"
+
+---
+
+## Step 8: Gate Warning (if close)
+
+After the current phase's steps, check if the user is likely approaching a gate:
+- If all required steps in the current phase are complete (or nearly complete),
+ add: "You're close to the **[Current] → [Next]** gate. Run `/gate-check` when ready."
+- If multiple required steps remain, skip the gate warning — it's not relevant yet.
+
+---
+
+## Step 9: Escalation Paths
+
+After the recommendations, if the user seems stuck or confused, add:
+
+```
+---
+Need more detail?
+- `/project-stage-detect` — full gap analysis with all missing artifacts listed
+- `/gate-check` — formal readiness check for your next phase
+- `/start` — re-orient from scratch
+```
+
+Only show this if the user's input suggested confusion (e.g. "I don't know", "stuck",
+"lost", "not sure"). Don't show it for simple "what's next?" queries.
+
+---
+
+## Collaborative Protocol
+
+- **Never auto-run the next skill.** Recommend it, let the user invoke it.
+- **Ask about MANUAL steps** rather than assuming complete or incomplete.
+- **Match the user's tone** — if they sound stressed ("I'm totally lost"), be
+ reassuring and give one action, not a list of six.
+- **One primary recommendation** — the user should leave knowing exactly one thing
+ to do next. Optional steps and "coming up" are secondary context.
diff --git a/.claude/skills/review-all-gdds/SKILL.md b/.claude/skills/review-all-gdds/SKILL.md
index a136c79e..a0e7c554 100644
--- a/.claude/skills/review-all-gdds/SKILL.md
+++ b/.claude/skills/review-all-gdds/SKILL.md
@@ -403,7 +403,9 @@ If any GDDs are flagged for revision:
Ask: "Should I update the systems index to mark these GDDs as needing revision?"
- If yes: for each flagged GDD, update its Status field in systems-index.md
- to "Needs Revision (Cross-GDD Review)" with a short note on why.
+ to "Needs Revision" with a short note in the adjacent Notes/Description column.
+ (Do NOT append parentheticals to the status value — other skills match "Needs Revision"
+ as an exact string and parentheticals break that match.)
Ask approval before writing.
---
diff --git a/.claude/skills/sprint-plan/SKILL.md b/.claude/skills/sprint-plan/SKILL.md
index 1bada8c0..66a2729b 100644
--- a/.claude/skills/sprint-plan/SKILL.md
+++ b/.claude/skills/sprint-plan/SKILL.md
@@ -101,6 +101,47 @@ For `status`:
- [Any new risks identified this sprint]
```
+### Sprint Status File
+
+After generating a new sprint plan, also write `production/sprint-status.yaml`.
+This is the machine-readable source of truth for story status — read by
+`/sprint-status`, `/story-done`, and `/help` without markdown parsing.
+
+Ask: "May I also write `production/sprint-status.yaml` to track story status?"
+
+Format:
+
+```yaml
+# Auto-generated by /sprint-plan. Updated by /story-done.
+# DO NOT edit manually — use /story-done to update story status.
+
+sprint: [N]
+goal: "[sprint goal]"
+start: "[YYYY-MM-DD]"
+end: "[YYYY-MM-DD]"
+generated: "[YYYY-MM-DD]"
+updated: "[YYYY-MM-DD]"
+
+stories:
+ - id: "[epic-story, e.g. 1-1]"
+ name: "[story name]"
+ file: "[production/stories/path.md]"
+ priority: must-have # must-have | should-have | nice-to-have
+ status: ready-for-dev # backlog | ready-for-dev | in-progress | review | done | blocked
+ owner: ""
+ estimate_days: 0
+ blocker: ""
+ completed: ""
+```
+
+Initialize each story from the sprint plan's task tables:
+- Must Have tasks → `priority: must-have`, `status: ready-for-dev`
+- Should Have tasks → `priority: should-have`, `status: backlog`
+- Nice to Have tasks → `priority: nice-to-have`, `status: backlog`
+
+For `update`: read the existing `sprint-status.yaml`, carry over statuses for
+stories that haven't changed, add new stories, remove dropped ones.
+
### Agent Consultation
For comprehensive sprint planning, consider consulting:
diff --git a/.claude/skills/sprint-status/SKILL.md b/.claude/skills/sprint-status/SKILL.md
index 5aadb03e..3c7042f8 100644
--- a/.claude/skills/sprint-status/SKILL.md
+++ b/.claude/skills/sprint-status/SKILL.md
@@ -51,7 +51,14 @@ found — burndown assessment skipped."
## 3. Scan Story Status
-For each story or task referenced in the sprint plan:
+**First: check for `production/sprint-status.yaml`.**
+
+If it exists, read it directly — it is the authoritative source of truth.
+Extract status for each story from the `status` field. No markdown scanning needed.
+Use its `sprint`, `goal`, `start`, `end` fields instead of re-parsing the sprint plan.
+
+**If `sprint-status.yaml` does not exist** (legacy sprint or first-time setup),
+fall back to markdown scanning:
1. If the entry references a story file path, check if the file exists.
Read the file and scan for status markers: DONE, COMPLETE, IN PROGRESS,
@@ -61,6 +68,9 @@ For each story or task referenced in the sprint plan:
3. If no status marker is found, classify as NOT STARTED.
4. If a file is referenced but does not exist, classify as MISSING and note it.
+When using the fallback, add a note at the bottom of the output:
+"⚠ No `sprint-status.yaml` found — status inferred from markdown. Run `/sprint-plan update` to generate one."
+
Optionally (fast check only — do not do a deep scan): grep `src/` for a
directory or file name that matches the story's system slug to check for
implementation evidence. This is a hint only, not a definitive status.
diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md
index 58c92fb7..3d6abf1e 100644
--- a/.claude/skills/start/SKILL.md
+++ b/.claude/skills/start/SKILL.md
@@ -118,19 +118,43 @@ The user knows what they want to make but hasn't documented it.
#### If D: Existing work
-The user has artifacts already. Figure out what exists and what's missing.
+The user has artifacts already. Two questions matter: what phase are they in,
+and are their existing artifacts in a format the template's skills can use.
1. Share what you found in Step 1 (now it's relevant):
- "I can see you have [X source files / Y design docs / Z prototypes]..."
- "Your engine is [configured as X / not yet configured]..."
-2. Recommend running `/project-stage-detect` for a full analysis
-3. If the engine isn't configured, note that `/setup-engine` should come first
-4. Show the recommended path:
- - `/project-stage-detect` — full gap analysis
- - `/setup-engine` — if not configured
- - `/design-system` — if systems index exists but GDDs are incomplete
+
+2. **Distinguish two sub-cases based on what exists:**
+
+ **Sub-case D1 — Artifacts exist but engine is not configured / very early stage**
+ (game concept exists but no GDDs or ADRs):
+ - This is close to a greenfield project. Route normally:
+ - Recommend `/setup-engine` first if engine not configured
+ - Then `/project-stage-detect` for a gap inventory
+ - Then pick up the normal pipeline from the detected phase
+
+ **Sub-case D2 — GDDs, ADRs, or stories already exist** (non-trivial existing work):
+ - The project needs a format compliance check, not just an existence check.
+ - Explain the distinction clearly:
+ > "Having files isn't the same as the template's skills being able to use them.
+ > GDDs might be missing required sections. ADRs might lack Status fields that
+ > story validation depends on. `/adopt` checks this specifically."
+ - Recommend this two-step path:
+ 1. `/project-stage-detect` — understand what phase and what's missing entirely
+ 2. `/adopt` — audit whether existing artifacts are in the right internal format,
+ and get a numbered migration plan to bring them up to standard
+ - Note: `/adopt` is what produces the actionable "what to fix" plan. After that,
+ existing skills handle each fix: `/design-system retrofit`, `/architecture-decision retrofit`, etc.
+
+3. Show the recommended path for D2:
+ - `/project-stage-detect` — phase detection + existence gaps
+ - `/adopt` — **format compliance audit + migration plan** (the key brownfield tool)
+ - `/setup-engine` — if engine not configured
+ - `/design-system retrofit [path]` — fill missing GDD sections
+ - `/architecture-decision retrofit [path]` — add missing ADR sections
+ - `/architecture-review` — bootstrap the TR requirement registry
- `/gate-check` — validate readiness for next phase
- - `/sprint-plan` — organize the work
---
diff --git a/.claude/skills/story-done/SKILL.md b/.claude/skills/story-done/SKILL.md
index 085074de..9e72f349 100644
--- a/.claude/skills/story-done/SKILL.md
+++ b/.claude/skills/story-done/SKILL.md
@@ -40,7 +40,8 @@ read that file directly.
Read the full story file. Extract and hold in context:
- **Story name and ID**
-- **GDD Requirement ID(s)** referenced
+- **GDD Requirement TR-ID(s)** referenced (e.g., `TR-combat-001`)
+- **Manifest Version** embedded in the story header (e.g., `2026-03-10`)
- **ADR reference(s)** referenced
- **Acceptance Criteria** — the complete list (every checkbox item)
- **Implementation files** — files listed under "files to create/modify"
@@ -49,9 +50,15 @@ Read the full story file. Extract and hold in context:
- **Estimated vs actual scope** — if an estimate was noted
Also read:
+- `docs/architecture/tr-registry.yaml` — look up each TR-ID in the story.
+ Read the *current* `requirement` text from the registry entry. This is the
+ source of truth for what the GDD required — do not use any requirement text
+ that may be quoted inline in the story (it may be stale).
- The referenced GDD section — just the acceptance criteria and key rules, not
- the full document
+ the full document. Use this to cross-check the registry text is still accurate.
- The referenced ADR(s) — just the Decision and Consequences sections
+- `docs/architecture/control-manifest.md` header — extract the current
+ `Manifest Version:` date (used in Phase 4 staleness check)
---
@@ -96,19 +103,29 @@ Compare the implementation against the design documents.
Run these checks automatically:
-1. **GDD rules check**: Read the GDD section referenced in the story. `Grep` the
- implemented files for key function names, data structures, or class names
- mentioned in the GDD. If the GDD specifies a formula, check for recognizable
- variable names from that formula.
-
-2. **ADR constraints check**: Read the referenced ADR's Decision section. Check
+1. **GDD rules check**: Using the current requirement text from `tr-registry.yaml`
+ (looked up by the story's TR-ID), check that the implementation reflects what
+ the GDD actually requires now — not what it required when the story was written.
+ `Grep` the implemented files for key function names, data structures, or class
+ names mentioned in the current GDD section.
+
+2. **Manifest version staleness check**: Compare the `Manifest Version:` date
+ embedded in the story header against the `Manifest Version:` date in the
+ current `docs/architecture/control-manifest.md` header.
+ - If they match → pass silently.
+ - If the story's version is older → flag as ADVISORY:
+ `ADVISORY: Story was written against manifest v[story-date]; current manifest
+ is v[current-date]. New rules may apply. Run /story-readiness to check.`
+ - If control-manifest.md does not exist → skip this check.
+
+3. **ADR constraints check**: Read the referenced ADR's Decision section. Check
for forbidden patterns from `docs/architecture/control-manifest.md` (if it
exists). `Grep` for patterns explicitly forbidden in the ADR.
-3. **Hardcoded values check**: `Grep` the implemented files for numeric literals
+4. **Hardcoded values check**: `Grep` the implemented files for numeric literals
in gameplay logic that should be in data files.
-4. **Scope check**: Did the implementation touch files outside the story's stated
+5. **Scope check**: Did the implementation touch files outside the story's stated
scope? (files not listed in "files to create/modify")
For each deviation found, categorize:
@@ -201,6 +218,12 @@ If yes, edit the story file:
3. If advisory deviations exist, ask: "Should I log these as tech debt in
`docs/tech-debt-register.md`?"
+4. **Update `production/sprint-status.yaml`** (if it exists):
+ - Find the entry matching this story's file path or ID
+ - Set `status: done` and `completed: [today's date]`
+ - Update the top-level `updated` field
+ - This is a silent update — no extra approval needed (already approved in step above)
+
---
## Phase 8: Surface the Next Story
diff --git a/.claude/skills/story-readiness/SKILL.md b/.claude/skills/story-readiness/SKILL.md
index 42c61e59..e5021a86 100644
--- a/.claude/skills/story-readiness/SKILL.md
+++ b/.claude/skills/story-readiness/SKILL.md
@@ -47,6 +47,14 @@ Before checking any stories, load reference documents once (not per-story):
- `design/gdd/systems-index.md` — to know which systems have approved GDDs
- `docs/architecture/control-manifest.md` — to know which manifest rules exist
(if the file does not exist, note it as missing once; do not re-flag per story)
+ Also extract the `Manifest Version:` date from the header block if the file exists.
+- `docs/architecture/tr-registry.yaml` — index all entries by `id`. Used to
+ validate TR-IDs in stories. If the file does not exist, note it once; TR-ID
+ checks will auto-pass for all stories (registry predates stories, so missing
+ registry means stories are from before TR tracking was introduced).
+- All ADR status fields — for each unique ADR referenced across the stories being
+ checked, read the ADR file and note its `Status:` field. Cache these so you
+ don't re-read the same ADR for every story.
- The current sprint file (if scope is `sprint`) — to identify Must Have /
Should Have priority for escalation decisions
@@ -77,9 +85,34 @@ items pass or are explicitly marked N/A with a stated reason.
### Architecture Completeness
-- [ ] **ADR referenced or N/A stated**: The story references at least one
- Accepted ADR, OR explicitly states "No ADR applies" with a brief reason.
+- [ ] **ADR referenced or N/A stated**: The story references at least one ADR,
+ OR explicitly states "No ADR applies" with a brief reason.
A story with no ADR reference and no explicit N/A note fails this check.
+- [ ] **ADR is Accepted (not Proposed)**: For each referenced ADR, check its
+ `Status:` field using the cached ADR statuses loaded in Section 2.
+ - If `Status: Accepted` → pass.
+ - If `Status: Proposed` → **BLOCKED**: the ADR may change before it is accepted,
+ and the story's implementation guidance could be wrong.
+ Fix: `BLOCKED: ADR-NNNN is Proposed — wait for acceptance before implementing.`
+ - If the ADR file does not exist → **BLOCKED**: referenced ADR is missing.
+ - Auto-pass if story has an explicit "No ADR applies" N/A note.
+- [ ] **TR-ID is valid and active**: If the story contains a `TR-[system]-NNN`
+ reference, look it up in the TR registry loaded in Section 2.
+ - If the ID exists and `status: active` → pass.
+ - If the ID exists and `status: deprecated` or `status: superseded-by: ...` →
+ NEEDS WORK: the requirement was removed or replaced.
+ Fix: update the story to reference the current requirement ID or remove if no longer applicable.
+ - If the ID does not exist in the registry → NEEDS WORK: ID was not registered
+ (story may predate registry, or registry needs an `/architecture-review` run).
+ - Auto-pass if the story has no TR-ID reference OR if the registry does not exist.
+- [ ] **Manifest version is current**: If the story has a `Manifest Version:` date
+ in its header AND `docs/architecture/control-manifest.md` exists:
+ - If story version matches current manifest `Manifest Version:` → pass.
+ - If story version is older than current manifest → NEEDS WORK: new rules may
+ apply. Fix: review changed manifest rules, update story if any forbidden/required
+ entries changed, then update the story's `Manifest Version:` to current.
+ - Auto-pass if either the story has no `Manifest Version:` field OR the manifest
+ does not exist.
- [ ] **Engine notes present**: For any post-cutoff engine API this story
is likely to touch, implementation notes or a verification requirement are
included. If the story clearly does not touch engine APIs (e.g., it is a
diff --git a/docs/architecture/tr-registry.yaml b/docs/architecture/tr-registry.yaml
new file mode 100644
index 00000000..97935084
--- /dev/null
+++ b/docs/architecture/tr-registry.yaml
@@ -0,0 +1,56 @@
+# Technical Requirement ID Registry
+#
+# PURPOSE: Persistent, stable IDs for every GDD technical requirement.
+# Prevents TR-ID renumbering across /architecture-review runs, which would
+# break story references.
+#
+# RULES:
+# - IDs are PERMANENT. Never renumber, never delete (use status: deprecated).
+# - Add new entries only at the END of each system's list.
+# - When a GDD requirement is reworded (same intent): update `requirement`
+# text and add a `revised` date. The ID stays the same.
+# - When a requirement is removed from the GDD: set status: deprecated.
+# - When a requirement is split or replaced: set status: superseded-by with
+# the new TR-ID(s).
+#
+# WRITTEN BY: /architecture-review (appends new entries, never overwrites)
+# READ BY: /create-epics-stories (embed IDs in stories)
+# /story-done (look up current requirement text at review time)
+# /story-readiness (validate TR-ID exists and is active)
+#
+# ID FORMAT: TR-[system-slug]-[NNN]
+# system-slug = short slug matching the GDD system name
+# NNN = three-digit zero-padded sequence per system, starting at 001
+#
+# STATUS VALUES: active | deprecated | superseded-by: TR-[system]-NNN
+
+version: 1
+last_updated: ""
+
+requirements: []
+
+# --- EXAMPLE ENTRIES (remove when first real entries are added) ---
+#
+# - id: TR-combat-001
+# system: combat
+# gdd: design/gdd/combat-system.md
+# requirement: "Player takes damage from enemies based on attack power minus defence"
+# created: 2026-03-10
+# revised: ""
+# status: active
+#
+# - id: TR-combat-002
+# system: combat
+# gdd: design/gdd/combat-system.md
+# requirement: "Combo window timing is 0.4 seconds between hits"
+# created: 2026-03-10
+# revised: "2026-04-01"
+# status: active
+#
+# - id: TR-combat-003
+# system: combat
+# gdd: design/gdd/combat-system.md
+# requirement: "Old damage formula using raw stats"
+# created: 2026-03-10
+# revised: ""
+# status: superseded-by: TR-combat-001