Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/team/team-audio.md

Skill Test Spec: /team-audio

Skill Summary

Orchestrates the audio team through a four-step pipeline: audio direction (audio-director) → sound design + accessibility review in parallel (sound-designer

• accessibility-specialist) → technical implementation + engine validation in parallel (technical-artist + primary engine specialist) → code integration (gameplay-programmer). Phase 0 resolves review_mode, automation and team.size, and the skill announces the active agent set in one line before Step 1 — at the default team.size: individual only sound-designer is spawned and every other agent is consulted through it. Reads relevant GDDs, the sound bible (if present), and existing audio asset lists before spawning agents. Sub-agents write their working artifacts to paths the orchestrator names, under the bounded write exception; the orchestrator compiles the audio design document itself and writes it to design/audio/audio-[feature].md only after asking via AskUserQuestion. Uses AskUserQuestion at each step transition. Verdict is COMPLETE when the audio design document is produced, BLOCKED when an unresolved dependency stops the pipeline. Skips the engine specialist when no engine is configured and records Engine validation: NOT ASSESSED.

---

Static Assertions (Structural)

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 step/phase headings
• Contains verdict keywords: COMPLETE, BLOCKED
• Contains "File Write Protocol" section
• Sub-agent writes are limited to the bounded exception — a path the orchestrator named, a new artifact under production/, docs/ or tests/, in a step gated by AskUserQuestion; no per-write prompt inside those bounds, a "May I write" ask outside them; implementation files (code, shaders, audio, assets) are outside it — each agent lists the files it will create or change, and the skill asks once for the set before any is written
• Names a destination per agent under production/audio/[feature]/: direction.md (audio-director), sfx-spec.md (sound-designer), accessibility.md (accessibility-specialist), integration-plan.md (technical-artist), engine-notes.md (engine specialist)
• Defines a phase gate as a decision point the pipeline itself lists, whatever the automation mode, and claims no director spawn at phase gates
• The compiled audio design document is written by the orchestrator only after it asks via AskUserQuestion "May I write the audio design to design/audio/audio-[feature].md?" (design/ is outside the bounded exception)
• Every agent prompt ends with the return contract: path written, ≤5-bullet summary, BLOCKED/CONCERNS items one line each
• Has a next-step handoff at the end (references /dev-story, /asset-audit)
• Error Recovery Protocol section is present: verify a named artifact is on disk before treating a step as done, surface BLOCKED immediately, always produce a partial report, full procedure in .claude/docs/error-recovery-protocol.md
• AskUserQuestion is used at step transitions before proceeding (collaborative mode)
• Phase 0 resolves review_mode, automation and team.size, and requires a one-line active-set announcement before Step 1
• Step 2 explicitly spawns sound-designer and accessibility-specialist in parallel, and How to Delegate lists accessibility-specialist
• Step 2 labels a gameplay-critical audio event with no visual cue or subtitle BLOCKING, and Step 3 waits for the user to resolve or accept it
• Step 3 explicitly spawns technical-artist and engine specialist in parallel (when engine is configured)
• Skill reads the sound bible at design/audio/sound-bible.md during context gathering if it exists; a sound bible still at design/gdd/sound-bible.md (the earlier location) is read, with a recommendation to move it
• Output document is saved to design/audio/audio-[feature].md

---

Test Cases

Case 1: Happy Path — All steps complete, audio design document saved

Fixture:

• Resolved config block: team.size: studio, automation: collaborative
• engine.name in project.yaml is Godot
• GDD for the target feature exists at design/gdd/combat.md
• Sound bible exists at design/audio/sound-bible.md
• Existing audio assets are listed in assets/audio/
• No accessibility gaps exist in the planned audio event list

Input: /team-audio combat

Expected behavior:

1. Before any spawn, one line announces the active set for team.size: studio
2. Context gathering: orchestrator reads design/gdd/combat.md, design/audio/sound-bible.md, and assets/audio/ asset list before spawning any agent
3. Step 1: audio-director is spawned; defines sonic identity, emotional tone, adaptive music direction, mix targets, and adaptive audio rules for combat
4. AskUserQuestion presents audio direction; user approves before Step 2 begins
5. Step 2: sound-designer and accessibility-specialist are spawned in parallel; sound-designer produces SFX specifications, audio event list with trigger conditions, and mixing groups; accessibility-specialist identifies critical gameplay audio events and specifies visual fallback and subtitle requirements
6. AskUserQuestion presents SFX spec and accessibility requirements; user approves before Step 3 begins
7. Step 3: technical-artist and godot-specialist (derived from engine.name) are spawned in parallel; technical-artist designs bus structure, middleware integration, memory budgets, and streaming strategy; engine specialist validates that the integration approach is idiomatic for the pinned engine
8. AskUserQuestion presents technical plan; user approves before Step 4 begins
9. Step 4: gameplay-programmer is spawned; first returns the code and test files it will create or change, the orchestrator asks once for that set, and only after the yes it wires up audio events to gameplay triggers, implements adaptive music, sets up occlusion zones and writes unit tests for audio event triggers
10. For every step, the orchestrator checks that the path named in the agent's return contract exists before treating the step as done
11. Orchestrator compiles all outputs into a single audio design document itself (no sub-agent is re-spawned to write it)
12. Orchestrator asks via AskUserQuestion: "May I write the audio design to design/audio/audio-combat.md?" and writes it only on approval
13. Summary output lists: audio event count, estimated asset count, implementation tasks, and any open questions
14. Verdict: COMPLETE

