asset-spec

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation` # Asset Spec 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: ```markdown # 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`: