Skip to content

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

Session memory extraction + tiered context loading improvements

Donchitoscdb1aa83b7ad
diff --git a/.claude/docs/templates/architecture-decision-record.md b/.claude/docs/templates/architecture-decision-record.md
index 7bdda2c9..0bc567a9 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 bd4cd00d..e17d95a9 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 3d97f96e..0a907e4c 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 ddafceb8..0c4ba825 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).
-
-3. **For each GDD, extract explicit content counts or lists.** Look for patterns
+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. **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 44a58a02..d1d327af 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 b1a85847..27f16499 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 9723ac0a..dd895a36 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