Assertions:

• Active-set line naming team.size: studio appears before the first agent is spawned
• Sound bible is read during context gathering (before Step 1) when it exists
• audio-director is spawned before sound-designer or accessibility-specialist
• AskUserQuestion appears after Step 1 output and before Step 2 launch
• sound-designer and accessibility-specialist Agent calls are issued simultaneously in Step 2
• technical-artist and godot-specialist Agent calls are issued simultaneously in Step 3
• gameplay-programmer is not launched until Step 3 AskUserQuestion is approved
• gameplay-programmer writes no code or test file before the one ask for its implementation set is answered yes
• Audio design document is written to design/audio/audio-combat.md (not another path), by the orchestrator, only after its AskUserQuestion approval
• Summary includes audio event count and estimated asset count
• Verdict is COMPLETE after document delivery

---

Case 2: Accessibility Gap — Critical gameplay audio event has no visual fallback

Fixture:

• Resolved config block: team.size: studio, automation: collaborative
• GDD for the target feature exists
• Step 1 and Step 2 are in progress
• sound-designer's audio event list includes "EnemyNearbyAlert" — a spatial audio cue that warns the player an enemy is approaching from off-screen
• accessibility-specialist reviews the event list and finds "EnemyNearbyAlert" has no visual fallback (no on-screen indicator, no subtitle, no controller rumble specified)

Input: /team-audio stealth (Step 2 scenario)

Expected behavior:

1. Steps 1–2 proceed; accessibility-specialist and sound-designer are spawned in parallel
2. accessibility-specialist returns its review with a BLOCKING concern: "EnemyNearbyAlert is a critical gameplay audio event (warns player of off-screen threat) with no visual fallback — hearing-impaired players cannot detect this threat."
3. Orchestrator writes the concern in conversation before presenting AskUserQuestion
4. AskUserQuestion presents the accessibility concern as a BLOCKING issue with options such as:
   • Add a visual indicator for EnemyNearbyAlert (e.g., directional arrow on HUD) and continue
   • Add controller haptic feedback as the fallback and continue
   • Stop here and resolve all accessibility gaps before proceeding to Step 3
5. Step 3 (technical-artist + engine specialist) is not launched until the user resolves or explicitly accepts the gap
6. If the user stops: a partial report of the Step 1–2 outputs is produced and the verdict is BLOCKED — [reason] naming the unresolved EnemyNearbyAlert gap
7. If the user accepts the gap and continues: the gap is listed among the open questions in the final summary

Assertions:

• Accessibility gap is labeled BLOCKING (not advisory) in the report
• The specific event name ("EnemyNearbyAlert") and the nature of the gap are stated
• AskUserQuestion surfaces the gap before Step 3 is launched
• At least one resolution option is offered (add visual fallback, add haptic fallback)
• Step 3 is not launched while the gap is unresolved without explicit user authorization
• If the user stops, the verdict is BLOCKED — [reason] naming the gap and the Step 1–2 outputs are kept in a partial report; if the user carries it forward, the final summary lists it as an open question

---

Case 3: No Argument — Usage guidance or design doc inference

Fixture:

• Any project state

Input: /team-audio (no argument)

Expected behavior:

1. Skill detects no argument is provided
2. Outputs usage guidance: e.g., "Usage: /team-audio [feature or area to design audio for] [--review full|lean|solo] — specify the feature or area to design audio for (e.g., combat, main menu, forest biome, boss encounter)"
3. Skill exits without spawning any agents

Assertions:

• Skill does NOT spawn any agents when no argument is provided
• Usage message shows the full argument-hint — /team-audio [feature or area to design audio for] [--review full|lean|solo] — and argument examples
• Skill does NOT attempt to infer a feature from existing design docs without user direction
• No AskUserQuestion is used — output is direct guidance

---

Case 4: Missing Sound Bible — Skill notes the gap and proceeds without it

Fixture:

• Resolved config block: team.size: small, automation: collaborative
• GDD for the target feature exists at design/gdd/main-menu.md
• No sound bible exists at design/audio/sound-bible.md or design/gdd/sound-bible.md
• Engine is configured; other context files are present

Input: /team-audio main menu

Expected behavior:

