Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/pipeline/map-systems.md

Skill Test Spec: /map-systems

Skill Summary

/map-systems decomposes a game concept into a systems index. It reads design/gdd/game-concept.md (at minimal, design/game-brief.md) and the pillars, enumerates explicit and implicit systems, maps dependencies into layers (Foundation → Core → Feature → Presentation → Polish), assigns priority tiers (MVP / Vertical Slice / Alpha / Full Vision), derives a design order, and writes design/gdd/systems-index.md from .claude/docs/templates/systems-index.md after approval. Each collaborative phase ends with an AskUserQuestion.

Three director gates run in sequence, each in its own phase: TD-SYSTEM-BOUNDARY (technical-director) after the dependency map is approved, PR-SCOPE (producer) after priorities are approved and before the write, and CD-SYSTEMS (creative-director) after the index is written. In lean and solo each is skipped with a named note. It is required before /design-system at standard/full and optional at minimal. Verdicts: COMPLETE (index written) or BLOCKED (user declined the write).

---

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 verdict keywords: COMPLETE, BLOCKED
• Contains "May I write" collaborative protocol language (for design/gdd/systems-index.md)
• Has a next-step handoff at the end (/design-system)
• Documents three gates at their phases: TD-SYSTEM-BOUNDARY (Phase 3), PR-SCOPE (Phase 4), CD-SYSTEMS (Phase 5, after the write)

---

Director Gate Checks

In full mode, sequentially:

