diff --git a/.claude/agent-memory/lead-programmer/MEMORY.md b/.claude/agent-memory/lead-programmer/MEMORY.md new file mode 100644 index 0000000..fb5a959 --- /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//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 0000000..31cbfb4 --- /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 0000000..c07b3e4 --- /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 daafab8..b352ae3 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 a9a8d29..f0f398d 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 e3c8b8f..a427378 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 176e1b6..286d661 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 1da85f3..e84abbd 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 ` — 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 0000000..309a4b4 --- /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 a136c79..a0e7c55 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 1bada8c..66a2729 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 5aadb03..3c7042f 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 58c92fb..3d6abf1 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 085074d..9e72f34 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. +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. **ADR constraints check**: Read the referenced ADR's Decision section. Check +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 42c61e5..e5021a8 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 0000000..9793508 --- /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