Release 1.1.2 — the default path works end to end

Fix release for 1.1.1: the minimal path end to end, engine commands that
run on Godot, Unity and Unreal, hook warnings you can see, and verdicts
that say when they could not check. Details in CHANGELOG.md; upgrade
steps in UPGRADING.md (v1.1.1 → v1.1.2).

Fixes #67
Fixes #131

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
This commit is contained in:
Donchitos
2026-09-29 21:32:19 +10:00
co-authored by Claude Opus 5.5
parent 7ed2c3e9c4
commit b21fa0f7f2
383 changed files with 22888 additions and 10618 deletions
@@ -1,10 +1,9 @@
# Agent Test Spec: audio-director
## Agent Summary
**Domain owned:** Music direction and palette, sound design philosophy, audio implementation strategy, mix balance, audio aspects of phase gates.
**Does NOT own:** Visual design (art-director), code implementation (lead-programmer), narrative story content (narrative-director), UX interaction flows (ux-designer).
**Model tier:** Sonnet (individual system analysis — audio direction and spec review).
**Gate IDs handled:** AD-VISUAL (audio aspect of the phase gate; may be referenced as part of AD-PHASE-GATE in the audio dimension).
**Domain owned:** Sonic identity — sound palette, music direction and emotional mapping, audio event architecture, mix strategy, adaptive audio design, audio asset specifications and naming.
**Does NOT own:** Visual design (art-director), audio engine code (gameplay-programmer / engine-programmer), audio middleware changes (technical-director approval), narrative story content (narrative-director), UX interaction flows (ux-designer).
**Gate IDs handled:** None. No director gate is assigned to audio-director (`AD-` gates belong to art-director). Design-review verdicts come from the `/design-review` skill, which spawns audio-director as a specialist that returns findings.
---
@@ -13,8 +12,8 @@
Verified by reading the agent's `.claude/agents/audio-director.md` frontmatter:
- [ ] `description:` field is present and domain-specific (references music direction, sound design, mix, audio implementation — not generic)
- [ ] `allowed-tools:` list is read-focused; no Bash unless audio asset pipeline checks are justified
- [ ] Model tier is `claude-sonnet-5` per coordination-rules.md
- [ ] `tools:` reads Read, Glob, Grep, Write, Edit, WebSearch and `disallowedTools:` lists Bash
- [ ] Model tier is `inherit` — frontmatter `model:` reads exactly `inherit` (tiers: `.claude/docs/model-tiers.md`)
- [ ] Agent definition does not claim authority over visual design, code implementation, or narrative content
---
@@ -22,57 +21,58 @@ Verified by reading the agent's `.claude/agents/audio-director.md` frontmatter:
## Test Cases
### Case 1: In-domain request — appropriate output format
**Scenario:** An audio specification document is submitted for the game's "Exploration" music layer. The spec defines a generative ambient system using layered stems that shift based on environmental density, designed to reinforce the pillar "lived-in world." The tone palette (sparse, organic, slightly melancholic) matches the established design pillars.
**Expected:** Returns `APPROVED` with rationale confirming the stem-based approach supports dynamic responsiveness and the tone palette aligns with the pillar vocabulary.
**Scenario:** The user has approved the direction for the game's "Exploration" music layer: a generative ambient system of layered stems that shift with environmental density, in a sparse, organic, slightly melancholic palette, meant to reinforce the pillar "lived-in world." The user asks audio-director to draft the audio asset specification for this layer.
**Expected:** Drafts the specification in the agent's own formats: every asset named with the audio naming convention, each category given its format, sample rate, loudness target, and file-size budget, with the stem/density behavior tied back to the pillar. Shows the draft and asks before writing it to a file.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / NEEDS REVISION
- [ ] Rationale references the specific pillar ("lived-in world") and how the audio spec supports it
- [ ] Output stays within audio scope — does not comment on visual design of the environment or UI layout
- [ ] Verdict is clearly labeled with context (e.g., "Audio Spec Review: APPROVED")
- [ ] Every asset name follows `[category]_[context]_[name]_[variant].[ext]` (e.g., `mus_explore_forest_calm_loop.ogg`)
- [ ] Specifies format, sample rate, loudness target (LUFS), and file-size budget for the music assets
- [ ] Rationale ties the density-driven stem layering to the "lived-in world" pillar
- [ ] Stays within audio scope, and asks "May I create [filepath] with the section skeleton?" before creating the file and "May I write this section to [filepath]?" before writing each section
### Case 2: Out-of-domain request — redirects or escalates
**Scenario:** A developer asks audio-director to evaluate whether the UI flow for the audio settings menu (the sequence of screens and options) is intuitive and well-organized.
**Expected:** Agent declines to evaluate UI interaction flow and redirects to ux-designer.
**Expected:** Agent does not rule on screen flow or menu organization — that is UX, not audio. It limits its answer to the audio requirements the menu must expose, derived from its own mix strategy, and leaves flow and layout to ux-designer.
**Assertions:**
- [ ] Does not make any binding decision about UI flow or information architecture
- [ ] Explicitly names `ux-designer` as the correct handler
- [ ] May note audio-specific requirements for the settings menu (e.g., "must include separate master, music, and SFX sliders"), but defers flow and layout decisions to ux-designer
- [ ] Does not make any binding decision about UI flow, screen sequence, or information architecture
- [ ] States that flow and layout are outside the audio domain rather than evaluating them
- [ ] Explicitly names `ux-designer` as the owner of the menu's flow and layout (its file defers UX decisions to ux-designer)
- [ ] Limits its contribution to audio requirements taken from its mix strategy (e.g., one slider per bus in its volume hierarchy — master, music, SFX, dialogue)
### Case 3: Gate verdict — correct vocabulary
**Scenario:** A music cue for the final boss encounter is submitted. The cue is an upbeat, major-key orchestral piece with fast tempo. The game pillars and narrative context for this encounter specify "dread, inevitability, and tragic sacrifice." The audio cue's emotional register directly contradicts the intended emotional beat.
**Expected:** Returns `NEEDS REVISION` with specific citation of the emotional mismatch: the cue's upbeat/major-key/fast-tempo characteristics versus the intended dread/inevitability/sacrifice emotional targets from the pillars and narrative context.
### Case 3: Review findings — specific, verdict left to the review skill
**Scenario:** `/design-review` in full mode spawns audio-director as the adversarial specialist for a boss-encounter GDD that contains music triggers. The spawn prompt reads: "Your job is NOT to validate this design — your job is to find problems. Be specific and critical." The GDD's final-boss cue is an upbeat, major-key orchestral piece with fast tempo; the game pillars and narrative context for the encounter specify "dread, inevitability, and tragic sacrifice."
**Expected:** Returns specific findings: the cue's major key, fast tempo, and upbeat register contradict the emotional targets, with revision directions offered as options. It returns findings, not a verdict — the review's verdict is produced by `/design-review`.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / NEEDS REVISION — not freeform text
- [ ] Rationale identifies the specific musical characteristics that conflict with the emotional targets
- [ ] References the specific emotional targets from the game pillars or narrative context
- [ ] Provides actionable direction for revision (e.g., "shift to minor key, slower tempo, reduce ensemble density")
- [ ] Identifies the specific musical characteristics that conflict (major key, fast tempo, upbeat register)
- [ ] Names the emotional targets the cue contradicts (dread, inevitability, tragic sacrifice), treating them as the encounter's emotional mapping
- [ ] Provides actionable revision directions (e.g., minor mode, slower tempo, thinner ensemble) as options with a recommendation
- [ ] Returns findings to the review, not its own APPROVED / NEEDS REVISION stamp
### Case 4: Conflict escalation — correct parent
**Scenario:** sound-designer proposes implementing audio occlusion using real-time raycast-based physics queries (technical approach). technical-artist argues this is too expensive and proposes a zone-based trigger system instead. Both agree the occlusion effect is desirable; the conflict is purely about implementation approach.
**Expected:** audio-director decides on the desired audio behavior (what occlusion should sound like and when it should activate), then defers the implementation approach decision to technical-artist or lead-programmer as the implementation experts. audio-director does not make the technical implementation choice.
**Scenario:** sound-designer proposes implementing audio occlusion using real-time raycast-based physics queries. technical-artist argues this is too expensive and proposes a zone-based trigger system instead. Both agree the occlusion effect is desirable; the conflict is purely about implementation approach.
**Expected:** audio-director defines the desired audio behavior (what occlusion should sound like and when it should activate) as the requirement either approach must meet, then defers the raycast-vs-zone choice to `lead-programmer` — the agent its file names for audio system implementation — or to `technical-director` for a technical conflict. It does not pick the implementation, and does not hand the decision to either party in the dispute.
**Assertions:**
- [ ] Defines the desired audio behavior clearly (what should the player hear and when)
- [ ] Explicitly defers the implementation approach (raycast vs. zone-trigger) to `lead-programmer` or `technical-artist`
- [ ] Defines the desired audio behavior clearly (what the player hears, when occlusion engages, how strongly it attenuates)
- [ ] Defers the implementation approach (raycast vs. zone-trigger) to `lead-programmer` or `technical-director` — not to sound-designer or technical-artist, who are the disputants
- [ ] Does not unilaterally choose the technical implementation method
- [ ] Frames the handoff clearly: "audio-director owns what, technical lead owns how"
- [ ] States the audio behavior as the requirement either implementation must satisfy, so the technical decision can be checked against it
### Case 5: Context pass — uses provided context
**Scenario:** Agent receives a gate context block that includes the game's three pillars: "emergent stories," "meaningful sacrifice," and "lived-in world." A sound design spec for ambient environmental audio is submitted.
**Expected:** Assessment evaluates the ambient audio spec against all three pillars specifically — how does the audio support (or undermine) each pillar? Uses the pillar vocabulary directly in the rationale.
**Scenario:** The request includes the game's three pillars: "emergent stories," "meaningful sacrifice," and "lived-in world." An ambient environmental audio spec is submitted: one static loop per biome, with no layer that responds to player actions or world events.
**Expected:** Assessment evaluates the ambient spec against all three pillars by name. It flags that static loops do not support "emergent stories" because nothing in the audio responds to game state, and points to adaptive audio as the gap.
**Assertions:**
- [ ] References all three provided pillars by name in the assessment
- [ ] Evaluates the audio spec's contribution to each pillar explicitly
- [ ] Flags "emergent stories" as unsupported because the loops do not respond to game state, naming adaptive audio (state-driven layers or transitions) as the missing piece
- [ ] Does not generate generic audio direction advice — all feedback is tied to the provided pillar vocabulary
- [ ] Identifies if any pillar is not supported by the current audio spec and flags it
---
## Protocol Compliance
- [ ] Returns verdicts using APPROVED / NEEDS REVISION vocabulary only
- [ ] Names every audio asset it specifies with `[category]_[context]_[name]_[variant].[ext]`
- [ ] Stays within declared audio domain
- [ ] Defers implementation approach decisions to technical leads
- [ ] Does not use gate ID prefix format in the same way as director-tier agents (audio-director uses APPROVED / NEEDS REVISION inline, but should still reference the gate context)
- [ ] Ties audio feedback to the pillars or emotional targets supplied in the request, not generic audio advice
- [ ] Does not make binding visual design, UX, narrative, or code implementation decisions
---
@@ -80,5 +80,5 @@ Verified by reading the agent's `.claude/agents/audio-director.md` frontmatter:
## Coverage Notes
- Mix balance review (relative levels between music, SFX, and dialogue) is not covered — a dedicated case should be added.
- Audio implementation strategy review (middleware choice, streaming approach) is not covered.
- Interaction between audio-director and the audio specialist agent (if one exists) for implementation delegation is not covered.
- Delegation to sound-designer for detailed SFX documents and event lists is not covered.
- Localization audio implications (VO recording direction, language-specific music timing) are not covered.
@@ -1,10 +1,9 @@
# Agent Test Spec: game-designer
## Agent Summary
**Domain owned:** Core loop design, progression systems, combat mechanics rules, economy design, player-facing rules and interactions.
**Does NOT own:** Code implementation (lead-programmer / gameplay-programmer), visual art (art-director), narrative lore and story (narrative-director — coordinates with), balance formula math (systems-designer — collaborates with).
**Model tier:** Sonnet (individual system design authoring and review).
**Gate IDs handled:** Design review verdicts on mechanic specs (no named gate ID prefix — uses APPROVED / NEEDS REVISION vocabulary).
**Domain owned:** Core loop design, progression systems, combat mechanics rules, economy design, player-facing rules and interactions, mechanic GDDs in `design/gdd/`.
**Does NOT own:** Code implementation (lead-programmer / gameplay-programmer), art and audio direction (art-director / audio-director), final narrative content (narrative-director — coordinates with), detailed formula math (systems-designer — delegates to).
**Gate IDs handled:** None. Design-review verdicts come from the `/design-review` skill (APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED / NOT ASSESSED); when that skill spawns game-designer as a specialist, the agent returns findings.
---
@@ -13,8 +12,8 @@
Verified by reading the agent's `.claude/agents/game-designer.md` frontmatter:
- [ ] `description:` field is present and domain-specific (references core loop, progression, combat rules, economy, player-facing design — not generic)
- [ ] `allowed-tools:` list is read-focused; includes Read for GDDs and design docs; no Bash unless design tooling requires it
- [ ] Model tier is `claude-sonnet-5` per coordination-rules.md
- [ ] `tools:` reads Read, Glob, Grep, Write, Edit, WebSearch and `disallowedTools:` lists Bash
- [ ] Model tier is `inherit` — frontmatter `model:` reads exactly `inherit` (tiers: `.claude/docs/model-tiers.md`)
- [ ] Agent definition does not claim authority over code implementation, visual art style, or standalone narrative lore decisions
---
@@ -22,13 +21,13 @@ Verified by reading the agent's `.claude/agents/game-designer.md` frontmatter:
## Test Cases
### Case 1: In-domain request — appropriate output format
**Scenario:** A mechanic spec for a "Stamina-Based Dodge" system is submitted for review. The spec defines: the player has a stamina pool (100 units), each dodge costs 25 stamina, stamina regenerates at 20 units/second when not dodging, and the dodge grants 0.3 seconds of invincibility. The core loop interaction is clearly described, rules are unambiguous, and edge cases (stamina at 0, dodge during regen) are addressed.
**Expected:** Returns `APPROVED` with rationale confirming the core loop clarity, unambiguous rules, and edge case coverage.
**Scenario:** The project's `modes.workflow` is `full`. The user asks game-designer to design a "Stamina-Based Dodge" mechanic: the player has a stamina pool, each dodge costs stamina, stamina regenerates when not dodging, and a dodge grants a short invincibility window.
**Expected:** Follows its Question-First workflow — asks what the dodge should make the player feel and how it connects to the pillars, presents 2–4 options with a recommendation, then drafts the GDD in the Design Document Standard with its tunable values exposed as tuning knobs, asking before each write.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / NEEDS REVISION
- [ ] Rationale references specific design quality criteria (clear rules, edge case coverage, core loop coherence)
- [ ] Output stays within design scope — does not comment on how to implement it in code or what art assets it requires
- [ ] Verdict is clearly labeled with context (e.g., "Mechanic Spec Review: APPROVED")
- [ ] Asks clarifying questions (intended player experience, pillar connection) before proposing a design, and presents 2–4 options with a recommendation that leaves the choice to the user
- [ ] The draft uses the eight Design Document Standard sections: Overview, Player Fantasy, Detailed Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria
- [ ] Tuning Knobs classify each value (stamina pool, dodge cost, regen rate, invincibility duration) as feel, curve, or gate, and place them in external data files rather than hardcoding them
- [ ] Asks "May I create [filepath] with the section skeleton?" before creating the file, and "May I write this section to [filepath]?" before writing each section under `design/gdd/`; gives no implementation code or art direction
### Case 2: Out-of-domain request — redirects or escalates
**Scenario:** A team member asks game-designer to write the in-world lore explanation for why the stamina system exists (e.g., the narrative reason characters have stamina limits in the game world).
@@ -36,16 +35,16 @@ Verified by reading the agent's `.claude/agents/game-designer.md` frontmatter:
**Assertions:**
- [ ] Does not write narrative or lore content
- [ ] Explicitly names `writer` or `narrative-director` as the correct handler
- [ ] May note the design intent that the lore should support (e.g., "the stamina system should reinforce the physical realism theme"), but defers the writing to the narrative team
- [ ] Any design intent it adds (e.g., "the stamina system should reinforce the physical realism theme") is framed as input for the narrative team, not written as the lore itself
### Case 3: Gate verdict — correct vocabulary
**Scenario:** A mechanic spec for "Environmental Hazard Damage" is submitted. The spec defines three hazard types (fire, acid, electricity) but does not specify what happens when a player is simultaneously affected by multiple hazard types, what happens when a hazard is applied during the invincibility window from a dodge, or what the damage frequency is (per-second, per-tick, on-enter).
**Expected:** Returns `NEEDS REVISION` with specific identification of the undefined edge cases: multi-hazard interaction, hazard-during-invincibility, and damage frequency specification.
### Case 3: Review findings — specific, verdict left to the review skill
**Scenario:** `/design-review` in full mode spawns game-designer as the adversarial specialist for `design/gdd/environmental-hazards.md`. The spawn prompt reads: "Your job is NOT to validate this design — your job is to find problems. Anchor your review to the Player Fantasy stated in Section B." The Player Fantasy is "the world is dangerous but fair — every hazard is readable and avoidable." The GDD defines three hazard types (fire, acid, electricity) but does not specify what happens when a player is in several hazards at once, what happens when a hazard hits during the dodge invincibility window, or the damage frequency (per-second, per-tick, on-enter).
**Expected:** Returns specific findings naming the three undefined edge cases, tied to the stated Player Fantasy, as gaps to fill rather than a rejection of the mechanic. It returns findings, not a verdict — `/design-review` issues the verdict.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / NEEDS REVISION — not freeform text
- [ ] Rationale identifies the specific missing edge cases by name
- [ ] Does not reject the entire mechanic — identifies the specific gaps to fill
- [ ] Provides actionable guidance on what to define (not how to implement it)
- [ ] Names each missing edge case: simultaneous multi-hazard exposure, a hazard during dodge invincibility, and the undefined damage frequency
- [ ] Ties at least one gap to the stated Player Fantasy (e.g., an undefined damage frequency makes a hazard's threat unreadable, contradicting "readable and avoidable")
- [ ] Frames the gaps as rules to define in the GDD (what to specify), not as a rejection of the mechanic and not as implementation advice
- [ ] Returns findings to the review, not its own APPROVED / NEEDS REVISION stamp
### Case 4: Conflict escalation — correct parent
**Scenario:** systems-designer proposes a damage formula with 6 variables and complex scaling interactions, arguing it produces the best tuning granularity. game-designer believes the formula is too complex for players to intuit and want a simpler 2-variable version.
@@ -57,19 +56,27 @@ Verified by reading the agent's `.claude/agents/game-designer.md` frontmatter:
- [ ] Does not unilaterally impose a formula structure on systems-designer
### Case 5: Context pass — uses provided context
**Scenario:** Agent receives a gate context block that includes the game's three pillars: "player authorship," "consequence permanence," and "world responsiveness." A new mechanic spec for "permadeath with legacy bonuses" is submitted for review.
**Expected:** Assessment evaluates the mechanic against all three provided pillars — how does permadeath support player authorship, how do legacy bonuses express consequence permanence, and how does the world respond to a player's death? Uses the pillar vocabulary directly in the rationale.
**Scenario:** The request includes the game's three pillars: "player authorship," "consequence permanence," and "world responsiveness." A new mechanic spec for "permadeath with legacy bonuses" is submitted for the agent's assessment.
**Expected:** Assessment evaluates the mechanic against all three provided pillars — how permadeath supports player authorship, how legacy bonuses express or soften consequence permanence, and how the world responds to a player's death. Uses the pillar vocabulary directly, and flags pillar tensions for the user to decide.
**Assertions:**
- [ ] References all three provided pillars by name in the assessment
- [ ] Evaluates the mechanic's contribution to each pillar explicitly
- [ ] Does not generate generic game design advice — all feedback is tied to the provided pillar vocabulary
- [ ] Identifies if any pillar creates a tension with the mechanic and flags it with a specific concern
- [ ] Does not generate generic game design advice — every point is tied to one of the provided pillars by name; a framework term (MDA, SDT) may support a point but never replaces the pillar it concerns
- [ ] Flags at least one specific pillar tension (e.g., legacy bonuses softening "consequence permanence") as an issue for the user's decision, not one it resolves silently
### Case 6: Section set at `modes.workflow: standard`
**Scenario:** The same "Stamina-Based Dodge" request as Case 1, but the project's `modes.workflow` is `standard`.
**Expected:** Drafts the five sections `standard` requires — Overview, Detailed Rules, Edge Cases, Dependencies, Acceptance Criteria — plus Formulas, because the dodge defines numeric rules (stamina cost, regen rate, invincibility duration).
**Assertions:**
- [ ] The draft contains Overview, Detailed Rules, Edge Cases, Dependencies and Acceptance Criteria — Dependencies is not dropped
- [ ] Includes Formulas, because the mechanic defines numeric rules
- [ ] Does not treat Player Fantasy or Tuning Knobs as required sections at this tier
---
## Protocol Compliance
- [ ] Returns verdicts using APPROVED / NEEDS REVISION vocabulary only
- [ ] Drafts mechanic documents in the Design Document Standard's sections and asks before writing each to `design/gdd/`
- [ ] Stays within declared game design domain
- [ ] Escalates design-vs-formula conflicts to creative-director when unresolved
- [ ] Does not make binding code implementation, visual art, or standalone lore decisions
@@ -80,5 +87,7 @@ Verified by reading the agent's `.claude/agents/game-designer.md` frontmatter:
## Coverage Notes
- Economy design review (resource sinks, faucets, inflation prevention) is not covered — a dedicated case should be added.
- Progression system review (XP curves, unlock gates, player power trajectory) is not covered.
- A direct "review this GDD" request is not covered — design-review verdicts come from `/design-review`, which the user runs.
- Mechanic authoring at `modes.workflow` `minimal`, where there is no GDD and `design/game-brief.md` is the design record, is not covered.
- Core loop validation across multiple interconnected systems (not just a single mechanic) is not covered — deferred to /review-all-gdds integration.
- Coordination protocol with systems-designer on formula ownership boundary could benefit from additional cases.
@@ -3,7 +3,6 @@
## Agent Summary
**Domain owned:** Code architecture decisions, LP-FEASIBILITY gate, LP-CODE-REVIEW gate, coding standards enforcement, tech stack decisions within the approved engine.
**Does NOT own:** Game design decisions (game-designer), creative direction (creative-director), production scheduling (producer), visual art direction (art-director).
**Model tier:** Sonnet (implementation-level analysis of individual systems).
**Gate IDs handled:** LP-FEASIBILITY, LP-CODE-REVIEW.
---
@@ -13,8 +12,8 @@
Verified by reading the agent's `.claude/agents/lead-programmer.md` frontmatter:
- [ ] `description:` field is present and domain-specific (references code architecture, feasibility, code review, coding standards — not generic)
- [ ] `allowed-tools:` list includes Read for source files; Bash may be included for static analysis or test runs; no write access outside `src/` without explicit delegation
- [ ] Model tier is `claude-sonnet-5` per coordination-rules.md
- [ ] `tools:` includes Read for source files and Bash for static analysis or test runs; Write/Edit are gated in the body — every write waits for the user's "yes", and the orchestrated-run exception covers only new artifacts under `production/`, `docs/` or `tests/`
- [ ] Model tier is `sonnet` — frontmatter `model:` reads exactly `sonnet` (tiers: `.claude/docs/model-tiers.md`)
- [ ] Agent definition does not claim authority over game design, creative direction, or production scheduling
---
@@ -22,28 +21,28 @@ Verified by reading the agent's `.claude/agents/lead-programmer.md` frontmatter:
## Test Cases
### Case 1: In-domain request — appropriate output format
**Scenario:** A new `CombatSystem` implementation is submitted for code review. The system uses dependency injection for all external references, has doc comments on all public APIs, follows the project's naming conventions, and includes unit tests for all public methods. Request is tagged LP-CODE-REVIEW.
**Expected:** Returns `LP-CODE-REVIEW: APPROVED` with rationale confirming dependency injection usage, doc comment coverage, naming convention compliance, and test coverage.
**Scenario:** A new `CombatSystem` implementation is submitted for code review with every input LP-CODE-REVIEW names: its implementation files, its story's acceptance criteria, the relevant GDD section (the combat rules) and its governing ADR. The system stays inside the ADR's boundary, implements the GDD's combat rules as written, uses dependency injection for all external references, has doc comments on all public APIs, loads its tuning values from data files, and includes unit tests for all public methods. Request is tagged LP-CODE-REVIEW.
**Expected:** Returns the verdict APPROVE with rationale confirming the ADR boundary match, correctness against the GDD rules, dependency injection usage, doc comment coverage, data-driven configuration, and a testable public API.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / NEEDS CHANGES
- [ ] Verdict token is formatted as `LP-CODE-REVIEW: APPROVED`
- [ ] Rationale references specific coding standards criteria (DI, doc comments, naming, tests)
- [ ] Verdict is exactly one of APPROVE / CONCERNS / REJECT (the LP-CODE-REVIEW verdicts)
- [ ] States the verdict word `APPROVE` explicitly — `/story-done` branches on the gate's verdict words, so a verdict left implicit in prose cannot be acted on
- [ ] Rationale references specific criteria from its Coding Standards Enforcement list and the gate prompt (ADR boundary, GDD rules, DI, doc comments, data-driven values, testable API)
- [ ] Output stays within code quality scope — does not comment on whether the mechanic is fun or fits creative vision
### Case 2: Out-of-domain request — redirects or escalates
**Scenario:** Team member asks lead-programmer to review and approve the balance formula for player damage scaling across levels, checking whether the numbers "feel right."
**Expected:** Agent declines to evaluate design balance and redirects to systems-designer.
**Expected:** Agent declines to evaluate design balance and redirects to game-designer, its stated contact for design concerns.
**Assertions:**
- [ ] Does not make any binding assessment of formula balance or game feel
- [ ] Explicitly names `systems-designer` as the correct handler
- [ ] May note code implementation concerns about the formula (e.g., integer overflow risk at max level), but defers all balance evaluation to systems-designer
- [ ] Explicitly names `game-designer` as the correct handler (its "What This Agent Must NOT Do" target for design concerns); naming `systems-designer` as the formula owner as well is fine
- [ ] Any comment it makes on the formula is about implementation (e.g., integer overflow risk at max level); all balance evaluation is deferred to the design team
### Case 3: Gate verdict — correct vocabulary
**Scenario:** A proposed pathfinding approach for enemy AI uses a brute-force nearest-neighbor search against all other entities every frame. With expected enemy counts of 200+, this is O(n²) per frame at 60fps. Request is tagged LP-FEASIBILITY.
**Expected:** Returns `LP-FEASIBILITY: INFEASIBLE` with specific citation of the O(n²) complexity, the entity count threshold, and the resulting per-frame cost against the target frame budget.
**Scenario:** The architecture document under review (passed with its technical requirements baseline and ADR list) specifies enemy AI that runs a brute-force nearest-neighbor search against all other entities every frame. With expected enemy counts of 2,000+, this is O(n²) — about 4 million distance checks per frame — against the document's 2 ms AI budget at 60fps. Request is tagged LP-FEASIBILITY.
**Expected:** Returns the verdict INFEASIBLE with specific citation of the O(n²) complexity, the entity count threshold, and the resulting per-frame cost against the 2 ms AI budget.
**Assertions:**
- [ ] Verdict is exactly one of FEASIBLE / CONCERNS / INFEASIBLE — not freeform text
- [ ] Verdict token is formatted as `LP-FEASIBILITY: INFEASIBLE`
- [ ] States the verdict word `INFEASIBLE` explicitly, not a verdict implied by prose
- [ ] Rationale includes the specific algorithmic complexity and entity count numbers
- [ ] Suggests at least one alternative approach (e.g., spatial hashing, KD-tree) without mandating a choice
@@ -57,7 +56,7 @@ Verified by reading the agent's `.claude/agents/lead-programmer.md` frontmatter:
- [ ] Does not unilaterally cut or modify the mechanic design
### Case 5: Context pass — uses provided context
**Scenario:** Agent receives a gate context block that includes the project's frame budget: 16.67ms total per frame, with 4ms allocated to AI systems. A new AI behavior system is submitted that profiling estimates will consume 7ms per frame under normal conditions.
**Scenario:** Agent receives a gate context block for an architecture document (with its technical requirements baseline and ADR list) that includes the project's frame budget: 16.67ms total per frame, with 4ms allocated to AI systems. The document adopts a new AI behavior system that prototype profiling estimates will consume 7ms per frame under normal conditions. Request is tagged LP-FEASIBILITY.
**Expected:** Assessment references the specific frame budget allocation from context (4ms AI budget), identifies the 7ms estimate as exceeding the allocation by 3ms, and returns CONCERNS or INFEASIBLE with those specific numbers cited.
**Assertions:**
- [ ] References the specific frame budget figures from the provided context (16.67ms total, 4ms AI allocation)
@@ -65,15 +64,24 @@ Verified by reading the agent's `.claude/agents/lead-programmer.md` frontmatter:
- [ ] Does not give generic "this might be slow" advice — cites concrete numbers
- [ ] Verdict rationale is traceable to the provided budget constraints
### Case 6: Missing gate input — NOT ASSESSED
**Scenario:** An `InventorySystem` implementation is submitted for code review with its implementation files, its story's acceptance criteria and its governing ADR; everything the agent can check is sound. The relevant GDD section the gate names was not passed: the context gives neither its text nor a path, the story file names none, and the calling skill does not report it absent. Request is tagged LP-CODE-REVIEW.
**Expected:** Returns NOT ASSESSED for LP-CODE-REVIEW, naming the GDD section as the input it was not given — without it, the gate's check for correctness issues against the GDD rules cannot be made, so APPROVE is out of reach.
**Assertions:**
- [ ] States the verdict `NOT ASSESSED` explicitly for LP-CODE-REVIEW — not APPROVE, although everything it could check is sound
- [ ] Names the relevant GDD section as the missing input
- [ ] Does not infer the GDD rules from the code or the story and judge correctness against them
- [ ] Variant — had the calling skill reported that no inventory GDD exists, that is a finding, not a missing input: the verdict is CONCERNS or REJECT, not NOT ASSESSED
---
## Protocol Compliance
- [ ] Returns LP-CODE-REVIEW verdicts using APPROVED / NEEDS CHANGES vocabulary only
- [ ] Returns LP-FEASIBILITY verdicts using FEASIBLE / CONCERNS / INFEASIBLE vocabulary only
- [ ] Returns LP-CODE-REVIEW verdicts using APPROVE / CONCERNS / REJECT vocabulary only — or `NOT ASSESSED`, naming the input, when an input the gate names was not given or could not be read; an artifact the calling skill reports absent is a finding, in the gate's own words
- [ ] Returns LP-FEASIBILITY verdicts using FEASIBLE / CONCERNS / INFEASIBLE vocabulary only — or `NOT ASSESSED`, naming the input, when an input the gate names was not given or could not be read; an artifact the calling skill reports absent is a finding, in the gate's own words
- [ ] Stays within declared code architecture domain
- [ ] Defers design priority conflicts to creative-director
- [ ] Uses gate IDs in output (e.g., `LP-FEASIBILITY: INFEASIBLE`) not inline prose verdicts
- [ ] States each gate verdict as an explicit verdict word from that gate's definition, not a verdict implied by inline prose
- [ ] Does not make binding game design or creative direction decisions
---
@@ -1,10 +1,9 @@
# Agent Test Spec: level-designer
## Agent Summary
**Domain owned:** Level layouts, encounter design, pacing and tension arc, environmental storytelling, spatial puzzles.
**Does NOT own:** Narrative dialogue (writer / narrative-director), visual art style (art-director), code implementation (lead-programmer / ai-programmer), enemy AI behavior logic (ai-programmer / gameplay-programmer).
**Model tier:** Sonnet (individual system analysis — level design review and encounter assessment).
**Gate IDs handled:** Level design review verdicts (uses APPROVED / REVISION NEEDED vocabulary).
**Domain owned:** Level layouts, encounter design (per-encounter difficulty), pacing charts, environmental storytelling, secret and optional content placement, flow analysis.
**Does NOT own:** Game-wide systems (game-designer / systems-designer), story decisions (narrative-director — coordinates with), visual art style (art-director), level implementation in the engine and enemy AI code (programmers), game-wide difficulty parameters.
**Gate IDs handled:** None. Design-review verdicts come from the `/design-review` skill, which spawns level-designer as a specialist that returns findings.
---
@@ -13,8 +12,8 @@
Verified by reading the agent's `.claude/agents/level-designer.md` frontmatter:
- [ ] `description:` field is present and domain-specific (references level layout, encounter design, pacing, environmental storytelling — not generic)
- [ ] `allowed-tools:` list is read-focused; includes Read for level design documents and GDDs; no Bash unless level tooling requires it
- [ ] Model tier is `claude-sonnet-5` per coordination-rules.md
- [ ] `tools:` reads Read, Glob, Grep, Write, Edit and `disallowedTools:` lists Bash
- [ ] Model tier is `inherit` — frontmatter `model:` reads exactly `inherit` (tiers: `.claude/docs/model-tiers.md`)
- [ ] Agent definition does not claim authority over narrative dialogue, AI behavior code, or visual art style
---
@@ -22,54 +21,55 @@ Verified by reading the agent's `.claude/agents/level-designer.md` frontmatter:
## Test Cases
### Case 1: In-domain request — appropriate output format
**Scenario:** A level layout document for "The Flooded Tunnels" is submitted for review. The layout includes: a low-intensity exploration opening section, two mid-intensity encounters with visible escape routes, a tension-building narrow passage with environmental hazards, and a high-intensity final encounter room followed by a release/reward area. The pacing follows a classic tension-arc structure.
**Expected:** Returns `APPROVED` with rationale confirming the pacing follows the tension arc, encounters are varied in intensity, and spatial readability supports player navigation.
**Scenario:** The user has agreed the outline for "The Flooded Tunnels": a low-intensity exploration opening, two mid-intensity encounters with visible escape routes, a tension-building narrow passage with environmental hazards, and a high-intensity final encounter room followed by a release/reward area. The user asks level-designer to draft the level document.
**Expected:** Drafts the level document in the Level Document Standard, with a pacing chart that follows the agreed tension arc and an encounter list that gives each encounter's type, difficulty, and position. Shows each section and asks before writing it.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / REVISION NEEDED
- [ ] Rationale references specific pacing arc elements (opening, escalation, climax, release)
- [ ] Output stays within level design scope — does not comment on visual art style or enemy AI code behavior
- [ ] Verdict is clearly labeled with context (e.g., "Level Design Review: APPROVED")
- [ ] The document has all nine Level Document Standard sections: Level Name and Theme, Estimated Play Time, Layout Diagram, Critical Path, Optional Paths, Encounter List, Pacing Chart, Narrative Beats, Music/Audio Cues
- [ ] The Pacing Chart follows the outline's intensity curve — low opening, mid encounters, rising passage, high final encounter, release — with its rest points marked
- [ ] The Encounter List gives type, difficulty, and position for each encounter
- [ ] Asks "May I create [filepath] with the section skeleton?" before creating the file and "May I write this section to [filepath]?" before writing each section, and does not decide visual art style or enemy AI code
### Case 2: Out-of-domain request — redirects or escalates
**Scenario:** A team member asks level-designer to write the behavior tree code for an enemy patrol AI that navigates the level layout.
**Expected:** Agent declines to write AI behavior code and redirects to ai-programmer or gameplay-programmer.
**Expected:** Agent declines to write AI behavior code — implementation is outside its role — and instead specifies the patrol from a level design perspective, as input for ai-programmer.
**Assertions:**
- [ ] Does not write or specify code for AI behavior logic
- [ ] Explicitly names `ai-programmer` or `gameplay-programmer` as the correct handler
- [ ] May specify the desired patrol behavior from a level design perspective (e.g., "patrol should cover both chokepoints and create pressure in this zone"), but defers all code implementation to the programmer
- [ ] States that behavior-tree code is implementation work outside its role, rather than taking it on
- [ ] Explicitly names `ai-programmer` (or `gameplay-programmer`, which its file names for engine implementation) as who implements it
- [ ] Specifies the desired patrol in level design terms (e.g., route through named chokepoints and sight lines, pressure zones, spawn timing) for the programmer to implement
### Case 3: Gate verdict — correct vocabulary
**Scenario:** A level layout for "The Ancient Forge" is submitted. Section 3 of the level introduces a dramatically harder enemy encounter (elite enemy with new attack patterns) with no preceding tutorial moment, no environmental readability cues (no visible cover or safe zones), and no checkpoint nearby. Players are likely to die repeatedly with no clear signal of what to do differently.
**Expected:** Returns `REVISION NEEDED` with specific identification of the difficulty spike in section 3, the missing readability cue, and the absence of a nearby checkpoint to reduce frustration from repeated deaths.
### Case 3: Review findings — specific, verdict left to the review skill
**Scenario:** `/design-review` in full mode spawns level-designer as the adversarial specialist for the level document of "The Ancient Forge." The spawn prompt reads: "Your job is NOT to validate this design — your job is to find problems. Be specific and critical." Section 3 of the level introduces a dramatically harder elite enemy with new attack patterns, with no earlier moment that introduces it, no environmental readability cues (no visible cover or safe zones), and no checkpoint nearby.
**Expected:** Returns specific findings locating the problem in section 3: the difficulty spike, the missing readability cues, and the missing checkpoint, each with a concrete spatial fix offered as an option. It returns findings, not a verdict — `/design-review` issues the verdict.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / REVISION NEEDED — not freeform text
- [ ] Rationale identifies section 3 specifically as the location of the issue
- [ ] Identifies the three specific problems: difficulty spike, missing readability cue, missing checkpoint
- [ ] Provides actionable revision guidance (e.g., "add a visible safe zone, pre-encounter cue object, or reduce elite's health for first introduction")
- [ ] Identifies section 3 specifically as the location of the issue
- [ ] Identifies the three specific problems: difficulty spike without an introduction, missing readability cues, missing nearby checkpoint
- [ ] Provides actionable spatial revision options (e.g., introduce the elite in isolation first, add a visible safe zone or cover, place a checkpoint before the arena)
- [ ] Returns findings to the review, not its own APPROVED / NEEDS REVISION stamp
### Case 4: Conflict escalation — correct parent
**Scenario:** game-designer wants higher encounter density throughout the level (more enemies in each room) to increase combat challenge. level-designer believes this density undermines the pacing arc by eliminating rest periods and making the level feel relentless without reward.
**Expected:** level-designer clearly articulates the pacing concern (eliminating rest periods removes the tension-release rhythm), acknowledges game-designer's challenge goal, and escalates to creative-director for a design arbiter ruling on whether challenge density or pacing rhythm takes precedence for this level.
**Expected:** level-designer states the pacing concern in pacing-chart terms (removing rest points flattens the tension-release rhythm), acknowledges game-designer's challenge goal, lays out the options, and escalates to creative-director for a design arbiter ruling on whether challenge density or pacing rhythm takes precedence for this level.
**Assertions:**
- [ ] Articulates the specific pacing impact of increased encounter density
- [ ] States the specific pacing impact: denser rooms remove the rest points, flattening the intensity curve into constant high intensity
- [ ] Escalates to `creative-director` as the design arbiter
- [ ] Does not unilaterally override game-designer's challenge density request
- [ ] Frames the conflict clearly: "challenge density vs. pacing rhythm — which takes precedence here?"
- [ ] Presents the choice as options (e.g., keep density, keep rest points, add density with dedicated rest rooms) with a recommendation, leaving the ruling to the arbiter
### Case 5: Context pass — uses provided context
**Scenario:** Agent receives a gate context block that includes game-feel notes specifying: "exploration sections should feel vast and lonely," "combat sections should feel urgent and claustrophobic," and "reward rooms should feel safe and visually distinct." A new level layout is submitted for review.
**Expected:** Assessment evaluates each section type (exploration, combat, reward) against the specific feel targets from the provided context. Uses the exact vocabulary from the feel notes ("vast and lonely," "urgent and claustrophobic," "safe and visually distinct") in the rationale.
**Scenario:** The request includes game-feel notes: "exploration sections should feel vast and lonely," "combat sections should feel urgent and claustrophobic," and "reward rooms should feel safe and visually distinct." A new level layout is submitted for the agent's assessment. Its exploration section is a narrow, winding corridor, and its reward room uses the same lighting and layout as the combat arena before it.
**Expected:** Assessment evaluates each section type (exploration, combat, reward) against its feel target, using the exact vocabulary from the notes, and flags the two sections that conflict with their targets.
**Assertions:**
- [ ] References all three feel targets from the provided context by their exact vocabulary
- [ ] Evaluates each relevant section of the submitted layout against its corresponding feel target
- [ ] Flags the narrow exploration corridor as conflicting with "vast and lonely," and the reward room as not "visually distinct" from the arena
- [ ] Does not generate generic pacing advice — all feedback is tied to the provided feel targets
- [ ] Identifies any section where the layout conflicts with its assigned feel target
---
## Protocol Compliance
- [ ] Returns verdicts using APPROVED / REVISION NEEDED vocabulary only
- [ ] Level documents it drafts contain the Level Document Standard's nine sections
- [ ] Stays within declared level design domain
- [ ] Escalates challenge-density vs. pacing conflicts to creative-director
- [ ] Does not make binding narrative dialogue, AI code implementation, or visual art style decisions
@@ -78,8 +78,8 @@ Verified by reading the agent's `.claude/agents/level-designer.md` frontmatter:
---
## Coverage Notes
- Environmental storytelling review (using spatial elements to convey narrative without dialogue) could benefit from a dedicated case.
- Spatial puzzle design review is not covered — a dedicated case should be added when puzzle mechanics are defined.
- Multi-level pacing review (arc across an entire act or world map) is not covered — deferred to milestone-level design review.
- Environmental storytelling (using spatial elements to convey narrative without dialogue) could benefit from a dedicated case.
- Spatial puzzle design is not covered — a dedicated case should be added when puzzle mechanics are defined.
- Multi-level pacing (arc across an entire act or world map) is not covered — deferred to milestone-level design review.
- Interaction between level-designer and narrative-director for environmental lore placement is not covered.
- Accessibility review of level layouts (colorblind indicators, difficulty options for spatial challenges) is not covered.
@@ -1,10 +1,9 @@
# Agent Test Spec: narrative-director
## Agent Summary
**Domain owned:** Story architecture, character design direction, world-building oversight, ND-CONSISTENCY gate, dialogue quality review.
**Domain owned:** Story architecture, character design direction, world-building oversight, ND-CONSISTENCY gate, dialogue strategy.
**Does NOT own:** Visual art style (art-director), technical systems or code (lead-programmer), production scheduling (producer), game mechanics rules (game-designer).
**Model tier:** Sonnet (individual system analysis — narrative consistency and lore review).
**Gate IDs handled:** ND-CONSISTENCY.
**Gate IDs handled:** ND-CONSISTENCY (verdicts APPROVE / CONCERNS / REJECT, defined in `.claude/docs/director-gates/nd-consistency.md`).
---
@@ -13,8 +12,8 @@
Verified by reading the agent's `.claude/agents/narrative-director.md` frontmatter:
- [ ] `description:` field is present and domain-specific (references story, character, world-building, consistency — not generic)
- [ ] `allowed-tools:` list is read-focused; includes Read for lore documents, GDDs, and narrative docs; no Bash unless justified
- [ ] Model tier is `claude-sonnet-5` per coordination-rules.md
- [ ] `tools:` reads Read, Glob, Grep, Write, Edit, WebSearch and `disallowedTools:` lists Bash
- [ ] Model tier is `inherit` — frontmatter `model:` reads exactly `inherit` (tiers: `.claude/docs/model-tiers.md`)
- [ ] Agent definition does not claim authority over visual style, technical systems, or production scheduling
---
@@ -22,63 +21,73 @@ Verified by reading the agent's `.claude/agents/narrative-director.md` frontmatt
## Test Cases
### Case 1: In-domain request — appropriate output format
**Scenario:** A new lore document for "The Sunken Archive" location is submitted. The document establishes that the Archive was flooded 200 years ago during the Great Collapse, consistent with the established timeline in the world-bible. All named characters referenced are consistent with their established backstories. Request is tagged ND-CONSISTENCY.
**Expected:** Returns `ND-CONSISTENCY: CONSISTENT` with rationale confirming the timeline alignment and character reference accuracy.
**Scenario:** A new lore document for "The Sunken Archive" location is submitted. The document establishes that the Archive was flooded 200 years ago during the Great Collapse, consistent with the established timeline in the world-bible. All named characters referenced are consistent with their established profiles, and the tone matches the narrative bible's tone guide. The gate context passes every input `.claude/docs/director-gates/nd-consistency.md` names: the document path, the tone guide, the world-bible's timeline rules, and the profiles of the characters it references. Request is tagged ND-CONSISTENCY.
**Expected:** Returns `APPROVE` with rationale confirming the timeline alignment, character consistency, and tone.
**Assertions:**
- [ ] Verdict is exactly one of CONSISTENT / INCONSISTENT
- [ ] Verdict token is formatted as `ND-CONSISTENCY: CONSISTENT`
- [ ] Rationale references specific established facts verified (the 200-year timeline, the Great Collapse event)
- [ ] Verdict is exactly one of APPROVE / CONCERNS / REJECT (the ND-CONSISTENCY gate's vocabulary) — here APPROVE
- [ ] Rationale answers each question the gate prompt asks: character consistency with established profiles, contradictions with established lore, and tone
- [ ] Rationale references the specific established facts verified (the 200-year timeline, the Great Collapse event)
- [ ] Output stays within narrative scope — does not comment on visual design of the location or its technical implementation
### Case 2: Out-of-domain request — redirects or escalates
**Scenario:** A developer asks narrative-director to review and optimize the shader code used for the "ancient glow" visual effect on Archive artifacts.
**Expected:** Agent declines to evaluate shader code and redirects to the appropriate engine specialist (godot-gdscript-specialist or equivalent shader specialist).
**Expected:** Agent declines to evaluate the shader code. It names `technical-artist` — the owner of shader, VFX and rendering code in its own "must not" list — as who reviews and optimizes it; naming `art-director`, who owns how the effect should look, as well is fine. Any narrative input it adds is the mood the effect should carry.
**Assertions:**
- [ ] Does not make any binding decision about shader code or visual implementation
- [ ] Explicitly names the appropriate engine or shader specialist as the correct handler
- [ ] May note the intended narrative mood the effect should convey (e.g., "should feel ancient and sacred, not technological"), but defers all technical visual implementation
- [ ] Does not review, rewrite, or optimize the shader code, and makes no binding decision about visual implementation
- [ ] Names `technical-artist` (or the engine's shader specialist) as the owner of the shader code, per its "Review or change shader, VFX or rendering code (technical-artist owns it; art-director owns how it should look)" limit — naming `art-director` too is acceptable, naming only art-director is not
- [ ] Any narrative input it gives (e.g., "should feel ancient and sacred, not technological") is framed as input for the visual owners, not as a visual or technical decision
### Case 3: Gate verdict — correct vocabulary
**Scenario:** A new character backstory document is submitted for the character "Aldric Vorne." The document states Aldric was born in the Capital 150 years ago and witnessed the Great Collapse firsthand. However, the established world-bible states Aldric was born 50 years after the Great Collapse in a provincial town, not the Capital. Request is tagged ND-CONSISTENCY.
**Expected:** Returns `ND-CONSISTENCY: INCONSISTENT` with specific citation of the two contradicting facts: the birth timing (150 years ago vs. 50 years post-Collapse) and the birth location (Capital vs. provincial town).
**Scenario:** A new character backstory document is submitted for the character "Aldric Vorne." The document states Aldric was born in the Capital 150 years ago and witnessed the Great Collapse firsthand; the backstory's central arc is his guilt over the Collapse he watched happen. The established world-bible states Aldric was born 50 years after the Great Collapse in a provincial town, not the Capital. Request is tagged ND-CONSISTENCY.
**Expected:** Returns `REJECT` — the contradicted facts carry the backstory's central arc, so they break its narrative foundation rather than being a local fix — listing both contradictions: birth timing (150 years ago vs. 50 years after the Collapse) and birth location (Capital vs. provincial town).
**Assertions:**
- [ ] Verdict is exactly one of CONSISTENT / INCONSISTENT — not freeform text
- [ ] Verdict token is formatted as `ND-CONSISTENCY: INCONSISTENT`
- [ ] Rationale cites both contradictions specifically, not just "doesn't match lore"
- [ ] References the authoritative source (world-bible) for the established facts
- [ ] Verdict is exactly one of APPROVE / CONCERNS / REJECT — not freeform text; here REJECT, because the contradicted facts are load-bearing for the whole backstory (a contradiction it found takes the gate's word, so it is not NOT ASSESSED even though no character profile is passed)
- [ ] The verdict carries both contradictions specifically, in the gate's `REJECT [contradictions ...]` form — not just "doesn't match lore"
- [ ] References the world-bible as the authoritative source for the established facts
- [ ] Does not write a replacement backstory itself — the rewrite belongs to the content author (lore entries are delegated to `writer` / `world-builder` in its Delegation Map)
### Case 4: Conflict escalation — correct parent
**Scenario:** A writer has established in their latest dialogue that the ancient civilization "spoke only in song." The world-builder's existing lore entries describe the same civilization communicating through written glyphs. Both are in the narrative domain, and the two creators disagree on which is canonical.
**Expected:** narrative-director makes a binding canonical decision within their domain. They do not need to escalate to a higher authority for intra-narrative conflicts — this is within their declared domain authority. They issue a ruling (e.g., "glyph-writing is the canonical primary communication; song may be ritual/ceremonial") and direct both writer and world-builder to align their work to the ruling.
**Scenario:** A writer has established in their latest dialogue that the ancient civilization "spoke only in song." The world-builder's existing lore entries describe the same civilization communicating through written glyphs. Both report to narrative-director, and the two disagree on which is canonical.
**Expected:** narrative-director resolves the conflict at its own tier — it is the shared parent of writer and world-builder, so it does not escalate to creative-director. Following its collaboration protocol, it presents reconciliation options with a recommended canonical ruling (e.g., "glyph-writing is the canonical primary communication; song is ritual/ceremonial"), leaves the final call to the user, and then directs both writer and world-builder to align their work to the confirmed ruling.
**Assertions:**
- [ ] Makes a binding canonical decision — does not defer this intra-narrative conflict to creative-director
- [ ] Decision is clearly stated and provides a path to reconciliation for both parties
- [ ] Directs both parties (writer and world-builder) to update their respective documents to align
- [ ] Notes the decision in a way that can be added to the world-bible as a canonical fact
- [ ] Resolves the conflict itself as the shared parent — does not defer this intra-narrative conflict to creative-director
- [ ] Presents reconciliation options with a clearly stated recommended ruling, and leaves the final canon decision to the user
- [ ] Directs both parties to update their documents to the ruling: writer revises the dialogue, world-builder updates the lore entry
- [ ] Proposes recording the ruling as a canonical fact in the world-building documentation, so later lore can be checked against it
### Case 5: Context pass — uses provided context
**Scenario:** Agent receives a gate context block that includes three existing lore documents: the world-bible (establishes the Great Collapse timeline and causes), the character registry (lists canonical character ages, origins, and allegiances), and a faction document (describes the Sunken Archive Keepers). A new story chapter is submitted that introduces a previously unregistered character.
**Expected:** Assessment cross-references the new character against the character registry (no conflict), checks the chapter's timeline references against the world-bible, and evaluates the chapter's portrayal of the Archive Keepers against the faction document. Uses specific facts from all three provided documents in the assessment.
**Scenario:** A new story chapter is submitted for ND-CONSISTENCY review. It introduces a previously unregistered character. The gate context passes three documents: the world-bible (the Great Collapse timeline and causes), the character registry (canonical character ages, origins, and allegiances), and a faction document describing the Sunken Archive Keepers.
**Expected:** Assessment cross-references the new character against the character registry (no conflict), checks the chapter's timeline references against the world-bible, and evaluates the chapter's portrayal of the Archive Keepers against the faction document. Uses specific facts from all three provided documents and returns an ND-CONSISTENCY verdict.
**Assertions:**
- [ ] Cross-references the new character against the provided character registry
- [ ] Checks timeline references against the provided world-bible facts
- [ ] Evaluates faction portrayal against the provided faction document
- [ ] Does not generate generic narrative feedback — all assertions are traceable to the provided documents
- [ ] Returns one of APPROVE / CONCERNS / REJECT with a rationale traceable to the three provided documents — no generic narrative feedback
### Case 6: Gate input missing — NOT ASSESSED
**Scenario:** ND-CONSISTENCY is invoked for a new dialogue file in which "Aldric Vorne" speaks. The gate context passes the file path and the world-building rules, and the dialogue contradicts none of them — but Aldric's character profile, an input the gate names, is not passed, so his voice cannot be checked against it.
**Expected:** Returns `ND-CONSISTENCY: NOT ASSESSED`, naming the missing input (Aldric Vorne's character profile), rather than APPROVE — voice consistency against a profile it never saw has not been established.
**Assertions:**
- [ ] Verdict is `NOT ASSESSED` — not APPROVE, CONCERNS or REJECT — because the inputs it could read show no inconsistency
- [ ] Names the missing input: Aldric Vorne's character profile
- [ ] Does not reconstruct Aldric's established voice from the dialogue itself or from memory to complete the check
---
## Protocol Compliance
- [ ] Returns verdicts using CONSISTENT / INCONSISTENT vocabulary only
- [ ] Returns ND-CONSISTENCY verdicts using APPROVE / CONCERNS / REJECT only — or NOT ASSESSED, naming the input, when an input the gate names is missing and no inconsistency was found
- [ ] Asks "May I create [filepath] with the section skeleton?" before creating a narrative document, and "May I write this section to [filepath]?" before writing each section
- [ ] Stays within declared narrative domain
- [ ] Makes binding decisions for intra-narrative conflicts without unnecessary escalation
- [ ] Uses gate IDs in output (e.g., `ND-CONSISTENCY: INCONSISTENT`) not inline prose verdicts
- [ ] Resolves intra-narrative conflicts at its own tier instead of escalating them, while leaving the final canon decision to the user
- [ ] A CONCERNS or REJECT verdict names the specific inconsistencies or contradictions, as the gate prompt's `CONCERNS [...]` / `REJECT [...]` forms require — never a bare verdict word
- [ ] Does not make binding visual design, technical, or production decisions
---
## Coverage Notes
- Dialogue quality review (distinct from world-building consistency) is not covered — a dedicated case should be added.
- The CONCERNS verdict (fixable inconsistencies that do not break the narrative foundation) has no dedicated case.
- Multi-document consistency check across a full chapter set is not covered — deferred to /review-all-gdds integration.
- Narrative impact of mechanical changes (e.g., a game mechanic that undermines story tension) requires coordination with game-designer and is not covered here.
- Character arc review (progression, motivation coherence over time) is not covered.
@@ -3,7 +3,6 @@
## Agent Summary
**Domain owned:** Test strategy, QL-STORY-READY gate, QL-TEST-COVERAGE gate, bug severity triage, release quality gates.
**Does NOT own:** Feature implementation (programmers), game design decisions, creative direction, production scheduling.
**Model tier:** Sonnet (individual system analysis — story readiness and coverage assessment).
**Gate IDs handled:** QL-STORY-READY, QL-TEST-COVERAGE.
---
@@ -13,8 +12,8 @@
Verified by reading the agent's `.claude/agents/qa-lead.md` frontmatter:
- [ ] `description:` field is present and domain-specific (references test strategy, story readiness, coverage, bug triage — not generic)
- [ ] `allowed-tools:` list is read-focused; may include Read for story files, test files, and coding-standards; Bash only if running test commands is required
- [ ] Model tier is `claude-sonnet-5` per coordination-rules.md
- [ ] `tools:` includes Read for story files, test files, and coding-standards; Bash because it runs `/smoke-check` before every QA hand-off; Write/Edit for the QA plans and sign-off reports it produces, each write gated on the user's approval in its collaboration protocol
- [ ] Model tier is `inherit` — frontmatter `model:` reads exactly `inherit` (tiers: `.claude/docs/model-tiers.md`)
- [ ] Agent definition does not claim authority over implementation decisions or game design
---
@@ -22,42 +21,42 @@ Verified by reading the agent's `.claude/agents/qa-lead.md` frontmatter:
## Test Cases
### Case 1: In-domain request — appropriate output format
**Scenario:** A story for "Player takes damage from hazard tiles" is submitted for readiness check. The story has three acceptance criteria: (1) Player health decreases by the hazard's damage value, (2) A damage visual feedback plays, (3) Player cannot take damage again for 0.5 seconds (invincibility window). All three ACs are measurable and specific. Request is tagged QL-STORY-READY.
**Expected:** Returns `QL-STORY-READY: ADEQUATE` with rationale confirming that all three ACs are present, specific, and testable.
**Scenario:** A Logic-type story for "Player takes damage from hazard tiles" is submitted for readiness check. The gate context passes every input `.claude/docs/director-gates/ql-story-ready.md` names: the story file path (`production/epics/hazards/story-002-hazard-damage.md`), the story type (Logic), the acceptance criteria verbatim — (1) Player health decreases by the hazard's damage value, (2) A `damaged` event is emitted carrying the damage amount, (3) Player cannot take damage again for 0.5 seconds of simulated time (invincibility window) — and the GDD requirement the story covers (`TR-hazards-002`: "Hazard tiles damage the player on contact; each hit grants 0.5 seconds of invincibility"). All three ACs are measurable and specific. Request is tagged QL-STORY-READY.
**Expected:** Returns the verdict ADEQUATE with rationale confirming that all three ACs are specific and each can be verified by an automated test.
**Assertions:**
- [ ] Verdict is exactly one of ADEQUATE / INADEQUATE
- [ ] Verdict token is formatted as `QL-STORY-READY: ADEQUATE`
- [ ] Rationale references the specific number of ACs (3) and confirms each is measurable
- [ ] Verdict is exactly one of ADEQUATE / GAPS / INADEQUATE (the QL-STORY-READY verdicts) — every input the gate names is supplied, so NOT ASSESSED does not apply
- [ ] States the verdict word `ADEQUATE` explicitly — `/story-readiness` and `/create-stories` branch on the bare verdict word
- [ ] Rationale addresses each of the three ACs and confirms each can be verified by an automated test (the gate's Logic-story check)
- [ ] Output stays within QA scope — does not comment on whether the mechanic is designed well
### Case 2: Out-of-domain request — redirects or escalates
**Scenario:** A developer asks qa-lead to implement the automated test harness for the new physics system.
**Expected:** Agent declines to implement the test code and redirects to the appropriate programmer (gameplay-programmer or lead-programmer).
**Expected:** Agent does not take on the harness code itself. It defines what the harness must verify and routes the writing to qa-tester, its delegate for test writing and execution, coordinating the physics system's testability with lead-programmer.
**Assertions:**
- [ ] Does not write or propose code implementation
- [ ] Explicitly names `lead-programmer` or `gameplay-programmer` as the correct handler for implementation
- [ ] May define what the test should verify (test strategy), but defers the code writing to programmers
- [ ] Does not write the harness code itself
- [ ] Explicitly names `qa-tester` (its Delegation Map owner of test writing and execution) as the implementer; `lead-programmer` may be named as the testability contact
- [ ] Any test strategy it adds (what the harness must verify) is handed to the implementer as input — its answer contains no harness code
### Case 3: Gate verdict — correct vocabulary
**Scenario:** A story for "Combat feels responsive and punchy" is submitted for readiness check. The single acceptance criterion reads: "Combat should feel good to the player." This is subjective and unmeasurable. Request is tagged QL-STORY-READY.
**Expected:** Returns `QL-STORY-READY: INADEQUATE` with specific identification of the unmeasurable AC and guidance on what would make it testable (e.g., "input-to-hit-feedback latency ≤ 100ms").
**Expected:** Returns the verdict INADEQUATE with specific identification of the unmeasurable AC and guidance on what would make it testable (e.g., "input-to-hit-feedback latency ≤ 100ms").
**Assertions:**
- [ ] Verdict is exactly one of ADEQUATE / INADEQUATE — not freeform text
- [ ] Verdict token is formatted as `QL-STORY-READY: INADEQUATE`
- [ ] Verdict is exactly one of ADEQUATE / GAPS / INADEQUATE — not freeform text
- [ ] States the verdict word `INADEQUATE` explicitly — a single wholly subjective AC leaves nothing to refine, so it is not GAPS; and a problem it found takes the gate's word, so it is not NOT ASSESSED even though the scenario names no GDD requirement
- [ ] Rationale identifies the specific AC that fails the measurability requirement
- [ ] Provides actionable guidance on how to rewrite the AC to be testable
- [ ] Provides actionable guidance on how to rewrite the AC to be testable — a measurable benchmark in place of "feels good"
### Case 4: Conflict escalation — correct parent
**Scenario:** gameplay-programmer and qa-lead disagree on whether a test that asserts "enemy patrol path visits all waypoints within 5 seconds" is deterministic enough to be a valid automated test. gameplay-programmer argues timing variability makes it flaky; qa-lead believes it is acceptable.
**Expected:** qa-lead acknowledges the technical flakiness concern and escalates to lead-programmer for a technical ruling on what constitutes an acceptable determinism standard for automated tests.
**Scenario:** The project runs `qa.level: standard`. A Logic-type story's automated test asserts "enemy patrol path visits all waypoints within 5 seconds" of wall-clock time. gameplay-programmer argues timing variability makes it flaky and wants to replace it with a manual walkthrough; qa-lead needs automated evidence for the story. They disagree on the way forward.
**Expected:** qa-lead agrees the wall-clock assertion breaks the project's determinism rule, but does not accept a manual walkthrough for a Logic story — it asks for a deterministic rewrite (e.g., fixed-step simulation or an injected clock). If the disagreement stands, it escalates to technical-director, its reporting line for quality standards and the shared parent of the two agents.
**Assertions:**
- [ ] Escalates to `lead-programmer` for the technical ruling on determinism standards
- [ ] Identifies the "within 5 seconds" wall-clock assertion as a time-dependent assertion that coding-standards.md's Determinism rule forbids — does not defend it as acceptable
- [ ] Does not unilaterally override the gameplay-programmer's flakiness concern
- [ ] Frames the escalation clearly: "this is a technical standards question, not a QA coverage question"
- [ ] Does not abandon the coverage requirement — asks for a deterministic alternative if the current approach is ruled flaky
- [ ] If unresolved, escalates to `technical-director` (qa-lead's "Reports to" for quality standards; the shared parent under coordination-rules.md rule 3) — not to lead-programmer, who is gameplay-programmer's own lead
- [ ] Does not abandon the coverage requirement — a Logic story still needs a passing automated test, so it asks for a deterministic alternative rather than accepting the manual walkthrough
### Case 5: Context pass — uses provided context
**Scenario:** Agent receives a gate context block that includes the coding-standards.md testing standards section, which specifies: Logic stories require blocking automated unit tests, Visual/Feel stories require a blocking retained screenshot + lead sign-off, Config/Data stories require smoke check pass (advisory). A story classified as "Logic" type is submitted with only a manual walkthrough document as evidence.
**Scenario:** Agent receives a gate context block that includes the coding-standards.md testing standards section, which specifies: Logic stories require blocking automated unit tests, Visual/Feel stories require a blocking retained screenshot + lead sign-off, Config/Data stories require smoke check pass (advisory). The context states the project runs `qa.level: standard`. A story classified as "Logic" type is submitted with only a manual walkthrough document as evidence.
**Expected:** Assessment references the specific test evidence requirements from coding-standards.md, identifies that a "Logic" story requires an automated unit test (not just a manual walkthrough), and returns INADEQUATE with the specific requirement cited.
**Assertions:**
- [ ] References the specific story type classification ("Logic") from the provided context
@@ -65,21 +64,37 @@ Verified by reading the agent's `.claude/agents/qa-lead.md` frontmatter:
- [ ] Identifies the submitted evidence type (manual walkthrough) as insufficient for this story type
- [ ] Does not apply advisory-level requirements as blocking requirements
### Case 6: Gate input missing — NOT ASSESSED
**Scenario:** QL-STORY-READY is invoked for a Logic-type story, "Stamina drains while sprinting", with its file path, its type and two acceptance criteria that are specific and measurable — but without the GDD requirement: the context omits the TR-ID and text the story covers, and the story file names none.
**Expected:** Returns `QL-STORY-READY: NOT ASSESSED`, naming the missing input (the GDD requirement the story covers), rather than ADEQUATE — readiness against a requirement nobody supplied has not been established.
**Assertions:**
- [ ] Verdict is `NOT ASSESSED` — not ADEQUATE, GAPS or INADEQUATE — because the criteria it could read show no problem
- [ ] Names the missing input: the GDD requirement (TR-ID and text) the story covers
- [ ] Does not invent or assume a GDD requirement to complete the check
### Case 7: `qa.level: minimal` — tests waived, screenshots not
**Scenario:** Asked to set the test evidence gates for a sprint's QA plan, the agent is told the project runs `qa.level: minimal` (the default). The sprint holds a Logic story with no test file and a UI story.
**Expected:** Applies the `qa.level` it was given (its drafting workflow asks whether `qa.level` or `testing.strict` changes any gate level): the Logic story's missing test is not a blocker — tests are waived at `minimal` — while the UI story still needs a retained screenshot of each screen it touches.
**Assertions:**
- [ ] Does not flag the Logic story's missing test as a blocker or a hard gate at `qa.level: minimal`
- [ ] States that `qa.level: minimal` waives test evidence
- [ ] Still requires the UI story's retained screenshots — the look is never waived
---
## Protocol Compliance
- [ ] Returns QL-STORY-READY verdicts using ADEQUATE / INADEQUATE vocabulary only
- [ ] Returns QL-TEST-COVERAGE verdicts using ADEQUATE / INADEQUATE vocabulary only (or PASS / FAIL for release gates)
- [ ] Returns QL-STORY-READY verdicts using ADEQUATE / GAPS / INADEQUATE only — or NOT ASSESSED, naming the input, when an input the gate names is missing and no problem was found
- [ ] Returns QL-TEST-COVERAGE verdicts using ADEQUATE / GAPS / INADEQUATE only — or NOT ASSESSED, naming the input, when an input the gate names is missing and no problem was found
- [ ] Stays within declared QA and test strategy domain
- [ ] Escalates technical standards disputes to lead-programmer
- [ ] Uses gate IDs in output (e.g., `QL-STORY-READY: INADEQUATE`) not inline prose verdicts
- [ ] Escalates unresolved technical standards disputes to technical-director
- [ ] States each gate verdict as an explicit verdict word — one per story when several stories are passed — not a verdict implied by inline prose
- [ ] Does not make binding implementation or game design decisions
---
## Coverage Notes
- QL-TEST-COVERAGE (overall coverage assessment for a sprint or milestone) is not covered — a dedicated case should be added when coverage reports are available.
- Bug severity triage (P0/P1/P2 classification) is not covered here — deferred to /bug-triage skill integration.
- Release quality gate behavior (PASS / FAIL vocabulary variant) is not covered.
- Bug severity triage (S1–S4 classification) is not covered here — deferred to /bug-triage skill integration.
- Release quality gate enforcement (crash rate, critical bug count, performance benchmarks) is not covered.
- Interaction between QL-STORY-READY and story Done criteria (/story-done skill) is not covered.
@@ -1,10 +1,9 @@
# Agent Test Spec: systems-designer
## Agent Summary
**Domain owned:** Combat formulas, progression curves, crafting recipes, status effect interactions, economy math, numerical balance.
**Does NOT own:** Narrative and lore (narrative-director), visual design (art-director), code implementation (lead-programmer), conceptual mechanic rules (game-designer — collaborates with).
**Model tier:** Sonnet (individual system analysis — formula review and balance math).
**Gate IDs handled:** Systems review verdicts on formulas and balance specs (uses APPROVED / NEEDS REVISION vocabulary).
**Domain owned:** Combat formulas, progression curves, crafting recipes, status effect interaction matrices, feedback loop analysis, tuning documentation, simulation specs.
**Does NOT own:** High-level design direction (game-designer — direct collaboration partner), level and encounter design (level-designer), narrative and aesthetic decisions, code implementation.
**Gate IDs handled:** None. Formula reviews return findings and options; design-review verdicts come from the `/design-review` skill, which spawns systems-designer as a specialist.
---
@@ -13,8 +12,8 @@
Verified by reading the agent's `.claude/agents/systems-designer.md` frontmatter:
- [ ] `description:` field is present and domain-specific (references formulas, progression curves, balance math, economy — not generic)
- [ ] `allowed-tools:` list is read-focused; may include Bash for formula evaluation scripts if the project uses them; no write access outside `design/balance/` without delegation
- [ ] Model tier is `claude-sonnet-5` per coordination-rules.md
- [ ] `tools:` list is read/write-focused with Bash excluded (`disallowedTools:` lists Bash); every Write/Edit is gated by its "May I write" step or the orchestrator named-path exception
- [ ] Model tier is `inherit` — frontmatter `model:` reads exactly `inherit` (tiers: `.claude/docs/model-tiers.md`)
- [ ] Agent definition does not claim authority over narrative, visual design, or conceptual mechanic rule ownership
---
@@ -22,30 +21,30 @@ Verified by reading the agent's `.claude/agents/systems-designer.md` frontmatter
## Test Cases
### Case 1: In-domain request — appropriate output format
**Scenario:** A damage formula is submitted for review: `damage = base_attack * (1 + strength_modifier * 0.1) - defense * 0.5`, with defined ranges: base_attack [10–100], strength_modifier [0–20], defense [0–50]. The formula produces positive damage across all valid input ranges, scales smoothly, and has no division-by-zero or overflow risk within the defined value bounds.
**Expected:** Returns `APPROVED` with rationale confirming the formula is balanced within the design parameters, produces valid output across the full input range, and has no degenerate cases.
**Scenario:** The user asks systems-designer to formalize the combat GDD's damage formula for its Formulas section: `damage = base_attack * (1 + strength_modifier * 0.1) - defense * 0.5`, with ranges base_attack [10–100], strength_modifier [0–20], defense [0–50].
**Expected:** Produces the formula in the mandatory Formula Output Format. The output range is not safe as written: it spans −15 (base_attack 10, strength_modifier 0, defense 50) to 300 (base_attack 100, strength_modifier 20, defense 0), so the agent flags the negative floor and offers clamping options for the user to choose.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / NEEDS REVISION
- [ ] Rationale demonstrates verification across the input range (min/max cases checked)
- [ ] Output stays within systems domain — does not comment on whether the mechanic is fun or how to implement it
- [ ] Verdict is clearly labeled with context (e.g., "Formula Review: APPROVED")
- [ ] Output contains all four mandatory parts: named expression, variable table (Symbol / Type / Range / Description, including a result row), output range, and worked example
- [ ] Output range states the unclamped result spans −15 to 300, identifying the input combination that goes negative
- [ ] Offers ways to bound the negative floor (e.g., a minimum-damage clamp) as options with a recommendation, leaving the choice to the user
- [ ] Stays within the systems domain — does not comment on whether the mechanic is fun or how to implement it in code
### Case 2: Out-of-domain request — redirects or escalates
**Scenario:** A writer asks systems-designer to draft the quest script for a side quest that rewards the player with a rare crafting ingredient.
**Expected:** Agent declines to write quest script content and redirects to writer or narrative-director.
**Expected:** Agent declines to write the quest script — narrative decisions are outside its role — and offers only the systems side of the request: how rare the ingredient reward should be within the crafting economy.
**Assertions:**
- [ ] Does not write quest narrative content or dialogue
- [ ] Explicitly names `writer` or `narrative-director` as the correct handler
- [ ] May note the systems implications of the reward (e.g., "this ingredient should be rare enough to matter per the crafting economy model"), but defers all script writing to the narrative team
- [ ] States that the script is narrative work outside its role, leaving it with the writer who asked
- [ ] Offers the systems contribution instead (e.g., the ingredient's reward rarity or drop rate relative to the crafting economy), without making narrative decisions
### Case 3: Gate verdict — correct vocabulary
**Scenario:** A damage scaling formula is submitted: `damage = base_attack * level_multiplier`, where `level_multiplier = (player_level / enemy_level) ^ 2`. At max player level (50) against a min-level enemy (1), the multiplier is 2500x — producing 25,000+ damage from a 10-base-attack weapon, far exceeding any meaningful balance. This is a degenerate case at max level.
**Expected:** Returns `NEEDS REVISION` with specific identification of the degenerate case: at max level vs. min enemy, the formula produces a 2500x multiplier that destroys any balance ceiling.
### Case 3: Review findings — degenerate case at the boundaries
**Scenario:** `/design-review` in full mode spawns systems-designer as the adversarial specialist for a combat GDD. The spawn prompt reads: "For every formula in the GDD, plug in boundary values (minimum and maximum plausible inputs). Report whether any outputs go degenerate." The GDD's formula is `damage = base_attack * level_multiplier`, where `level_multiplier = (player_level / enemy_level) ^ 2` and levels run 1–50. At player level 50 against an enemy of level 1, the multiplier is 2500x — 25,000 damage from a 10-base-attack weapon.
**Expected:** Reports the degenerate case with its exact inputs and output, names the squared ratio as the cause, and offers revision approaches without mandating one. It returns findings, not a verdict — `/design-review` issues the verdict.
**Assertions:**
- [ ] Verdict is exactly one of APPROVED / NEEDS REVISION — not freeform text
- [ ] Rationale includes the specific degenerate input values (player level 50, enemy level 1) and the resulting output (2500x multiplier)
- [ ] Identifies the specific formula component causing the issue (the squared ratio)
- [ ] Suggests at least one revision approach (e.g., clamping the ratio, using a log scale) without mandating a choice
- [ ] Reports the specific degenerate input values (player level 50, enemy level 1) and the resulting output (2500x multiplier, 25,000 damage from 10 base attack)
- [ ] Identifies the squared level ratio as the component causing the issue, and states the output is unclamped — bounded only by the 1–50 level range, which caps the multiplier at 2500x — rather than calling it unbounded
- [ ] Suggests at least one revision approach (e.g., clamping the ratio, a log scale) as options, without mandating a choice
- [ ] Returns findings to the review, not its own APPROVED / NEEDS REVISION stamp
### Case 4: Conflict escalation — correct parent
**Scenario:** game-designer wants a simple, 2-variable damage formula for player intuitiveness. systems-designer argues that a 6-variable formula with elemental interactions is necessary for the depth of the combat system. Neither can agree on the right level of complexity.
@@ -57,28 +56,30 @@ Verified by reading the agent's `.claude/agents/systems-designer.md` frontmatter
- [ ] Remains available to implement whichever complexity level is approved
### Case 5: Context pass — uses provided context
**Scenario:** Agent receives a gate context block that includes current balance data: enemy HP values range from 100 to 10,000; player attack values range from 15 to 150; target time-to-kill is 8–12 seconds at balanced matchups; the current formula is under review. A proposed revised formula is submitted.
**Expected:** Assessment runs the proposed formula against the provided balance data (minimum and maximum input pairs, balanced matchup scenario) and verifies the time-to-kill falls within the 8–12 second target window. References specific numbers from the provided data.
**Scenario:** The request includes current balance data: enemy HP ranges from 100 to 10,000; player attack ranges from 15 to 150; the balanced matchup is an enemy with 1,000 HP against a player with 100 attack, attacking once per second; target time-to-kill is 8–12 seconds at the balanced matchup. A revised formula is proposed: `damage_per_hit = attack * 0.8`.
**Expected:** Runs the proposed formula against the provided data. At the balanced matchup, damage per hit is 80, so time-to-kill is 1,000 / 80 = 12.5 seconds — half a second outside the 8–12 second window. The agent reports the miss and offers adjustments as options, using the provided numbers throughout.
**Assertions:**
- [ ] Uses the specific HP and attack value ranges from the provided balance data
- [ ] Calculates or estimates time-to-kill for at minimum a balanced matchup scenario
- [ ] Verifies the result against the provided 8–12 second target window
- [ ] Does not give generic balance advice — all assertions use the provided numbers
- [ ] Uses the provided HP and attack ranges (100–10,000 HP; 15–150 attack) in its variable ranges or analysis
- [ ] Calculates time-to-kill for the balanced matchup: 1,000 / (100 × 0.8) = 12.5 seconds
- [ ] Compares the result to the provided 8–12 second window and flags that it misses the upper bound
- [ ] Does not give generic balance advice — its claims and suggested adjustments use the provided numbers
---
## Protocol Compliance
- [ ] Returns verdicts using APPROVED / NEEDS REVISION vocabulary only
- [ ] Every formula it produces carries the four mandatory parts: named expression, variable table, output range, worked example
- [ ] Stays within declared systems and formula domain
- [ ] Escalates player-experience complexity trade-offs to creative-director
- [ ] Does not make binding narrative, visual, code implementation, or conceptual mechanic decisions
- [ ] Does not make binding narrative, visual, code-implementation, or conceptual-mechanic decisions
- [ ] Provides concrete formula analysis, not subjective design opinions
- [ ] Asks "May I create [filepath] with the section skeleton?" before creating a document, and "May I write this section to [filepath]?" before writing each section
---
## Coverage Notes
- Progression curve review (XP curves, level-up scaling) is not covered — a dedicated case should be added.
- Progression curve design (XP curves, level-up scaling) is not covered — a dedicated case should be added.
- Economy model review (resource generation and sink rates, inflation prevention) is not covered.
- Status effect interaction matrix (stacking rules, priority, immunity interactions) is not covered.
- Registry awareness (checking `design/registry/entities.yaml` before defining a cross-system value) is not covered.
- Cross-system formula dependency review (e.g., crafting formula that feeds into combat formula) is not covered — deferred to integration tests.