asset-spec

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation

If no argument is provided, check whether design/assets/entity-inventory.md exists:

• If it exists: read it, find the first entity or screen with status "Needed" but no spec file yet, and use AskUserQuestion:
  • Prompt: "The next unspecced item is [name]. Generate specs for it?"
  • Options: [A] Yes — spec [name] / [B] Pick a different item / [C] Stop here
• If no entity inventory: check design/assets/asset-manifest.md. If manifest exists, same flow above but reading from manifest.
• If neither exists: start the Entity & Screen Inventory flow (Phase 0b below) rather than failing.

---

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automation_always_ask categories always prompt). Note: actually invoking an external image generator (calling an image API) always prompts regardless of modes.automation — it is an irreversible external action guarded unconditionally, independent of whether external_calls is listed in automation_always_ask. (Today this skill only emits generation-prompt text; the guard applies if live generation is ever wired in.)

Phase 0b: Entity & Screen Inventory (runs when no arguments and no existing inventory)

This flow produces design/assets/entity-inventory.md — the master list of everything the game needs visually. Run once before asset spec work begins.

Step 1 — Gather from docs

Read all available source material in parallel:

• design/gdd/systems-index.md — extract every system listed
• GDD asset content — do not full-read every GDD. The two wanted sections are standard headings, and named entities live in the registry:

  Grep pattern="## (Visual/Audio Requirements|UI Requirements)" glob="design/gdd/*.md" output_mode="content" -A 25
  

  For named entities (characters, enemies, buildings, items), read design/registry/entities.yaml (entities/items) if it exists and has entries; otherwise grep the GDDs for named content. Full-read a GDD only when its Visual/Audio section is missing or reads [To be designed] (Phase 1 already handles that case). VFX events surface in the Visual/Audio grep context.
• design/art/art-bible.md — extract: any named visual categories, asset type expectations
• design/narrative/ — scan for any character or world entity documents if they exist (optional — not required)

Step 2 — Build proposed inventory

Organize everything found into categories:

Characters / Protagonists
Enemies / Creatures
Buildings / Structures
Environment / Terrain
Items / Props
VFX / Particles
UI Screens (list each screen by name)
HUD Elements
Audio (SFX, music — descriptions only, no generation prompts)
Other

For each item, note the source doc it was found in.

Step 3 — Present and collaborate

Present the full proposed inventory to the user in conversation. Then use AskUserQuestion:

• Prompt: "I found [N] visual entities and [N] UI screens across your GDDs and art bible. Review the list — what's missing, what's not needed?"
• Options:
  • [A] Looks good — save this inventory
  • [B] Add items I'll describe
  • [C] Remove items that don't apply
  • [D] Both add and remove — let me edit

If [B] or [D]: ask the user to describe additional items. Accept brief descriptions ("a medieval keep, used as a level background") or detailed ones — either works. Work through them collaboratively until the user is satisfied.

If [C] or [D]: ask which items to remove and why. Remove them from the list.

Step 4 — Write inventory

After user approval, ask: "May I write the entity inventory to design/assets/entity-inventory.md?"

Write the file:

# Visual Entity & Screen Inventory

> Generated: [date]
> Sources: [list of source docs read]

## Entities

| # | Name | Type | Description | Source | Status |
|---|------|------|-------------|--------|--------|
| 1 | [name] | Character / Enemy / Building / Environment / Item / Other | [brief description] | [source doc] | Needed |

## UI Screens

| # | Screen Name | Description | Source | Status |
|---|-------------|-------------|--------|--------|
| 1 | Main Menu | [description] | [source] | Needed |

## HUD Elements

| # | Element | Description | Source | Status |
|---|---------|-------------|--------|--------|

## Audio

| # | Name | Type (SFX / Music / Ambient) | Description | Source | Status |
|---|------|------------------------------|-------------|--------|--------|

After writing, tell the user:

"Entity inventory saved. Next steps:

• Run /ux-design [screen name] for each UI screen in the inventory
• Run /asset-spec system:[name], level:[name] or character:[name] for each visual entity — whichever of the three the entity belongs to
• Or run /asset-spec again to work through the inventory one item at a time"

---

Phase 0: Parse Arguments

Extract:

• Target type: system, level, or character
• Target name: the name after the colon (normalize to kebab-case)
• Review mode: --review [full|lean|solo] if present

The effective mode is the one already resolved at the top of this skill via resolve_config --keys review_mode, which applies the full chain; with nothing set it follows modes.rigor — solo at minimal (the default), lean at standard, full at full. A --review argument overrides it for this run only.

Mode behavior:

• full: spawn both art-director and technical-artist in parallel
• lean: spawn art-director only — faster, skips technical constraint pass
• solo: no agent spawning — main session writes specs from art bible rules alone. Use for simple asset categories or when speed matters more than depth.

---

Phase 1: Gather Context

Read all source material before asking the user anything.

Required reads:

• Art bible: Read design/art/art-bible.md — fail if missing:

  "No art bible found. Run /art-bible first — asset specs are anchored to the art bible's visual rules and asset standards."

  Exception — the minimal path. If there is no art bible but design/game-brief.md exists (at rigor: minimal no art bible is required), do not fail: anchor the specs in the brief's Art & audio direction line, and say so at the top of the output — "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." Offer /art-bible once, as optional. The written spec follows the same anchor: its header reads > **Art direction**: design/game-brief.md (Art & audio direction) — no art bible in place of the > **Art Bible**: line, each asset carries **Brief anchor:** [the brief line applied] in place of the Art Bible Anchors block, and no spec cites an Art Bible section or §8 tier. Extract: Visual Identity Statement, Color System (semantic colors), Shape Language, Asset Standards (art bible Section 8 — dimensions, formats, polycount budgets, texture resolution tiers).

• Project config: Read performance.* and naming.* from project.yaml; for any key absent or empty (including when project.yaml has no performance or naming block), fall back to .claude/docs/technical-preferences.md. Extract performance budgets and naming conventions.

Source doc reads (by target type):

• system: Read design/gdd/[target-name].md. Extract the Visual/Audio Requirements section. If it doesn't exist or reads [To be designed]:

  "The Visual/Audio section of design/gdd/[target-name].md is empty. Either run /design-system [target-name] to complete the GDD, or describe the visual needs manually." Use AskUserQuestion: [A] Describe needs manually / [B] Stop — complete the GDD first

• level: Read design/levels/[target-name].md. Extract art requirements, asset list, VFX needs, and the art-director's production concept specs from Step 4.
• character or entity: Read design/narrative/characters/[target-name].md or search design/narrative/ and design/assets/entity-inventory.md for a matching entry. Extract visual description, role, and any specified distinguishing features.
  • If no source doc exists: do not fail. Instead, use AskUserQuestion:
    • Prompt: "No profile found for [name]. Describe it briefly — a sentence or two is enough."
    • Options: [A] Describe it now / [B] Skip this entity / [C] Stop here
    • If [A]: the user's description becomes the source. Brief answers produce concise specs; detailed answers produce detailed specs. Accept whatever level of detail the user provides and work from it.

Optional reads:

• This target's existing spec: if design/assets/specs/[target-name]-assets.md exists, read it — this is a re-run, and Phase 2 proposes only what is new or changed since (Phase 5 updates the file in place).
• Existing manifest: Read design/assets/asset-manifest.md if it exists — extract already-specced assets for this target to avoid duplicates.
• Related specs: Glob design/assets/specs/*.md — scan for assets that could be shared (e.g., a common UI element specced for one system might apply here too).

Present context summary:

Asset Spec: [Target Type] — [Target Name]

• Source doc: [path] — [N] asset types identified
• Art bible: found — Asset Standards at Section 8
• Existing specs for this target: [N already specced / none]
• Shared assets found in other specs: [list or "none"]

---

Phase 2: Asset Identification

From the source doc, extract every asset type mentioned — explicit and implied.

For systems: look for VFX events, sprite references, UI elements, audio triggers, particle effects, icon needs, and any "visual feedback" language.

For levels: look for unique environment props, atmospheric VFX, lighting setups, ambient audio, skybox/background, and any area-specific materials.

For characters: look for sprite sheets (idle, walk, attack, death), portrait/avatar, VFX attached to abilities, UI representation (icon, health bar skin).

Group assets into categories:

• Sprite / 2D Art — character sprites, UI icons, tile sheets
• VFX / Particles — hit effects, ambient particles, screen effects
• Environment — props, tiles, backgrounds, skyboxes
• UI — HUD elements, menu art, fonts (if custom)
• Audio — SFX, music tracks, ambient loops (note: audio specs are descriptions only — no generation prompts)
• 3D Assets — meshes, materials (if applicable per engine)

Present the full identified list to the user. Use AskUserQuestion:

• Prompt: "I identified [N] assets across [N] categories for [target]. Review before speccing:"
• Show the grouped list in conversation text first
• Options: [A] Proceed — spec all of these / [B] Remove some assets / [C] Add assets I didn't catch / [D] Adjust categories

Do NOT proceed to Phase 3 without user confirmation of the asset list.

---

Phase 3: Spec Generation

Spawn specialist agents based on review mode. Issue all Agent calls simultaneously — do not wait for one before starting the next.

Full mode — spawn in parallel:

art-director via Agent:

• Provide: full asset list from Phase 2, art bible Visual Identity Statement, Color System, Shape Language, the source doc's visual requirements, and any reference games/art mentioned in the art bible Section 9
• Ask: "For each asset in this list, produce: (1) a 2–3 sentence visual description anchored to the art bible's shape language and color system — be specific enough that two different artists would produce consistent results; (2) a generation prompt ready for use with AI image tools (Midjourney/Stable Diffusion style — include style keywords, composition, color palette anchors, negative prompts); (3) which art bible rules directly govern this asset (cite by section). For audio assets, describe the sonic character instead of a generation prompt."

technical-artist via Agent:

• Provide: full asset list, art bible Asset Standards (Section 8), performance budgets (performance.* from project.yaml, else technical-preferences.md), engine name and version
• Ask: "For each asset in this list, specify: (1) exact dimensions or polycount (match the art bible Asset Standards tiers — do not invent new sizes); (2) file format and export settings; (3) naming convention (naming.* from project.yaml, else technical-preferences.md); (4) any engine-specific constraints this asset type must respect; (5) LOD requirements if applicable. Flag any asset type where the art bible's preferred standard conflicts with the engine's constraints."

Lean mode — spawn art-director only (skip technical-artist).

Solo mode — skip both. Derive specs from art bible rules alone, noting that technical constraints were not validated.

Announce every skipped agent by name in the output, before the specs: "technical-artist skipped — Lean mode: technical constraints not validated." / "art-director and technical-artist skipped — Solo mode: specs derived in this session; technical constraints not validated." A spec drafted without an agent must not read like one an agent reviewed.

Collect both responses before Phase 4. If any conflict exists between art-director and technical-artist (e.g., art-director specifies 4K textures but technical-artist flags the engine budget requires 512px), surface it explicitly — do NOT silently resolve.

---

Phase 4: Compile and Review

Combine the agent outputs into a draft spec per asset. Present all specs in conversation text using this format:

## ASSET-[NNN] — [Asset Name]

| Field | Value |
|-------|-------|
| Category | [Sprite / VFX / Environment / UI / Audio / 3D] |
| Dimensions | [e.g. 256×256px, 4-frame sprite sheet] |
| Format | [PNG / SVG / WAV / etc.] |
| Naming | [e.g. vfx_frost_hit_01.png] |
| Polycount | [if 3D — e.g. <800 tris] |
| Texture Res | [e.g. 512px — matches Art Bible §8 Tier 2] |

**Visual Description:**
[2–3 sentences. Specific enough for two artists to produce consistent results.]

**Art Bible Anchors:**
- §3 Shape Language: [relevant rule applied]
- §4 Color System: [color role — e.g. "uses Threat Blue per semantic color rules"]

**Generation Prompt:**
[Ready-to-use prompt. Include: style keywords, composition notes, color palette anchors, lighting direction, negative prompts.]

**Status:** Needed

After presenting all specs, use AskUserQuestion:

• Prompt: "Asset specs for [target] — [N] assets. Review complete?"
• Options: [A] Approve all — write to file / [B] Revise a specific asset / [C] Regenerate with different direction

If [B]: ask which asset and what to change. Revise inline and re-present. Do NOT re-spawn agents for minor text revisions — only re-spawn if the visual direction itself needs to change.

If [C]: ask what direction to change. Re-spawn the relevant agent with the updated brief.

---

Phase 5: Write Spec File

After approval, ask: "May I write the spec to design/assets/specs/[target-name]-assets.md?"

If that file already exists (a re-run for the same target), update it in place — never overwrite it wholesale. Keep its existing ASSET-NNN blocks and IDs, apply only the changes the user approved, and append new assets with the next project-wide IDs. Show what changes, then ask "May I update design/assets/specs/[target-name]-assets.md?" instead of "May I write".

Write the file with:

# Asset Specs — [Target Type]: [Target Name]

> **Source**: [path to source GDD/level/character doc]
> **Art Bible**: design/art/art-bible.md
> **Generated**: [date]
> **Status**: [N] assets specced / [N] approved / [N] in production / [N] done

[all asset specs in ASSET-NNN format]

Then update design/assets/asset-manifest.md. If it doesn't exist, create it:

# Asset Manifest

> Last updated: [date]

## Progress Summary

| Total | Needed | In Progress | Done | Approved |
|-------|--------|-------------|------|----------|
| [N] | [N] | [N] | [N] | [N] |

## Assets by Context

### [Target Type]: [Target Name]
| Asset ID | Name | Category | Status | Spec File |
|----------|------|----------|--------|-----------|
| ASSET-001 | [name] | [category] | Needed | design/assets/specs/[target]-assets.md |

If the manifest already exists, append the new context block — on a re-run for this target, add the new rows to its existing block instead of appending a second one — and update the Progress Summary counts.

Ask: "May I update design/assets/asset-manifest.md?"

---

Phase 6: Close

Use AskUserQuestion:

• Prompt: "Asset specs complete for [target]. What's next?"
• Options:
  • [A] Spec another system — /asset-spec system:[next-system]
  • [B] Spec a level — /asset-spec level:[level-name]
  • [C] Spec a character — /asset-spec character:[character-name]
  • [D] Run /asset-audit — validate delivered assets against specs
  • [E] Stop here

---

Asset ID Assignment

Asset IDs are assigned sequentially across the entire project — not per-context. Read the manifest before assigning IDs to find the current highest number:

Grep pattern="ASSET-" path="design/assets/asset-manifest.md"

Start new assets from ASSET-[highest + 1]. This ensures IDs are stable and unique across the whole project.

If no manifest exists yet, start from ASSET-001.

---

Shared Asset Protocol

Before speccing an asset, check if an equivalent already exists in another context's spec:

• Common UI elements (health bars, score displays) are often shared across systems
• Generic environment props may appear in multiple levels
• Character VFX (hit sparks, death effects) may reuse a base spec with color variants

If a match is found: reference the existing ASSET-ID rather than creating a duplicate. Note the shared usage in the manifest's referenced-by column.

"ASSET-012 (Generic Hit Spark) already specced for Combat system. Reusing for Tower Defense — adding tower-defense to referenced-by."

---

Error Recovery Protocol

If any spawned agent returns BLOCKED or cannot complete:

1. Surface immediately: "[AgentName]: BLOCKED — [reason]"
2. In lean mode or if technical-artist blocks: proceed with art-director output only — note that technical constraints were not validated
3. In solo mode or if art-director blocks: derive descriptions from art bible rules — flag as "Art director not consulted — verify against art bible before production"
4. Always produce a partial spec — never discard work because one agent blocked

---

Collaborative Protocol

Applies in collaborative mode (the default). For guided and autonomous modes, see .claude/docs/automation-modes.md — the rules below describe what collaborative mode requires, not universal behavior.

Every phase follows: Identify → Confirm → Generate → Review → Approve → Write

• Never spec assets without first confirming the asset list with the user
• Always anchor specs to the art bible — a spec that contradicts the art bible is wrong
• Surface all agent disagreements — do not silently pick one
• Write the spec file only after explicit approval
• Update the manifest immediately after writing the spec

---

Recommended Next Steps

• Run /asset-spec [next-context] to continue speccing remaining systems, levels, or characters
• Run /asset-audit to validate delivered assets against the written specs and identify gaps or mismatches