asset-spec skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,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; automationalwaysask 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 externalcalls is listed in automationalwaysask. (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:

standard headings, and named entities live in the registry:

• design/gdd/systems-index.md — extract every system listed
• GDD asset content — do not full-read every GDD. The two wanted sections are

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 entity:[name] to spec each visual entity

- 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 resolveconfig --keys reviewmode, which applies the full chain and defaults to lean — not 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."

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:

• 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.