1. TD-SYSTEM-BOUNDARY (technical-director) — after the dependency ordering is approved, before priority assignment. REJECT → revise boundaries with the user; CONCERNS → noted inline in the index.
2. PR-SCOPE (producer) — after priorities are approved, before the index is written. UNREALISTIC → offer to revise tier assignments before writing; OPTIMISTIC → show the suggested adjustments and ask whether to apply them.
3. CD-SYSTEMS (creative-director) — after the index is written; it receives the index path, the pillars and core fantasy (the brief's pitch and "what they feel" line at minimal), every tier's assignments and the high-risk and bottleneck systems. REJECT → revise the system set before GDD authoring; CONCERNS → AskUserQuestion (Revise the system set / Accept — record them in the index / Discuss further); on Accept they are recorded as a > **Creative Director Note** (<tier>): … directly beneath the ## Priority Tiers table.

Any of the three may answer NOT ASSESSED [missing input]; it is never read as approval — the input is supplied and the gate re-run, or the run goes on with [GATE-ID]: NOT ASSESSED — [input] recorded in the index.

In lean mode each is skipped with a note: "TD-SYSTEM-BOUNDARY skipped — Lean mode.", "PR-SCOPE skipped — Lean mode.", "CD-SYSTEMS skipped — Lean mode."

In solo mode the same three notes appear with "Solo mode."

---

Test Cases

Case 1: Happy Path — Concept decomposed and index written in full review mode

Fixture:

• project.yaml: modes.workflow: standard, modes.review_mode: full
• design/gdd/game-concept.md exists with Core Mechanics naming combat and an inventory, and an MVP Definition section
• design/gdd/game-pillars.md exists with 2 pillars
• No design/gdd/systems-index.md exists yet
• TD-SYSTEM-BOUNDARY returns APPROVE, PR-SCOPE returns REALISTIC, CD-SYSTEMS returns APPROVE

Input: /map-systems

Expected behavior:

1. Reads the concept and pillars; globs design/gdd/*.md
2. Presents systems by category — name, category, one-sentence description, explicit or implicit (e.g. combat implies health, damage calculation, hit detection, combat UI) — and asks about missing / combined / unneeded systems
3. Presents the layered dependency map (bottlenecks, leaf nodes, any cycles) and asks "Does this dependency ordering look right?…"
4. After approval spawns TD-SYSTEM-BOUNDARY, passing the dependency graph (each system → what it depends on), the layer assignments, the bottleneck systems and any cycles with their proposed resolutions
5. Presents priority tiers with reasoning that cites this project's pillars; after approval spawns PR-SCOPE
6. Presents the summary (counts by category, MVP count, first 3 in design order, high-risk items) and asks "May I write the systems index to design/gdd/systems-index.md?"
7. Writes the index, then spawns CD-SYSTEMS with the index path, pillars/core fantasy, every tier's system assignments and the high-risk and bottleneck systems
8. Updates production/session-state/active.md; Verdict: COMPLETE; offers /design-system [first-system-in-order]

Assertions:

• Implicit systems are inferred and labelled implicit, with the reason given
• TD-SYSTEM-BOUNDARY spawns after the dependency map is approved and before priorities are presented, and is passed the full dependency graph — not a summary
• PR-SCOPE spawns after priorities are approved and before the write ask
• "May I write the systems index to design/gdd/systems-index.md?" is asked and nothing is written before approval
• CD-SYSTEMS spawns only after the index is written, and receives all four tiers and the high-risk systems — not the MVP list alone
• The Systems Enumeration table keeps the template's columns (# / System Name / Category / Priority / Status / Design Doc / Depends On) — no added column
• active.md is updated and the verdict is COMPLETE

---

Case 2: Failure Path — No game concept found

Fixture:

• project.yaml: modes.workflow: standard
• Neither design/gdd/game-concept.md nor design/game-brief.md exists

Input: /map-systems

Expected behavior:

1. Phase 1 finds no concept
2. Skill outputs: "No game concept found. Run /brainstorm first to create one, then come back to decompose it into systems."
3. Skill stops — no enumeration, no gates, no index

Assertions:

• The "No game concept found" message is printed
• Skill recommends /brainstorm as the next action
• No systems enumeration is presented and no gate is spawned
• No design/gdd/systems-index.md is created and Verdict COMPLETE is not emitted

---

Case 3: Director Gate — CD-SYSTEMS returns CONCERNS after the write

Fixture:

• Game concept and pillars exist; no index yet
• project.yaml: modes.workflow: standard, modes.review_mode: full
• TD-SYSTEM-BOUNDARY returns APPROVE, PR-SCOPE returns REALISTIC
• CD-SYSTEMS returns CONCERNS: an MVP system implied by the core fantasy is missing
• At the CONCERNS question the user picks Accept — record them in the index

Input: /map-systems

Expected behavior:

1. The index is written after "May I write" approval
2. CD-SYSTEMS is spawned and returns CONCERNS
3. The concerns are shown with AskUserQuestion: Revise the system set / Accept — record them in the index / Discuss further
4. On Accept, the concern is recorded in the index as > **Creative Director Note** (MVP): … directly beneath the ## Priority Tiers table
5. Session state is updated; Verdict: COMPLETE

Assertions:

• CD-SYSTEMS is spawned only after the index is written, not before the write ask
• The CONCERNS go to the user as a choice — the index is not edited before the user picks
• Only the Accept choice, which names the edit, leads to the note being written; it sits directly beneath the ## Priority Tiers table and names the MVP tier
• Had the user picked Revise the system set, the affected systems would be reworked with the user and the re-write of the index asked again
• CONCERNS do not trigger a full re-decomposition (that path is REJECT's)
• Verdict is COMPLETE

---

Case 4: Edge Case — Systems index already exists

Fixture:

• project.yaml: modes.workflow: standard
• design/gdd/game-concept.md exists
• design/gdd/systems-index.md already exists with 8 systems, 3 of them designed

Input: /map-systems

Expected behavior:

1. Skill reads the existing index and presents its current status
2. Skill asks: "The systems index already exists with 8 systems (3 designed, 5 not started). What would you like to do?" with "Update the index with new systems", "Design the next undesigned system", "Review and revise priorities"
3. User chooses an action
4. Skill resumes from the existing index rather than recreating it

Assertions:

• Skill detects and reads the existing index before proceeding
• The system count with designed / not-started split is presented
• All three options are offered — the index is not auto-overwritten
• Skill does NOT re-run a full decomposition from scratch without the user choosing to

---

Case 5: Director Gate — Lean and solo modes skip all three gates, noted

Fixture (lean mode):

• Game concept exists
• project.yaml: modes.workflow: standard, modes.review_mode: lean

Lean mode expected behavior:

1. Systems, dependencies and priorities are presented and approved as in Case 1
2. Notes "TD-SYSTEM-BOUNDARY skipped — Lean mode." and "PR-SCOPE skipped — Lean mode." at their phases
3. "May I write" is asked; the index is written after approval
4. Notes "CD-SYSTEMS skipped — Lean mode."
5. Session state is updated and Verdict: COMPLETE is printed

Assertions (lean mode):

• All three skip notes appear, each at its own phase
• No director agent is spawned
• The "May I write" ask still precedes the write
• active.md is updated and Verdict: COMPLETE is printed even though CD-SYSTEMS was skipped

Fixture (solo mode):

• Same concept, project.yaml: modes.workflow: standard, modes.review_mode: full
• Input: /map-systems --review solo

Solo mode expected behavior:

1. --review solo overrides the resolved full
2. The same three gates are skipped, noted with "Solo mode."

Assertions (solo mode):

• All three skip notes carry the "Solo mode." label
• Behavior is otherwise identical to lean mode for this skill

---

Case 6: Guided mode — a new index is still asked for; an update is not

Fixture (new index):

• project.yaml: modes.workflow: standard, modes.review_mode: solo, modes.automation: guided
• Game concept exists; no design/gdd/systems-index.md

Fixture (update):

• Same, but design/gdd/systems-index.md exists and the user chose "Update the index with new systems"

Input (both fixtures): /map-systems

Expected behavior:

1. New index: after the summary, asks "May I write the systems index to design/gdd/systems-index.md?" and writes only after yes — guided asks "May I write?" for new files
2. Update: presents the summary, names design/gdd/systems-index.md, writes the update without waiting for an explicit yes, and says what it wrote

Assertions:

• New index at guided: the write ask is shown and nothing is written before it is answered
• Update at guided: no write ask; the summary and destination are shown before the write and the result is reported after it

---

Case 7: Director Gate — TD-SYSTEM-BOUNDARY returns REJECT

Fixture:

• project.yaml: modes.workflow: standard, modes.review_mode: full
• Game concept and pillars exist; no index yet
• TD-SYSTEM-BOUNDARY returns REJECT: two systems share one responsibility and must be merged

Input: /map-systems

Expected behavior:

1. The dependency map is approved and TD-SYSTEM-BOUNDARY is spawned
2. The REJECT is presented, naming the two systems
3. The boundaries are revised with the user; the revised dependency map is shown
4. Only then are priorities presented and PR-SCOPE spawned

Assertions:

• Priority assignment does not start while the REJECT is unresolved
• The revised boundaries are shown to the user before priorities are presented
• PR-SCOPE is not spawned and nothing is written before the revision
• The REJECT is not recorded as a note and passed over — that handling is CONCERNS'

---

Protocol Compliance

• Reads the game concept (or brief at minimal) and pillars before any decomposition
• AskUserQuestion at enumeration, dependencies, priorities and the write
• "May I write the systems index to design/gdd/systems-index.md?" asked before writing — at collaborative, and at guided for a new index
• CD-SYSTEMS's CONCERNS reach the written index only through the user's choice; TD-SYSTEM-BOUNDARY's CONCERNS are noted inline in the index
• Gates run sequentially at their own phases in full mode, never before their inputs exist
• Skipped gates noted by name and mode in lean/solo output
• Ends with next-step handoff: /design-system [next-system]

---

Coverage Notes

• Circular dependency detection and its proposed resolutions are part of Phase 3 — not independently fixture-tested here.
• PR-SCOPE UNREALISTIC, the CD-SYSTEMS REJECT path and a NOT ASSESSED answer from any of the three gates are not given fixtures.
• autonomous (records the enumeration via log_decision and writes without asking) is not tested.
• The next and [system-name] argument modes (handoff to /design-system) are not tested here — they are post-index conveniences.
• docs.density depth (where per-system prose goes) is not fixture-locked.