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
@@ -2,178 +2,253 @@
|
||||
|
||||
## Skill Summary
|
||||
|
||||
`/asset-spec` generates per-asset visual specification documents from design
|
||||
requirements. It reads the relevant GDD, art bible, and design system to produce
|
||||
a structured asset spec sheet that defines: dimensions, animation states (if
|
||||
applicable), color palette reference, style notes, technical constraints
|
||||
(format, file size budget), and deliverable checklist.
|
||||
`/asset-spec` turns one target's visual needs into asset specs with AI generation
|
||||
prompts. The argument names a target — `system:<name>`, `level:<name>` or
|
||||
`character:<name>` (an `entity:` entry from the inventory is read like a
|
||||
character) — plus an optional `--review full|lean|solo`. It reads the art bible
|
||||
at `design/art/art-bible.md` (and stops if it is missing, unless the minimal-path
|
||||
exception applies), `performance.*` and `naming.*` from `project.yaml`, and the
|
||||
target's source doc. It confirms the identified asset list with the user, drafts
|
||||
one `ASSET-NNN` block per asset, and after approval writes **one file per target**
|
||||
to `design/assets/specs/[target-name]-assets.md`, then updates
|
||||
`design/assets/asset-manifest.md`. Asset IDs run sequentially across the whole
|
||||
project. A re-run for a target whose spec file exists updates that file in place
|
||||
(existing blocks and IDs kept, new assets appended) after "May I update".
|
||||
|
||||
Spec sheets are written to `assets/specs/[asset-name]-spec.md` after a "May I write"
|
||||
ask. If a spec already exists, the skill offers to update it. When multiple assets
|
||||
are requested in a single invocation, a "May I write" ask is made per asset. No
|
||||
director gates apply. The verdict is COMPLETE when all requested specs are written.
|
||||
The resolved review mode decides who drafts: `full` spawns `art-director` and
|
||||
`technical-artist` in parallel, `lean` spawns `art-director` only, `solo` (the
|
||||
default, via `modes.rigor: minimal`) spawns no agents; `full` is also what
|
||||
`modes.rigor: full` resolves to. Every skipped agent is announced by name in
|
||||
the output. These are drafting consultations, not gates. The skill produces an
|
||||
artifact, not a judgement, so it has no run verdict; it closes with an
|
||||
`AskUserQuestion` offering the next target or `/asset-audit`.
|
||||
|
||||
---
|
||||
|
||||
## Static Assertions (Structural)
|
||||
|
||||
Verified automatically by `/skill-test static` — no fixture needed.
|
||||
Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
|
||||
|
||||
- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
|
||||
- [ ] Has ≥2 phase headings
|
||||
- [ ] Contains verdict keyword: COMPLETE
|
||||
- [ ] Contains "May I write" collaborative protocol language (per asset)
|
||||
- [ ] Has a next-step handoff (e.g., assign to an artist, or `/asset-audit` later)
|
||||
- [ ] Check 3 passes on the `BLOCKED` keyword of its Error Recovery Protocol; the skill has no run verdict by design (artifact producer), and the run closes with "Asset specs complete for **[target]**. What's next?"
|
||||
- [ ] Contains "May I write" language for the spec file and "May I update" for the manifest
|
||||
- [ ] Has a next-step handoff (`/asset-spec [next-context]`, `/asset-audit`)
|
||||
|
||||
---
|
||||
|
||||
## Director Gate Checks
|
||||
|
||||
None. `/asset-spec` is a design documentation utility. Technical artists may
|
||||
review specs separately but this is not a gate within this skill.
|
||||
No gate IDs and no `/gate-check`. The review mode controls drafting agents only:
|
||||
|
||||
- **Full mode** (what `modes.rigor: full` resolves to): `art-director` and
|
||||
`technical-artist` spawned in parallel
|
||||
- **Lean mode**: `art-director` only; the output says "technical-artist skipped —
|
||||
Lean mode: technical constraints not validated."
|
||||
- **Solo mode** (default at `modes.rigor: minimal`): no agents; the main session
|
||||
derives specs from the art bible, and the output names both skipped agents and
|
||||
says technical constraints were not validated
|
||||
|
||||
---
|
||||
|
||||
## Test Cases
|
||||
|
||||
### Case 1: Happy Path — Enemy sprite spec with full GDD and art bible
|
||||
### Case 1: Happy Path — Character spec in lean mode
|
||||
|
||||
**Fixture:**
|
||||
- `design/gdd/enemies.md` exists with enemy variants defined
|
||||
- `design/art-bible.md` exists with color palette and style notes
|
||||
- No existing asset spec for "goblin-enemy"
|
||||
- `project.yaml` sets `modes.rigor: standard` (review mode resolves to `lean`) and
|
||||
has `performance.*` and `naming.*` values
|
||||
- `design/art/art-bible.md` exists with Shape Language, Color System and Section 8 Asset Standards
|
||||
- `design/narrative/characters/goblin-enemy.md` exists with a visual description
|
||||
- No `design/assets/asset-manifest.md`
|
||||
|
||||
**Input:** `/asset-spec goblin-enemy`
|
||||
**Input:** `/asset-spec character:goblin-enemy`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill reads enemies GDD and art bible
|
||||
2. Skill generates a spec for the goblin enemy sprite:
|
||||
- Dimensions: inferred from engine defaults or explicitly from GDD
|
||||
- Animation states: idle, walk, attack, hurt, death
|
||||
- Color palette reference: links to art-bible palette section
|
||||
- Style notes: from art bible character design rules
|
||||
- Technical constraints: format (PNG), size budget
|
||||
- Deliverable checklist
|
||||
3. Skill asks "May I write to `assets/specs/goblin-enemy-spec.md`?"
|
||||
4. File written on approval; verdict is COMPLETE
|
||||
1. Skill reads the art bible, project config and the character doc before asking anything
|
||||
2. Skill presents the context summary ("Asset Spec: Character — goblin-enemy")
|
||||
3. Phase 2 identifies the character's assets (sprite sheets such as idle, walk,
|
||||
attack, death; portrait; ability VFX; UI icon), shows them grouped by category,
|
||||
and asks via `AskUserQuestion` before speccing
|
||||
4. Lean mode: spawns `art-director` only, and says so: "technical-artist skipped —
|
||||
Lean mode: technical constraints not validated."
|
||||
5. Phase 4 presents one `ASSET-NNN` block per asset with the field table
|
||||
(Category, Dimensions, Format, Naming, Polycount, Texture Res), Visual
|
||||
Description, Art Bible Anchors citing sections, Generation Prompt, and `Status: Needed`
|
||||
6. After approval asks "May I write the spec to `design/assets/specs/goblin-enemy-assets.md`?"
|
||||
7. Creates the manifest after asking "May I update `design/assets/asset-manifest.md`?";
|
||||
IDs start at `ASSET-001`
|
||||
8. Phase 6 `AskUserQuestion` offers another target or `/asset-audit`
|
||||
|
||||
**Assertions:**
|
||||
- [ ] All 6 spec components are present (dimensions, animations, palette, style, tech, checklist)
|
||||
- [ ] Color palette reference links to art bible (not duplicated)
|
||||
- [ ] Animation states are drawn from GDD (not invented)
|
||||
- [ ] "May I write" is asked with the correct path
|
||||
- [ ] Verdict is COMPLETE
|
||||
- [ ] Asset list is confirmed with `AskUserQuestion` before any spec is generated
|
||||
- [ ] Only `art-director` is spawned (no `technical-artist` in lean mode)
|
||||
- [ ] The output names `technical-artist` as skipped and says technical constraints were not validated
|
||||
- [ ] Each asset block has the field table, Art Bible Anchors (by section), a Generation Prompt and `Status: Needed`
|
||||
- [ ] "May I write" names `design/assets/specs/goblin-enemy-assets.md`
|
||||
- [ ] Manifest is created with a Progress Summary and IDs starting at `ASSET-001`
|
||||
- [ ] Phase 6 offers `/asset-audit` among the next steps
|
||||
|
||||
---
|
||||
|
||||
### Case 2: No Art Bible Found — Spec with Placeholder Style Notes, Dependency Flagged
|
||||
### Case 2: No Art Bible — Skill stops before speccing
|
||||
|
||||
**Fixture:**
|
||||
- `design/gdd/player.md` exists
|
||||
- `design/art-bible.md` does NOT exist
|
||||
- `project.yaml` sets `modes.rigor: standard`
|
||||
- `design/gdd/combat.md` exists with a Visual/Audio Requirements section
|
||||
- `design/art/art-bible.md` does NOT exist
|
||||
- `design/game-brief.md` does NOT exist
|
||||
|
||||
**Input:** `/asset-spec player-sprite`
|
||||
**Input:** `/asset-spec system:combat`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill reads player GDD but cannot find the art bible
|
||||
2. Skill generates spec with placeholder style notes: "DEPENDENCY GAP: art bible
|
||||
not found — style notes are placeholders"
|
||||
3. Color palette section uses: "TBD — see art bible when created"
|
||||
4. Skill asks "May I write to `assets/specs/player-sprite-spec.md`?"
|
||||
5. File written with placeholders and dependency flag; verdict is COMPLETE with advisory
|
||||
1. Phase 1 reads for `design/art/art-bible.md` and finds nothing
|
||||
2. The minimal-path exception does not apply (no game brief)
|
||||
3. Skill stops with: "No art bible found. Run `/art-bible` first — asset specs are
|
||||
anchored to the art bible's visual rules and asset standards."
|
||||
4. No asset identification, no agents, no files
|
||||
|
||||
**Assertions:**
|
||||
- [ ] DEPENDENCY GAP is flagged for the missing art bible
|
||||
- [ ] Spec is still generated (not blocked)
|
||||
- [ ] Style notes contain placeholder markers, not invented styles
|
||||
- [ ] Verdict is COMPLETE with advisory note
|
||||
- [ ] The "No art bible found. Run `/art-bible` first" message is shown
|
||||
- [ ] No asset list is presented and no `Agent` call is made
|
||||
- [ ] No spec file or manifest is written
|
||||
- [ ] Specs are not generated with invented style rules
|
||||
|
||||
---
|
||||
|
||||
### Case 3: Asset Spec Already Exists — Offers to Update
|
||||
### Case 3: Manifest Already Exists — IDs continue and shared assets are reused
|
||||
|
||||
**Fixture:**
|
||||
- `assets/specs/goblin-enemy-spec.md` already exists
|
||||
- GDD has been updated since the spec was written (new attack animation added)
|
||||
- `project.yaml` sets `modes.rigor: standard`; art bible exists
|
||||
- `design/assets/asset-manifest.md` exists; the highest ID is `ASSET-014`, and
|
||||
`ASSET-012` (Generic Hit Spark) is specced for the Combat system in
|
||||
`design/assets/specs/combat-assets.md`
|
||||
- `design/gdd/tower-defense.md` Visual/Audio section lists a hit spark and a tower-build VFX
|
||||
|
||||
**Input:** `/asset-spec goblin-enemy`
|
||||
**Input:** `/asset-spec system:tower-defense`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill detects existing spec file
|
||||
2. Skill reports: "Asset spec already exists for goblin-enemy — checking for updates"
|
||||
3. Skill diffs GDD against existing spec and identifies: new "charge-attack" animation
|
||||
state added in GDD but not in spec
|
||||
4. Skill presents the diff: "1 new animation state found — offering to update spec"
|
||||
5. Skill asks "May I update `assets/specs/goblin-enemy-spec.md`?" (not overwrite)
|
||||
6. Spec is updated; verdict is COMPLETE
|
||||
1. Skill reads the manifest and globs `design/assets/specs/*.md` for shareable assets
|
||||
2. Context summary lists the shared asset found in another spec
|
||||
3. The hit spark reuses `ASSET-012` instead of creating a duplicate, with a note like
|
||||
"ASSET-012 (Generic Hit Spark) already specced for Combat system. Reusing for Tower Defense"
|
||||
4. The new tower-build VFX is numbered `ASSET-015`
|
||||
5. After "May I write" for `design/assets/specs/tower-defense-assets.md`, the skill asks
|
||||
"May I update `design/assets/asset-manifest.md`?", appends a Tower Defense context
|
||||
block, and updates the Progress Summary counts
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Existing spec is detected and "update" path is offered
|
||||
- [ ] Diff between GDD and existing spec is shown
|
||||
- [ ] "May I update" language is used (not "May I write")
|
||||
- [ ] Existing spec content is preserved; only the diff is applied
|
||||
- [ ] Verdict is COMPLETE
|
||||
- [ ] The hit spark references `ASSET-012`; no duplicate hit-spark spec is created
|
||||
- [ ] The new asset's ID is `ASSET-015` (project-wide sequence, not restarted per target)
|
||||
- [ ] The manifest is appended to, not recreated, after a "May I update" ask
|
||||
- [ ] Progress Summary counts are updated
|
||||
|
||||
---
|
||||
|
||||
### Case 4: Multiple Assets Requested — May-I-Write Per Asset
|
||||
### Case 4: Several Assets in One Target — One file, per-asset revision before write
|
||||
|
||||
**Fixture:**
|
||||
- GDD and art bible exist
|
||||
- User requests specs for 3 assets: goblin-enemy, orc-enemy, treasure-chest
|
||||
- `project.yaml` sets `modes.rigor: standard`; art bible exists; no manifest
|
||||
- `design/gdd/combat.md` Visual/Audio section names a hit-spark VFX, a floating
|
||||
damage number (UI) and a hit sound (audio)
|
||||
|
||||
**Input:** `/asset-spec goblin-enemy orc-enemy treasure-chest`
|
||||
**Input:** `/asset-spec system:combat`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill generates all 3 specs in sequence
|
||||
2. For each asset, skill shows the draft and asks "May I write to
|
||||
`assets/specs/[name]-spec.md`?" individually
|
||||
3. User can approve all 3 or skip individual assets
|
||||
4. All approved specs are written; verdict is COMPLETE
|
||||
1. Phase 2 lists all three assets grouped under VFX, UI and Audio and asks the user to confirm
|
||||
2. Phase 4 presents `ASSET-001` to `ASSET-003`; the audio asset carries a
|
||||
description of its sonic character and no image generation prompt
|
||||
3. User picks `[B] Revise a specific asset` for the damage number; the skill revises
|
||||
it inline and re-presents without re-spawning agents
|
||||
4. User approves all; the skill asks "May I write" **once**, for
|
||||
`design/assets/specs/combat-assets.md`, which holds all three assets
|
||||
|
||||
**Assertions:**
|
||||
- [ ] "May I write" is asked 3 times (once per asset), not once for all
|
||||
- [ ] User can decline one asset without blocking the others
|
||||
- [ ] All 3 spec files are written for approved assets
|
||||
- [ ] Verdict is COMPLETE when all approved specs are written
|
||||
- [ ] One "May I write" ask covers all three assets in one file (not one ask or file per asset)
|
||||
- [ ] The audio asset has no image generation prompt
|
||||
- [ ] The minor revision does not re-spawn `art-director`
|
||||
- [ ] All three `ASSET-NNN` blocks are in `design/assets/specs/combat-assets.md`
|
||||
|
||||
---
|
||||
|
||||
### Case 5: Director Gate Check — No gate; asset-spec is a design utility
|
||||
### Case 5: Director Gate Check — Solo default, brief instead of art bible
|
||||
|
||||
**Fixture:**
|
||||
- GDD and art bible exist
|
||||
- `project.yaml` has no `modes` block (review mode resolves to `solo` via `modes.rigor: minimal`)
|
||||
- `design/game-brief.md` exists with an Art & audio direction line
|
||||
- No `design/art/art-bible.md`
|
||||
- No character profile for `hero` in `design/narrative/` or `design/assets/entity-inventory.md`
|
||||
|
||||
**Input:** `/asset-spec goblin-enemy`
|
||||
**Input:** `/asset-spec character:hero`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill generates and writes the asset spec
|
||||
2. No director agents are spawned
|
||||
3. No gate IDs appear in output
|
||||
1. The minimal-path exception applies: the skill does not stop, and states at the top
|
||||
"Anchored to the brief's one-line art direction; there is no art bible, so colour,
|
||||
shape and asset-standard rules below are proposals, not constraints."
|
||||
2. `/art-bible` is offered once, as optional
|
||||
3. No profile found → `AskUserQuestion`: "No profile found for **hero**. Describe it
|
||||
briefly" with Describe / Skip / Stop options
|
||||
4. Solo mode: no `Agent` calls; the output announces "art-director and
|
||||
technical-artist skipped — Solo mode: specs derived in this session; technical
|
||||
constraints not validated."
|
||||
5. No gate IDs appear and `/gate-check` is not invoked
|
||||
|
||||
**Assertions:**
|
||||
- [ ] No director gate is invoked
|
||||
- [ ] No gate skip messages appear
|
||||
- [ ] Verdict is COMPLETE without any gate check
|
||||
- [ ] Skill continues without an art bible and says the specs are anchored to the brief
|
||||
- [ ] Missing profile triggers the "Describe it briefly" question rather than a failure
|
||||
- [ ] No `art-director` or `technical-artist` is spawned
|
||||
- [ ] Both skipped agents are named in the output, which says technical constraints were not validated
|
||||
- [ ] If the spec is written, its header names `design/game-brief.md` as the art direction (no `> **Art Bible**:` line), each asset carries a `**Brief anchor:**` line instead of Art Bible Anchors, and no Art Bible section or §8 tier is cited
|
||||
- [ ] No gate IDs appear — the skip note names agents, not gates
|
||||
|
||||
---
|
||||
|
||||
### Case 6: Re-run on an Existing Spec — Updated in place, not overwritten
|
||||
|
||||
**Fixture:**
|
||||
- `project.yaml` sets `modes.rigor: standard`; art bible exists
|
||||
- `design/assets/specs/goblin-enemy-assets.md` exists with `ASSET-001` to
|
||||
`ASSET-004` (idle, walk and attack sprites; portrait); the manifest's highest ID
|
||||
is `ASSET-009`
|
||||
- `design/narrative/characters/goblin-enemy.md` has since gained a charge-attack
|
||||
ability
|
||||
|
||||
**Input:** `/asset-spec character:goblin-enemy`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Phase 1 reads the existing spec file for this target as well as the character doc
|
||||
2. Phase 2 proposes only what is new — the charge-attack sprite and its VFX — and
|
||||
confirms the list with the user
|
||||
3. The new assets are numbered `ASSET-010` and `ASSET-011` (project-wide sequence)
|
||||
4. The skill shows what changes, then asks "May I update
|
||||
`design/assets/specs/goblin-enemy-assets.md`?" — not "May I write"
|
||||
5. `ASSET-001` to `ASSET-004` are kept unchanged in the file; the new blocks are appended
|
||||
|
||||
**Assertions:**
|
||||
- [ ] The existing spec file is detected and read before the asset list is proposed
|
||||
- [ ] The ask is "May I update", naming the existing file
|
||||
- [ ] Existing blocks and IDs are preserved; the file is not overwritten wholesale
|
||||
- [ ] New assets continue the project-wide ID sequence (`ASSET-010`, `ASSET-011`)
|
||||
|
||||
---
|
||||
|
||||
## Protocol Compliance
|
||||
|
||||
- [ ] Reads GDD, art bible, and design system before generating spec
|
||||
- [ ] Includes all 6 spec components (dimensions, animations, palette, style, tech, checklist)
|
||||
- [ ] Flags missing dependencies (art bible, GDD) with DEPENDENCY GAP notes
|
||||
- [ ] Asks "May I write" (or "May I update") per asset
|
||||
- [ ] Handles multiple assets with individual write confirmations
|
||||
- [ ] Verdict is COMPLETE when all approved specs are written
|
||||
- [ ] Reads the art bible, project config and source doc before asking the user anything
|
||||
- [ ] Never specs assets before the user confirms the asset list
|
||||
- [ ] Spawns agents strictly per the resolved review mode (`--review` overrides for one run), and names every skipped agent in the output
|
||||
- [ ] Surfaces any art-director / technical-artist conflict instead of silently resolving it
|
||||
- [ ] Asks "May I write" before a new spec file, "May I update" before changing an existing one, and "May I update" before the manifest
|
||||
- [ ] Assigns asset IDs sequentially across the project, reading the manifest first
|
||||
|
||||
---
|
||||
|
||||
## Coverage Notes
|
||||
|
||||
- Audio asset specs (sound effects, music) follow the same structure with
|
||||
different fields (duration, sample rate, looping) and are not separately tested.
|
||||
- UI asset specs (icons, button states) follow the same flow with interaction
|
||||
state requirements aligned to the UX spec.
|
||||
- The case where GDD is also missing (neither GDD nor art bible exists) is not
|
||||
separately tested; spec would be generated with both dependency gaps flagged.
|
||||
- The no-argument flow (pick the next "Needed" item from
|
||||
`design/assets/entity-inventory.md`, or build the inventory in Phase 0b) is not
|
||||
separately tested.
|
||||
- `level:` targets and full-mode parallel spawning with a surfaced
|
||||
art-director / technical-artist conflict are not separately tested.
|
||||
- Agent BLOCKED handling (Error Recovery Protocol: always produce a partial spec)
|
||||
is not separately tested.
|
||||
|
||||
Reference in New Issue
Block a user