Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/authoring/create-architecture.md

Skill Test Spec: /create-architecture

Skill Summary

/create-architecture produces the master architecture document, docs/architecture/architecture.md. Phase 0 loads context and stops early when a prerequisite is missing: the engine reference docs (no engine → /setup-engine), design/gdd/systems-index.md (absent at standard/full → /map-systems), and design/gdd/game-concept.md (absent → /brainstorm; at minimal the one-page design/game-brief.md stands in). It extracts a Technical Requirements Baseline (TR-[system]-[NNN]) from the requirement-bearing sections of every GDD, inventories existing ADRs from their headers, and shows an Engine Knowledge Gap Inventory with an AskUserQuestion before authoring.

Phases 1–4 (layer map, module ownership, data flow, API boundaries) are each presented and approved. Phase 5 audits existing ADRs and maps every baseline requirement to ADR coverage; uncovered requirements become Required New ADRs. Phase 7 asks "All sections approved. May I write the master architecture document?" with [A]/[B]/[C] options. Phase 7b collects the TD-ARCHITECTURE and LP-FEASIBILITY reviews, presents them side by side, and asks before recording the sign-off in the Document Status section. Phase 8 updates production/session-state/active.md and prints a fixed handoff template.

An existing docs/architecture/architecture.md is never replaced unasked: Phase 0e offers to update chosen sections in place (raising the document's version), to rewrite it, or to stop. Focus-area arguments (layers, data-flow, api-boundaries, adr-audit) are that update with one section chosen; with no document yet, they offer the full walkthrough instead.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains sign-off verdict keywords in the gates' own words: APPROVE, CONCERNS, FEASIBLE, and the REVISED after … records
• Contains ask-before-write language: write approvals via AskUserQuestion ("May I write the master architecture document?", "May I update the Document Status section…")
• Has a next-step handoff at the end (/architecture-decision, /architecture-review, /create-control-manifest)
• Documents one consistent write model for docs/architecture/architecture.md — when the file is first created and when each approved section is written
• Documents gate behavior: TD-ARCHITECTURE + LP-FEASIBILITY in full mode; each skipped in lean/solo with a named note
• Documents the stop branches for a missing engine, systems index and game concept
• Documents retrofit: an existing docs/architecture/architecture.md is detected, and updating chosen sections is offered before any rewrite

---

Director Gate Checks

Review mode comes from the resolved review_mode (modes.review_mode in project.yaml); --review full|lean|solo overrides it for one run.

In full mode: after docs/architecture/architecture.md is written, TD-ARCHITECTURE (technical-director) and LP-FEASIBILITY (lead-programmer) review it. Each is a spawned agent that reads its own gate file (.claude/docs/director-gates/td-architecture.md, lp-feasibility.md); their inputs are independent, so they spawn together and both verdicts are collected before Step 3 presents them. The parent never reads those files: it passes TD-ARCHITECTURE the document path, the Technical Requirements Baseline (TR-IDs and count), the ADR list with statuses and the Engine Knowledge Gap Inventory.

In lean mode: neither is a PHASE-GATE, so both are skipped. Output notes "TD-ARCHITECTURE and LP-FEASIBILITY skipped — Lean mode."

In solo mode: both are skipped with "TD-ARCHITECTURE and LP-FEASIBILITY skipped — Solo mode."

---

Test Cases

Case 1: Happy Path — New architecture document, full mode, reviews approve

Fixture:

• project.yaml has engine.name: Godot, modes.review_mode: full, modes.workflow: full
• docs/engine-reference/godot/ has VERSION.md, breaking-changes.md, deprecated-apis.md, current-best-practices.md and modules/
• design/gdd/game-concept.md and design/gdd/systems-index.md exist with real content
• design/gdd/combat.md and design/gdd/inventory.md follow the GDD template
• docs/architecture/adr-0001-event-bus.md exists (Status: Accepted)
• No docs/architecture/architecture.md
• TD-ARCHITECTURE returns APPROVE; LP-FEASIBILITY returns FEASIBLE

Input: /create-architecture

Expected behavior:

1. Phase 0a reads the four engine docs and only the modules/ docs matching domains in the systems index
2. Phase 0b Greps the requirement-bearing sections of each GDD (Detailed Rules/Design, Formulas, Dependencies, Tuning Knobs, Acceptance Criteria) and presents the Technical Requirements Baseline with IDs such as TR-combat-001
3. Phase 0c builds the ADR inventory from ## Status/## Summary and **Domain** Greps, not full reads
4. Phase 0d shows the Engine Knowledge Gap Inventory and asks [A] Proceed — flag HIGH RISK domains… / [B] Let me check the engine reference first… / [C] Show me which domains are HIGH RISK and why
5. Phases 1–4: each proposal (layer map, ownership map, each data-flow scenario, API boundaries) is shown and approved before the next, and each approval is recorded in production/session-state/active.md — nothing is written to the architecture document before Phase 7
6. Phase 7: a one-paragraph summary, then "All sections approved. May I write the master architecture document?" with [A] Yes — write… / [B] Show me the full draft inline first… / [C] Not yet…
7. Phase 7b: TD-ARCHITECTURE (passed the document path, the TR baseline, the ADR list with statuses and the knowledge gap inventory) and LP-FEASIBILITY review the written document; both assessments are shown side by side; the user chooses Accept — proceed to handoff
8. The proposed Document Status block is shown, then "May I update the Document Status section with the sign-off results?"
9. Phase 8 writes a summary to production/session-state/active.md and prints the handoff with the headings "Architecture Complete", "Run These ADRs Next", "Gate-Check Readiness"; its Then: line names /architecture-review, then /create-control-manifest once the review passes, and the readiness block names /gate-check pre-production

Assertions:

• The baseline uses TR-[system]-[NNN] IDs and is built from the scanned GDD sections, not whole-file reads
• The knowledge gap inventory and its three-option AskUserQuestion come before Phase 1
• Each section is shown before its approval is asked
• The master document is written only after the Phase 7 AskUserQuestion approval
• TD-ARCHITECTURE and LP-FEASIBILITY are each spawned as agents (technical-director, lead-programmer) after the document is written, and both verdicts are collected before Step 3
• TD-ARCHITECTURE is passed its four context items by name; the parent session does not read the gate file
• The Document Status sign-off is written only after the "May I update" approval
• The handoff uses the fixed template headings, with no trailing commentary
• The handoff names /gate-check pre-production — never a [stage] placeholder, which while this skill runs would resolve to the gate already passed
• docs/architecture/architecture.md is not written, even in part, before the Phase 7 ask; Phases 2–4 approvals go to the session state

---

Case 2: Review Concerns — LP-FEASIBILITY returns CONCERNS

Fixture:

• Same as Case 1, up to Phase 7b
• LP-FEASIBILITY returns CONCERNS: "Save/load path has no owning module for serialisation"
• Scenario (a): TD-ARCHITECTURE returns APPROVE
• Scenario (b): TD-ARCHITECTURE returns NOT ASSESSED, naming a context item it could not read

Input: /create-architecture

Expected behavior:

1. Step 3 shows the Technical Director assessment and the Lead Programmer verdict side by side, including the specific concern
2. AskUserQuestion: Accept — proceed to handoff / Revise flagged items first / Discuss specific concerns
3. If Accept: the proposed Document Status reads LP-FEASIBILITY: [date] — CONCERNS (accepted), and is applied only after "May I update the Document Status section…" is answered yes
4. If Revise: the flagged section is re-drafted and approved as in Phases 1–4, the revised document is written once through Phase 7's ask, and the status then reads LP-FEASIBILITY: [date] — REVISED after CONCERNS
5. The skill does not record FEASIBLE for a review that returned CONCERNS
6. (b) Step 4 proposes TD-ARCHITECTURE: [date] — NOT ASSESSED — [missing input], never APPROVE, and the handoff's first line says NOT ASSESSED

Assertions:

• The concern text is shown to the user alongside the TD assessment
• The user is offered Accept / Revise flagged items first / Discuss specific concerns
• Accepting records CONCERNS (accepted), not FEASIBLE
• A revision records REVISED after CONCERNS, and the revised document is written once, after its sections are approved
• No Document Status change is written without the "May I update" approval
• (b) A NOT ASSESSED review is recorded with its missing input and never as an approval

---

Case 3: Lean and Solo Modes — Both reviews skipped, written with user approval only

Fixture:

• Same project as Case 1, but scenario (a): project.yaml has modes.review_mode: lean
• Scenario (b): same project, invoked with --review solo

Input: (a) /create-architecture (b) /create-architecture --review solo

Expected behavior:

1. Phases 0–7 run as in Case 1; the document is written after the Phase 7 approval
2. At Phase 7b neither review runs; output notes (a) "TD-ARCHITECTURE and LP-FEASIBILITY skipped — Lean mode." (b) "TD-ARCHITECTURE and LP-FEASIBILITY skipped — Solo mode."
3. Step 4 shows the Document Status block with both lines skipped — [mode] mode and asks before applying it; the skill then proceeds to the Phase 8 handoff without blocking on the skipped reviews

Assertions:

• Neither technical-director nor lead-programmer is spawned, and no TD-ARCHITECTURE review is applied in lean or solo mode
• The skip note names both gates and the mode
• (b) The --review solo argument overrides the resolved review_mode for the run
• The document is written on user approval alone, and completion is not blocked
• Document Status records both reviews as skipped in that mode (after its ask), so the document says why it has no sign-off
• The Phase 8 handoff is still printed

---

Case 3b: Review Rejects — Accept Is Not Offered

Fixture:

• Same project as Case 1 in full mode; technical-director returns TD-ARCHITECTURE: REJECT (a Core system depends on a Presentation-layer module); lead-programmer returns LP-FEASIBILITY: FEASIBLE

Input: /create-architecture

Expected behavior:

1. Both reviews are spawned in parallel at Phase 7b
2. Step 3 shows TD-ARCHITECTURE: REJECT and LP-FEASIBILITY: FEASIBLE side by side
3. The AskUserQuestion offers Revise flagged items first and Discuss specific concerns — not Accept
4. On Revise flagged items first, the flagged sections are re-drafted and approved as in Phases 1–4, and the revised document is written once, through Phase 7's ask
5. Nothing is recorded as approved; Step 4 records REVISED after REJECT, and the handoff's first line carries the same value

Assertions:

• technical-director and lead-programmer calls are issued before either result is awaited
• Accept — proceed to handoff is not an option while a REJECT stands
• The revised document is written once, after the re-drafted sections are approved — not section by section
• Document Status never shows TD-ARCHITECTURE as APPROVE for this run; the handoff line says REVISED after REJECT

---

Case 4: Edge Case — Systems index missing or empty

Fixture:

• Engine configured; design/gdd/game-concept.md exists
• Scenario (a): modes.workflow: standard, no design/gdd/systems-index.md
• Scenario (b): modes.workflow: standard, design/gdd/systems-index.md exists but contains only template placeholders
• Scenario (c): modes.workflow: minimal, no systems index, no game concept, design/game-brief.md exists

Input: /create-architecture

Expected behavior:

1. The skill checks both design files exist before reading either
2. (a) Stops with: "No systems index found. Run /map-systems first…" — no baseline is built, no file is written
3. (b) Treats the placeholder-only index as absent and stops the same way
4. (c) Says the systems index is not required at minimal, reads design/game-brief.md in place of the concept, and proceeds

Assertions:

• (a) The skill stops with the /map-systems message and writes nothing
• (b) A present-but-placeholder systems index is treated as absent
• (c) At minimal the skill says the index is not required and proceeds from the game brief
• At standard (a, b), no run continues past Phase 0b with a missing design file; at minimal (c) the brief stands in for both, and the run stops only if it is absent too

---

Case 5: ADR Audit — Proposed ADRs and uncovered requirements

Fixture:

• Same as Case 1, plus docs/architecture/adr-0002-save-format.md with Status: Proposed
• Also design/gdd/crafting.md, written before the GDD template, with none of the scanned section headings
• Baseline requirement TR-combat-002 (combo state machine) is not covered by any ADR's GDD Requirements Addressed section or decision text

Input: /create-architecture

Expected behavior:

1. Phase 0b's section Grep matches nothing in crafting.md, so the skill full-reads it, says so, and its requirements enter the baseline as TR-crafting-NNN — a zero-match GDD is never treated as having no requirements
2. Phase 0c lists ADR-0001 (Accepted) and ADR-0002 (Proposed) with their domains
3. Phase 5 shows the ADR quality table and the traceability table, marking TR-combat-002 as ❌ GAP, with a covered/gap count
4. The gap is listed under Required New ADRs, grouped by layer with Foundation first, as /architecture-decision [title] → covers: TR-combat-002
5. Phase 8's "Gate-Check Readiness" lists ADR-0002 under "Accept ADRs" and the unwritten ADRs under "Write ADRs"
6. "Run These ADRs Next" lists at most three ADRs from Phase 6, in priority order

Assertions:

• crafting.md, which matched no scanned section, is full-read and reported, and contributes TR-IDs to the baseline
• ADR statuses come from the header scan and ADR-0002 is reported as Proposed
• TR-combat-002 is marked as a GAP and becomes a Required New ADR naming the TR-ID it covers
• Required New ADRs are grouped by layer, Foundation first
• "Gate-Check Readiness" lists ADR-0002 under "Accept ADRs"
• "Run These ADRs Next" lists no more than three entries

---

Case 6: Existing Architecture Document — Update in place, never overwritten unasked

Fixture:

• Same project as Case 1, but project.yaml has modes.review_mode: lean
• Scenario (a): docs/architecture/architecture.md exists at Version: 2 with every section written; the user picks [A] Update chosen sections in place and chooses Data Flow
• Scenario (b): no docs/architecture/architecture.md; the input is /create-architecture layers

Input: (a) /create-architecture (b) /create-architecture layers

Expected behavior:

1. (a) Phase 0e finds the document, reads its Document Status and headings, and asks "An architecture document already exists (v2, [last updated]). What should this run do?" with [A] Update chosen sections in place / [B] Rewrite the whole document — replaces the existing file / [C] Stop
2. (a) Only Phase 3 (Data Flow) is authored; the output says which phases were skipped
3. (a) Phase 7's ask names the Data Flow section and the change from v2 to v3; on yes, only ## Data Flow is replaced, with Edit, and Version becomes 3
4. (a) Every other section of the document is unchanged, and the handoff names v3
5. (b) The skill says there is no architecture document for the layers focus area to update, and offers the full walkthrough instead; nothing is written before the user answers

Assertions:

• (a) The existing document is detected before any authoring, and replacing it is only ever the user's explicit [B] choice
• (a) Only the chosen section is re-authored and written; the other sections are left as they were
• (a) The version is raised, not reset to v1.0
• (b) A focus-area run with no document writes nothing and offers the full walkthrough

---

Protocol Compliance

• Stops before authoring when the engine is missing, or on a standard/full project when the systems index or game concept is missing; at minimal it proceeds from design/game-brief.md and stops only when that is absent too
• Every section is shown in full before its approval is asked
• Write approvals use AskUserQuestion with labeled options, not plain-text asks
• Follows one consistent write model for docs/architecture/architecture.md, and never replaces an existing one without the user choosing to
• TD-ARCHITECTURE and LP-FEASIBILITY run only in full mode; lean/solo print a skip note naming each gate and the mode
• The Document Status sign-off is recorded only after the "May I update" approval
• Ends with the fixed handoff template and next steps (/architecture-decision, /architecture-review, /create-control-manifest)

---

Coverage Notes

• Of the focus-area arguments, only layers with no existing document is fixture-tested (Case 6 b). A focus-area run against an existing document follows Case 6 (a)'s update path but is not tested on its own.
• The "no engine configured" stop is asserted structurally only.
• workflow: standard (a system layer map and the critical ADR list only) is not fixture-tested past Phase 0b; Case 4 exercises only its stop branches.
• docs.density depth variations and guided / autonomous automation modes are not tested.