/asset-spec

name: asset-spec
description: "Generate per-asset visual specifications and AI generation prompts from GDDs, level docs, or character profiles. Produces structured spec files and updates the master asset manifest. Run after art bible and GDD/level design are approved, before production begins."
argument-hint: "[system:<name> | level:<name> | character:<name>] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion
model: sonnet

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.

---

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
• All GDDs in `design/gdd/` — extract: Visual/Audio Requirements sections, UI elements mentioned, VFX events, any named entities (characters, enemies, buildings, items)
• `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

**Mode behavior:**

• `full` (default): 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 (Section 8 — dimensions, formats, polycount budgets, texture resolution tiers).

• **Technical preferences**: Read `.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