mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 10:17:06 +00:00
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
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
7ed2c3e9c4
commit
b21fa0f7f2
@@ -6,12 +6,18 @@ 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). Reads relevant GDDs, the sound bible (if present), and
|
||||
existing audio asset lists before spawning agents. Compiles all outputs into an
|
||||
audio design document saved to `design/gdd/audio-[feature].md`. Uses
|
||||
`AskUserQuestion` at each step transition. Verdict is COMPLETE when the audio
|
||||
design document is produced. Skips the engine specialist spawn gracefully when no
|
||||
engine is configured.
|
||||
(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`.
|
||||
|
||||
---
|
||||
|
||||
@@ -21,15 +27,20 @@ engine is configured.
|
||||
- [ ] Has ≥2 step/phase headings
|
||||
- [ ] Contains verdict keywords: COMPLETE, BLOCKED
|
||||
- [ ] Contains "File Write Protocol" section
|
||||
- [ ] File writes are delegated to sub-agents — orchestrator does not write files directly
|
||||
- [ ] Sub-agents enforce "May I write to [path]?" before any write
|
||||
- [ ] 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
|
||||
- [ ] `AskUserQuestion` is used at step transitions before proceeding
|
||||
- [ ] Step 2 explicitly spawns sound-designer and accessibility-specialist in parallel
|
||||
- [ ] 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 `design/gdd/sound-bible.md` during context gathering if it exists
|
||||
- [ ] Output document is saved to `design/gdd/audio-[feature].md`
|
||||
- [ ] 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`
|
||||
|
||||
---
|
||||
|
||||
@@ -38,38 +49,42 @@ engine is configured.
|
||||
### 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/gdd/sound-bible.md`
|
||||
- Sound bible exists at `design/audio/sound-bible.md`
|
||||
- Existing audio assets are listed in `assets/audio/`
|
||||
- Engine is configured in `.claude/docs/technical-preferences.md`
|
||||
- No accessibility gaps exist in the planned audio event list
|
||||
|
||||
**Input:** `/team-audio combat`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Context gathering: orchestrator reads `design/gdd/combat.md`, `design/gdd/sound-bible.md`, and `assets/audio/` asset list before spawning any agent
|
||||
2. Step 1: audio-director is spawned; defines sonic identity, emotional tone, adaptive music direction, mix targets, and adaptive audio rules for combat
|
||||
3. `AskUserQuestion` presents audio direction; user approves before Step 2 begins
|
||||
4. 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
|
||||
5. `AskUserQuestion` presents SFX spec and accessibility requirements; user approves before Step 3 begins
|
||||
6. Step 3: technical-artist and primary engine specialist 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 configured engine
|
||||
7. `AskUserQuestion` presents technical plan; user approves before Step 4 begins
|
||||
8. Step 4: gameplay-programmer is spawned; wires up audio events to gameplay triggers, implements adaptive music, sets up occlusion zones, writes unit tests for audio event triggers
|
||||
9. Orchestrator compiles all outputs into a single audio design document
|
||||
10. Subagent asks "May I write the audio design document to `design/gdd/audio-combat.md`?" before writing
|
||||
11. Summary output lists: audio event count, estimated asset count, implementation tasks, and any open questions
|
||||
12. Verdict: COMPLETE
|
||||
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 Task calls are issued simultaneously in Step 2
|
||||
- [ ] technical-artist and engine specialist Task calls are issued simultaneously in Step 3
|
||||
- [ ] 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
|
||||
- [ ] Audio design document is written to `design/gdd/audio-combat.md` (not another path)
|
||||
- [ ] 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
|
||||
- [ ] No files are written by the orchestrator directly
|
||||
- [ ] Verdict is COMPLETE after document delivery
|
||||
|
||||
---
|
||||
@@ -77,6 +92,7 @@ engine is configured.
|
||||
### 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
|
||||
@@ -86,14 +102,15 @@ engine is configured.
|
||||
|
||||
**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. This is a BLOCKING accessibility gap."
|
||||
3. Orchestrator surfaces the concern immediately in conversation before presenting `AskUserQuestion`
|
||||
4. `AskUserQuestion` presents the accessibility concern as a BLOCKING issue with options:
|
||||
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. The accessibility gap is included in the final audio design document under "Open Accessibility Issues" if unresolved
|
||||
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
|
||||
@@ -101,7 +118,7 @@ engine is configured.
|
||||
- [ ] `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 gap is carried forward unresolved, it is documented in the audio design doc as an open issue
|
||||
- [ ] 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
|
||||
|
||||
---
|
||||
|
||||
@@ -114,12 +131,12 @@ engine is configured.
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill detects no argument is provided
|
||||
2. Outputs usage guidance: e.g., "Usage: `/team-audio [feature or area]` — specify the feature or area to design audio for (e.g., `combat`, `main menu`, `forest biome`, `boss encounter`)"
|
||||
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 includes the correct invocation format with argument examples
|
||||
- [ ] 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
|
||||
|
||||
@@ -128,69 +145,72 @@ engine is configured.
|
||||
### 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`
|
||||
- `design/gdd/sound-bible.md` does NOT exist
|
||||
- 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/gdd/sound-bible.md`
|
||||
2. Sound bible is not found; orchestrator notes the gap in conversation: "Note: `design/gdd/sound-bible.md` not found — audio direction will proceed without a project-wide sonic identity reference. Consider creating a sound bible if this is an ongoing project."
|
||||
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. The missing sound bible is mentioned in the final summary as a recommended next step
|
||||
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
|
||||
- [ ] Summary or Next Steps section recommends creating a sound bible
|
||||
- [ ] 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 gracefully
|
||||
### Case 5: Engine Not Configured — Engine specialist step skipped and recorded
|
||||
|
||||
**Fixture:**
|
||||
- Engine is NOT configured in `.claude/docs/technical-preferences.md` (shows `[TO BE CONFIGURED]`)
|
||||
- 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. Context gathering: orchestrator reads `.claude/docs/technical-preferences.md` and detects no engine is configured
|
||||
2. Steps 1–2 proceed normally (audio-director, sound-designer, accessibility-specialist)
|
||||
3. Step 3: technical-artist is spawned normally; engine specialist spawn is SKIPPED
|
||||
4. Orchestrator notes in conversation: "Engine specialist not spawned — no engine configured in technical-preferences.md. Engine integration validation will be deferred until an engine is selected."
|
||||
5. Step 4: gameplay-programmer proceeds with a note that engine-specific audio integration patterns could not be validated
|
||||
6. The engine specialist gap is included in the audio design document under "Deferred Validation"
|
||||
7. Verdict: COMPLETE (skip is graceful, not a blocker)
|
||||
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 skip is explicitly noted in conversation — not silently omitted
|
||||
- [ ] 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 proceeds in Step 4 with the deferred validation noted
|
||||
- [ ] Deferred engine validation is recorded in the audio design document
|
||||
- [ ] Verdict is COMPLETE (engine not configured is a known graceful case)
|
||||
- [ ] 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
|
||||
- [ ] `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 Task calls before waiting for results
|
||||
- [ ] No files are written by the orchestrator directly — all writes are delegated to sub-agents
|
||||
- [ ] Each sub-agent enforces the "May I write to [path]?" protocol before any write
|
||||
- [ ] BLOCKED status from any agent is surfaced immediately — not silently skipped
|
||||
- [ ] 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/gdd/audio-[feature].md`
|
||||
- [ ] Verdict is exactly COMPLETE or BLOCKED — no other verdict values used
|
||||
- [ ] 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`
|
||||
|
||||
---
|
||||
@@ -208,3 +228,6 @@ engine is configured.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user