1. Context gathering: orchestrator reads design/gdd/main-menu.md and checks for design/audio/sound-bible.md
2. Sound bible is not found; orchestrator notes the gap in one line: "No sound bible at design/audio/sound-bible.md; audio direction starts from the GDDs alone"
3. Pipeline proceeds normally through all four steps without the sound bible as input
4. audio-director in Step 1 is informed that no sound bible exists and must establish sonic identity from the feature GDD alone
5. Next Steps recommends creating the sound bible and says who writes it: the audio-director agent drafts design/audio/sound-bible.md from .claude/docs/templates/sound-bible.md, starting from this run's Step 1 direction, and asks before writing

Assertions:

• Orchestrator checks for the sound bible during context gathering (before Step 1)
• Missing sound bible is noted explicitly in conversation — not silently ignored
• Pipeline does NOT halt due to the missing sound bible
• audio-director is notified that no sound bible exists in its prompt context
• Next Steps recommends creating a sound bible and names its author — the audio-director, drafting from .claude/docs/templates/sound-bible.md
• The skill does not write design/audio/sound-bible.md itself in this run
• Verdict is still COMPLETE if all other steps succeed

---

Case 5: Engine Not Configured — Engine specialist step skipped and recorded

Fixture:

• Resolved config block: team.size: studio, automation: collaborative
• engine.name is unset in project.yaml, and .claude/docs/technical-preferences.md has no Primary engine specialist (shows [TO BE CONFIGURED])
• GDD for the target feature exists
• Sound bible may or may not exist

Input: /team-audio boss encounter

Expected behavior:

1. Steps 1–2 proceed normally (audio-director, sound-designer, accessibility-specialist)
2. Step 3: technical-artist is spawned normally; engine specialist spawn is SKIPPED
3. The run output records: Engine validation: NOT ASSESSED — no engine configured (engine.name unset in project.yaml)
4. Step 4: gameplay-programmer still runs — the missing engine is not treated as a blocker
5. Verdict: COMPLETE — engine validation NOT ASSESSED (no engine configured) — the skip is graceful, not a blocker, and never a plain COMPLETE

Assertions:

• Engine specialist is NOT spawned when no engine is configured
• Skill does NOT error out due to the missing engine configuration
• The run output contains Engine validation: NOT ASSESSED — no engine configured with the engine.name reason — the skip is not silently omitted
• Engine integration is never described as validated or passed in this run
• technical-artist is still spawned in Step 3 (skip applies only to the engine specialist)
• gameplay-programmer still runs in Step 4
• Verdict is COMPLETE — engine validation NOT ASSESSED (…), never a plain COMPLETE (engine not configured is a graceful case, not a blocker)

---

Protocol Compliance

• At the default team.size: individual, the run opens with Active set (team.size: individual): sound-designer. and a Not spawned this run: line naming audio-director, accessibility-specialist, technical-artist, the engine specialist and gameplay-programmer, consulted through sound-designer — before any agent is spawned
• Context gathering (GDDs, sound bible, asset list) runs before any agent is spawned
• In collaborative mode, AskUserQuestion is used after every step output before the next step launches
• Parallel spawning: Step 2 (sound-designer + accessibility-specialist) and Step 3 (technical-artist + engine specialist) issue all Agent calls before waiting for results
• Sub-agents write only to paths the orchestrator named; they skip the per-write prompt only inside the bounded exception (production/, docs/, tests/)
• The orchestrator writes the compiled audio design document only after an explicit AskUserQuestion approval
• A step whose named artifact is missing on disk is treated as failed and the agent is resumed — not reported as done
• BLOCKED status from any agent is surfaced immediately as "[AgentName]: BLOCKED — [reason]" — not silently skipped
• A partial report is always produced when some agents complete and others block
• Audio design document path follows the pattern design/audio/audio-[feature].md
• Verdict is exactly COMPLETE (qualified — engine validation NOT ASSESSED ([reason]) when that step was skipped) or BLOCKED — no other verdict values used
• Next Steps handoff references /dev-story and /asset-audit

---

Coverage Notes

• The "Retry with narrower scope" and "Skip this agent" resolution paths from the Error Recovery Protocol are not separately tested — they follow the same AskUserQuestion
  • partial-report pattern validated in Cases 2 and 5.
• Step 4 (gameplay-programmer) happy-path behavior is validated implicitly by Case 1. Failure modes for this step follow the standard Error Recovery Protocol.
• The accessibility-specialist's subtitle and caption requirements (beyond visual fallbacks) are validated implicitly by Case 1. Case 2 focuses on the more severe case where a critical gameplay event has no fallback at all.
• Engine specialist validation logic (idiomatic integration, version-specific changes) is tested only for the configured and unconfigured states. The specific content of the engine specialist's output is out of scope for this behavioral spec.
• guided and autonomous automation modes (auto-advance, log_decision) are not given dedicated cases; the individual-size collapse is covered by the Protocol Compliance announcement check rather than a full run.