Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Shell ai-agentsai-assisted-developmentanthropicclaudeclaude-codegame-designgame-developmentgamedevgodotindie-game-devunityunreal-engine
Pipeline integrity + brownfield adoption system
Donchitos0bbf25ec3171
diff --git a/.claude/agent-memory/lead-programmer/MEMORY.md b/.claude/agent-memory/lead-programmer/MEMORY.mdnew file mode 100644index 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.yamlnew file mode 100644index 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.mdnew file mode 100644index 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 contentdiff --git a/.claude/skills/architecture-decision/SKILL.md b/.claude/skills/architecture-decision/SKILL.mdindex 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, WriteWhen 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.mdindex 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 thearchitecture must provide for the system to work. A technical requirement is anystatement that implies a specific architectural decision.@@ -251,8 +272,11 @@ If no revision flags are found, write: "No GDD revision flags — all GDD assumpare 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].mAlso ask: "May I update `docs/architecture/architecture-traceability.md` with thecurrent 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:```markdowndiff --git a/.claude/skills/create-control-manifest/SKILL.md b/.claude/skills/create-control-manifest/SKILL.mdindex 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 eachrule, see the referenced ADR.diff --git a/.claude/skills/create-epics-stories/SKILL.md b/.claude/skills/create-epics-stories/SKILL.mdindex 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 levelsReport: "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 implementationnotes come from ADRs; all rules come from the control manifest. Never inventrequirements 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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.mdindex 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 ConsultationFor comprehensive sprint planning, consider consulting:diff --git a/.claude/skills/sprint-status/SKILL.md b/.claude/skills/sprint-status/SKILL.mdindex 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 adirectory or file name that matches the story's system slug to check forimplementation evidence. This is a hint only, not a definitive status.diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.mdindex 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.mdindex 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 notedAlso 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. Checkfor forbidden patterns from `docs/architecture/control-manifest.md` (if itexists). `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 literalsin 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 statedscope? (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 Storydiff --git a/.claude/skills/story-readiness/SKILL.md b/.claude/skills/story-readiness/SKILL.mdindex 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 storyis likely to touch, implementation notes or a verification requirement areincluded. If the story clearly does not touch engine APIs (e.g., it is adiff --git a/docs/architecture/tr-registry.yaml b/docs/architecture/tr-registry.yamlnew file mode 100644index 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