diff --git a/.claude/docs/templates/architecture-decision-record.md b/.claude/docs/templates/architecture-decision-record.md index 7bdda2c..0bc567a 100644 --- a/.claude/docs/templates/architecture-decision-record.md +++ b/.claude/docs/templates/architecture-decision-record.md @@ -6,12 +6,25 @@ ## Date -[YYYY-MM-DD] +[YYYY-MM-DD — when this ADR was written] + +## Last Verified + +[YYYY-MM-DD — when this ADR was last confirmed accurate against the current +engine version and design. Update this date when you re-read and confirm it +is still correct, even if nothing changed.] ## Decision Makers [Who was involved in this decision] +## Summary + +[2 sentences: what problem this ADR solves, and what was decided. Written for +tiered context loading — a skill scanning 20 ADRs uses this to decide whether +to read the full decision. Be specific: name the system, the problem, and the +chosen approach.] + ## Engine Compatibility | Field | Value | diff --git a/.claude/docs/templates/game-design-document.md b/.claude/docs/templates/game-design-document.md index bd4cd00..e17d95a 100644 --- a/.claude/docs/templates/game-design-document.md +++ b/.claude/docs/templates/game-design-document.md @@ -3,8 +3,17 @@ > **Status**: Draft | In Review | Approved | Implemented > **Author**: [Agent or person] > **Last Updated**: [Date] +> **Last Verified**: [Date — when this doc was last confirmed accurate against current design] > **Implements Pillar**: [Which game pillar this supports] +## Summary + +[2–3 sentences: what this system is, what it does for the player, and why it +exists in this game. Written for tiered context loading — a skill scanning +20 GDDs uses this section to decide whether to read further. No jargon.] + +> **Quick reference** — Layer: `[Foundation | Core | Feature | Presentation]` · Priority: `[MVP | Vertical Slice | Alpha | Full Vision]` · Key deps: `[System names or "None"]` + ## Overview [One paragraph that explains this mechanic to someone who knows nothing about @@ -174,6 +183,24 @@ These are subjective targets stated precisely enough to get consistent verdicts. | Information | Display Location | Update Frequency | Condition | |-------------|-----------------|-----------------|-----------| +## Cross-References + +[Declare every explicit dependency on another GDD's specific mechanic, value, or +rule. This table is machine-checked by `/review-all-gdds` Phase 2c — it replaces +implicit prose references with verifiable declarations. If you reference another +system's behaviour anywhere in this document, it must appear here.] + +| This Document References | Target GDD | Specific Element Referenced | Nature | +|--------------------------|-----------|----------------------------|--------| +| [e.g., "combo multiplier feeds score"] | `design/gdd/score.md` | `combo_multiplier` output value | Data dependency | +| [e.g., "death triggers respawn"] | `design/gdd/respawn.md` | Death state transition | State trigger | +| [e.g., "stamina gates dodge"] | `design/gdd/stamina.md` | Stamina depletion rule | Rule dependency | + +> **Note on "Nature"**: use one of — `Data dependency` (we consume their output), +> `State trigger` (their state change triggers our behaviour), `Rule dependency` +> (our rule assumes their rule is also true), `Ownership handoff` (we hand off +> ownership of a value to them). + ## Acceptance Criteria [Testable criteria that confirm this mechanic is working as designed.] diff --git a/.claude/skills/architecture-review/SKILL.md b/.claude/skills/architecture-review/SKILL.md index 3d97f96..0a907e4 100644 --- a/.claude/skills/architecture-review/SKILL.md +++ b/.claude/skills/architecture-review/SKILL.md @@ -26,14 +26,34 @@ and Pre-Production. ## Phase 1: Load Everything -Read all inputs before analysis: +### Phase 1a — L0: Summary Scan (fast, low tokens) + +Before reading any full document, use Grep to extract `## Summary` sections +from all GDDs and ADRs: + +``` +Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 4 +Grep pattern="## Summary" glob="docs/architecture/adr-*.md" output_mode="content" -A 3 +``` + +For `single-gdd [path]` mode: use the target GDD's summary to identify which +ADRs reference the same system (Grep ADRs for the system name), then full-read +only those ADRs. Skip full-reading unrelated GDDs entirely. + +For `engine` mode: only full-read ADRs — GDDs are not needed for engine checks. + +For `coverage` or `full` mode: proceed to full-read everything below. + +### Phase 1b — L1/L2: Full Document Load + +Read all inputs appropriate to the mode: ### Design Documents -- All GDDs in `design/gdd/` — read every file completely +- All in-scope GDDs in `design/gdd/` — read every file completely - `design/gdd/systems-index.md` — the authoritative list of systems ### Architecture Documents -- All ADRs in `docs/architecture/` — read every file completely +- All in-scope ADRs in `docs/architecture/` — read every file completely - `docs/architecture/architecture.md` if it exists ### Engine Reference @@ -389,6 +409,22 @@ If yes: This ensures all future story files can reference stable TR-IDs that persist across every subsequent architecture review. +### Session State Update + +After writing all approved files, silently append to +`production/session-state/active.md`: + + ## Session Extract — /architecture-review [date] + - Verdict: [PASS / CONCERNS / FAIL] + - Requirements: [N] total — [X] covered, [Y] partial, [Z] gaps + - New TR-IDs registered: [N, or "None"] + - GDD revision flags: [comma-separated GDD names, or "None"] + - Top ADR gaps: [top 3 gap titles from the report, or "None"] + - Report: docs/architecture/architecture-review-[date].md + +If `active.md` does not exist, create it with this block as the initial content. +Confirm in conversation: "Session state updated." + The traceability index format: ```markdown diff --git a/.claude/skills/content-audit/SKILL.md b/.claude/skills/content-audit/SKILL.md index ddafceb..0c4ba82 100644 --- a/.claude/skills/content-audit/SKILL.md +++ b/.claude/skills/content-audit/SKILL.md @@ -22,10 +22,20 @@ Parse the argument: 1. **Read `design/gdd/systems-index.md`** for the full list of systems, their categories, and MVP/priority tier. -2. **Read all GDD files** in `design/gdd/` (or the single system GDD if a - system name was given). +2. **L0 pre-scan**: Before full-reading any GDDs, Grep all GDD files for + `## Summary` sections plus common content-count keywords: + ``` + Grep pattern="(## Summary|N enemies|N levels|N items|N abilities|enemy types|item types)" glob="design/gdd/*.md" output_mode="files_with_matches" + ``` + For a single-system audit: skip this step and go straight to full-read. + For a full audit: full-read only the GDDs that matched content-count keywords. + GDDs with no content-count language (pure mechanics GDDs) are noted as + "No auditable content counts" without a full read. -3. **For each GDD, extract explicit content counts or lists.** Look for patterns +3. **Full-read in-scope GDD files** (or the single system GDD if a system + name was given). + +4. **For each GDD, extract explicit content counts or lists.** Look for patterns like: - "N enemies" / "enemy types:" / list of named enemies - "N levels" / "N areas" / "N maps" / "N stages" diff --git a/.claude/skills/create-epics-stories/SKILL.md b/.claude/skills/create-epics-stories/SKILL.md index 44a58a0..d1d327a 100644 --- a/.claude/skills/create-epics-stories/SKILL.md +++ b/.claude/skills/create-epics-stories/SKILL.md @@ -40,11 +40,28 @@ If no argument, use `AskUserQuestion`: ## 2. Load All Inputs -Read everything before generating any output: +### Step 2a — L0: Summary Scan + +Before full-reading any documents, Grep all GDDs for their `## Summary` sections: + +``` +Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5 +``` + +For `all` mode: display a manifest of all Approved/Designed GDDs with their +summaries so the user can confirm scope before the full load begins. + +For `layer:` or `[system-name]` modes: filter to only the target GDDs based +on the Summary quick-reference line (Layer + Priority). Skip full-reading +GDDs outside the requested scope entirely. + +### Step 2b — L1/L2: Full Document Load + +Read everything for the in-scope systems before generating any output: ### Design Documents - `design/gdd/systems-index.md` — authoritative system list, layers, status -- All GDDs in `design/gdd/` — read every file with "Approved" or "Designed" status +- In-scope GDDs in `design/gdd/` — read every file with "Approved" or "Designed" status - For each GDD, extract: - System name and layer (from systems-index.md) - All acceptance criteria (these become story acceptance criteria) diff --git a/.claude/skills/review-all-gdds/SKILL.md b/.claude/skills/review-all-gdds/SKILL.md index b1a8584..27f1649 100644 --- a/.claude/skills/review-all-gdds/SKILL.md +++ b/.claude/skills/review-all-gdds/SKILL.md @@ -38,17 +38,37 @@ completeness. This skill reviews the *relationships* between all GDDs. ## Phase 1: Load Everything -Read all design documents before any analysis: +### Phase 1a — L0: Summary Scan (fast, low tokens) + +Before reading any full document, use Grep to extract `## Summary` sections +from all GDD files: + +``` +Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5 +``` + +Display a manifest to the user: +``` +Found [N] GDDs. Summaries: + • combat.md — [summary text] + • inventory.md — [summary text] + ... +``` + +For `since-last-review` mode: run `git log --name-only` to identify GDDs +modified since the last review report file was written. Show the user which +GDDs are in scope based on summaries before doing any full reads. Only +proceed to L1 for those GDDs plus any GDDs listed in their "Key deps". + +### Phase 1b — L1/L2: Full Document Load + +Full-read the in-scope documents: 1. `design/gdd/game-concept.md` — game vision, core loop, MVP definition 2. `design/gdd/game-pillars.md` if it exists — design pillars and anti-pillars 3. `design/gdd/systems-index.md` — authoritative system list, layers, dependencies, status -4. **Every system GDD in `design/gdd/`** — read completely (skip game-concept.md - and systems-index.md — those are read above) - -For `since-last-review` mode: run `git log --name-only` to identify GDDs -modified since the last review report file was written. Only load those GDDs -plus any GDDs they depend on. +4. **Every in-scope system GDD in `design/gdd/`** — read completely (skip + game-concept.md and systems-index.md — those are read above) Report: "Loaded [N] system GDDs covering [M] systems. Pillars: [list]. Anti-pillars: [list]." @@ -510,6 +530,22 @@ Ask: "Should I update the systems index to mark these GDDs as needing revision?" as an exact string and parentheticals break that match.) Ask approval before writing. +### Session State Update + +After writing the report (and updating systems index if approved), silently +append to `production/session-state/active.md`: + + ## Session Extract — /review-all-gdds [date] + - Verdict: [PASS / CONCERNS / FAIL] + - GDDs reviewed: [N] + - Flagged for revision: [comma-separated list, or "None"] + - Blocking issues: [N — brief one-line descriptions, or "None"] + - Recommended next: [the Phase 7 handoff action, condensed to one line] + - Report: design/gdd/gdd-cross-review-[date].md + +If `active.md` does not exist, create it with this block as the initial content. +Confirm in conversation: "Session state updated." + --- ## Phase 7: Handoff diff --git a/.claude/skills/story-done/SKILL.md b/.claude/skills/story-done/SKILL.md index 9723ac0..dd895a3 100644 --- a/.claude/skills/story-done/SKILL.md +++ b/.claude/skills/story-done/SKILL.md @@ -269,6 +269,20 @@ If yes, edit the story file: - Update the top-level `updated` field - This is a silent update — no extra approval needed (already approved in step above) +### Session State Update + +After updating the story file, silently append to +`production/session-state/active.md`: + + ## Session Extract — /story-done [date] + - Verdict: [COMPLETE / COMPLETE WITH NOTES / BLOCKED] + - Story: [story file path] — [story title] + - Tech debt logged: [N items, or "None"] + - Next recommended: [next ready story title and path, or "None identified"] + +If `active.md` does not exist, create it with this block as the initial content. +Confirm in conversation: "Session state updated." + --- ## Phase 8: Surface the Next Story