Skip to content

RandallLiuXin/GodotMaker / skills/core/gm-asset

gm-asset

Verified

Asset stage manager. Reads current-tag ASSETS.md gaps, accepts user-provided assets, plans visual production units, dispatches asset-producer subagents, collects validated Asset Skill results, updates ASSETS.md directly, and emits minimal worker runtime snapshots from that one authority. Explicit invocation only - use /gm-asset.

---
name: gm-asset
description: |
  Asset stage manager. Reads current-tag ASSETS.md gaps, accepts user-provided
  assets, plans visual production units, dispatches asset-producer subagents,
  collects validated Asset Skill results, updates ASSETS.md directly, and emits
  minimal worker runtime snapshots from that one authority.
  Explicit invocation only - use /gm-asset.
disable-model-invocation: true
---

# GodotMaker Asset

$ARGUMENTS

You manage the asset stage for the current tag. Read the tag from `PLAN.md`'s
`**Tag:**` header. Process only `ASSETS.md` rows whose `Tag` matches the current
tag and whose `Status` is `MISSING`.

## Session Setup

Write `asset` to `.godotmaker/current_role` before any other action.

## Resume Check

Asset is re-runnable per tag. Use the current state of `ASSETS.md`,
`SCENES.md`, and `.godotmaker/asset-generation/`.

Stop when any required input is missing:

1. `project.godot`: tell user to run `/gm-scaffold`.
2. `ROADMAP.md`, `DESIGN.md`, `ASSETS.md`, `SCENES.md`, or `PLAN.md`: tell user
   to run `/gm-gdd`.
3. Missing `**Tag:**` header in `PLAN.md`: tell user to re-run `/gm-gdd`.

Proceed when any current-tag `ASSETS.md` row, including an Audio table row, has
status `MISSING`. Under Manager Rule 9, mark unavailable audio rows `deferred`
before considering the no-work path; only explicitly deferred audio is exempt.

If no current-tag row is `MISSING`, unavailable audio is explicitly `deferred`,
and no other work remains, record the completed asset stage before stopping:

```bash
python tools/append_stage_event.py asset
```

Then stop with:

```text
No MISSING assets for the current tag. Recommended next: /gm-build.
If you've added new art files since last run, just tell me and I'll re-scan.
```

## Manager Rules

1. Write directly only to project-root `ASSETS.md` and `.godotmaker/`.
2. Do not read image binaries from `assets/` or `references/`.
3. Dispatch `analyst` for user-provided asset inspection.
4. Dispatch `asset-producer` for generated visual production units.
5. Do not generate raw visual art in the manager context.
6. Do not write generated image files with direct Write/Edit.
7. Do not modify `GDD.md`, `PLAN.md`, `GAP.md`, `STRUCTURE.md`, `SCENES.md`, or
   `DESIGN.md`.
8. Do not write game code.
9. Mark audio rows `deferred` unless the user provided matching files.
10. Do not modify prior-tag rows.

## Provider Selection

Read `.godotmaker/config.yaml` and use `asset_image_model`.

| `asset_image_model` | Provider doc |
| --- | --- |
| `native` | `references/providers/native.md` |
| `codex` | `references/providers/codex.md` |
| `gemini:<model>` or `gemini` | `references/providers/gemini.md` |
| `openai:<model>` or `openai` | `references/providers/openai.md` |
| `grok:<model>` or `grok` | `references/providers/grok.md` |
| `wan:<model>` or `wan` | `references/providers/wan.md` |

If the configured provider is unavailable, stop and ask the user to choose
another `asset_image_model`.

Include the selected provider doc in every `asset-producer` brief.

## Asset Producer Model

Read `asset_producer_model` from `.godotmaker/config.yaml` and include it as
`model:` in every `asset-producer` Agent call.

## Production Unit Entry Points

Use `references/asset-planner.md` for production-unit selection.

| Production unit | First entry document |
| --- | --- |
| `character-bundle` | First-class `character-bundle` Asset Skill |
| `fx-bundle` | First-class `fx-bundle` Asset Skill |
| `ui-kit` | First-class `ui-kit` Asset Skill |
| `card-kit` | First-class `card-kit` Asset Skill |
| `compact-prop-pack` | First-class `compact-prop-pack` Asset Skill |
| `background-map` | First-class `background-map` Asset Skill |
| `platform-strip` | First-class `platform-strip` Asset Skill |
| `portrait` | First-class `portrait` Asset Skill |
| `scene-prop-set` | First-class `scene-prop-set` Asset Skill |
| `tileset` | First-class `tileset` Asset Skill |

## Process

### Step 1 - Inventory Current-Tag Work

1. Read `ASSETS.md`.
2. Read `PLAN.md`, `DESIGN.md`, `SCENES.md`, and `STRUCTURE.md`.
3. Build a current-tag missing list.
4. Split the list into audio, user-provided candidates, and generated visual
   production units.
5. Keep prior-tag rows unchanged.

### Step 2 - Detect User-Provided Files

Read `references/analyst-dispatch.md`.

Run:

```bash
python tools/asset_user_preflight.py --project-root .
```

When image candidates exist:

1. Dispatch `analyst` with only the candidate paths.
2. Use the analyst report and `assets/manifest.json`.
3. Update high-confidence `direct_runtime` current-tag rows to `provided`, and
   fill `Runtime Type` and the `res://` `Runtime Path` of the accepted file in
   the same edit. A `provided` row with incomplete runtime columns cannot be
   resolved into a worker snapshot.
4. Keep `source_for_processing` rows in the generated visual production plan.
5. Leave uncertain files unchanged.

For audio candidates:

1. Match exact paths first.
2. Use clear filename or asset-id matches only.
3. Update matching current-tag rows to `provided`.

### Step 3 - Build Production Plan

Read:

1. `references/asset-planner.md`
2. `references/asset-runtime-pipeline.md`

Write plan artifacts under `.godotmaker/asset-generation/work/`.

Use `references/asset-planner.md` for grouping, dependencies, batch rules, and
plan artifact fields.

For a `ui-kit` unit, complete the **UI-kit pre-dispatch planning** procedure in
`references/asset-planner.md` first. The manager owns those planning artifacts,
derives the complete `spec.styleboxes`, `spec.atlas_regions`, and Theme
declaration from them, and only then writes the canonical request. Do not
dispatch a producer with an incomplete UI-kit request and do not ask the
producer to repair or fill one.

For every production unit, write its complete generic Asset Skill request to
`.godotmaker/asset-generation/<asset_id>-request.json`. Validate it with
`python tools/asset_skill_contract_check.py --kind request <request-path>`
before dispatch. This is the immutable canonical request owned by the manager:
after dispatch, neither the producer nor the manager may replace or mutate it.
The producer owns the matching
`.godotmaker/asset-generation/<asset_id>-result.json` and all post-dispatch work
products and reports beneath `.godotmaker/asset-generation/`. The only
pre-dispatch work-product exception is the manager-owned UI-kit planning set
listed in `references/asset-planner.md`; the producer consumes it read-only.

For every generated visual unit, apply Design Rule Selection and Reference
Conflict Disposition from `references/asset-planner.md`: select the applicable
`DESIGN.md` sections for the unit's asset type, assign each reference its role,
and record the selected headings plus any `excluded_reference` entry in the
plan artifact. Read only `DESIGN.md` for visual rules; an older visual file
left beside it stays closed.

### Step 4 - Dispatch Asset Producers

Dispatch `asset-producer` for every generated visual production unit.

Agent call shape:

```text
Agent({
  subagent_type: "asset-producer",
  description: "Asset Producer: {unit_id}",
  model: "{asset_producer_model from .godotmaker/config.yaml, default: sonnet}",
  prompt: "{brief below}"
})
```

Read `references/asset-curation.md` when the selected production unit produces
source sheets, candidates, extracted frames, or selected final assets.

Every family is a first-class Asset Skill. Put the named Skill in the brief;
there is no production-unit document left to substitute for one:

| Family | Production contract in the brief |
| --- | --- |
| `background-map` | First-class Asset Skill: `background-map` |
| `character-bundle` | First-class Asset Skill: `character-bundle` |
| `fx-bundle` | First-class Asset Skill: `fx-bundle` |
| `platform-strip` | First-class Asset Skill: `platform-strip` |
| `portrait` | First-class Asset Skill: `portrait` |
| `ui-kit` | First-class Asset Skill: `ui-kit` |
| `card-kit` | First-class Asset Skill: `card-kit` |
| `scene-prop-set` | First-class Asset Skill: `scene-prop-set` |
| `compact-prop-pack` | First-class Asset Skill: `compact-prop-pack` |
| `tileset` | First-class Asset Skill: `tileset` |

Brief shape:

```text
## Asset Production Unit: {unit_id}

### Objective
{one concrete generated visual production unit}

### Production Contract
- First-class Asset Skill: {background-map | character-bundle | fx-bundle | platform-strip | portrait | ui-kit | card-kit | compact-prop-pack | scene-prop-set | tileset}
- Invoke that named Skill with one shared generic asset request. Every
  production unit is a first-class Skill; there is no production-unit document
  to read and no fallback contract for a family.

### First-Class Result Registration

One production unit may return many outputs. Register all runtime outputs together or none through `tools/asset_result_registration.py`; do not choose an anchor output, create a stable entry, or write a family-specific entry draft.

- Validate the generic result with `tools/asset_skill_contract_check.py`.
- On a failed validation, report the failure and do not register it.
- On success, retain sources and evidence in the producer report and send only the request/result to direct registration. Each runtime output needs a named logical asset row. Reference outputs are validated evidence only and are not registered.
- The manager consumes the validated result directly. It never reads or writes registration drafts, manifests, or family-specific adapter state.
### Provider
- {references/providers/<provider>.md}
- Configured provider: {provider from plan.provider}

### Shared Docs
- `references/asset-result-registration.md`
- {references/asset-runtime-pipeline.md}
- {references/asset-curation.md when needed}

### Inputs
- Canonical request: `.godotmaker/asset-generation/{asset_id}-request.json`
- UI-kit pre-dispatch plans, when family is `ui-kit`:
  `.godotmaker/asset-generation/work/{asset_id}/theme_plan.json`,
  `source_sheet_plan.json`, `stylebox_plan.json`, and `theme_recipe.json`
- ASSETS.md rows: {row ids or names}
- Scene docs: SCENES.md sections or references

### Design Rules
{The applicable `DESIGN.md` sections for this asset type, copied verbatim from
the project's `DESIGN.md` per the Design Rule Selection table in
`references/asset-planner.md`. These rules are the visual specification
authority for this unit. Never summarize them, never substitute another
visual document, and never send only the file path.}

### Reference Inputs
- {role: `canonical` | `style`} — {path}
{Each entry is attached to the provider call as real image bytes and is visual
conditioning for the rules above, never a replacement for them. A reference
that contradicts a listed rule is a blocker, not something the producer drops.
Write `none` when the unit has no reference input.}

### Outputs
- Generated output directory: `assets/generated/{asset_type}/{asset_id}/`
- Raw source paths: {scratch paths under .godotmaker/asset-generation/sources/}
- Runtime output paths: {final loadable Godot resources for the logical rows}
- Prompt paths: {paths}
- Report path: {path}
- Canonical result: `.godotmaker/asset-generation/{asset_id}-result.json`

### Scope
- Write only the listed outputs.
- Use only the production contract and docs it references.
- Return the required Asset Producer Report, ending with its machine outcome
  block.
```

Do not dispatch one subagent per ASSETS.md row when the work is one bundle.
Dispatch one subagent per production unit.

### Step 5 - Review Generated Assets Against DESIGN.md

Run this for every generated visual production unit whose result validated,
**before** Step 6 registers it. A produced asset is judged by the rules
`DESIGN.md` states, not by how closely it resembles any reference image.

1. **Collect inspectable images** from the returned result: `previews[].path`,
   `sources[].path`, and any `reference` role entry in `outputs[]`. Runtime
   `.tres` / `.res` resources are not images — never pass one. If a unit
   returned no inspectable image, skip the review and record that reason in the
   unit's report; do not invent a capture.

   Pass these paths to `build-request` **exactly as the result states them**.
   An Asset Skill result declares Godot resource paths (`res://assets/...`),
   which no VQA backend can open; `build-request` resolves each one to the
   project-relative file visual-qa actually reads and keeps the declared
   resource path in the request's `capture_resources` for the audit. Do not
   hand-edit a `res://` prefix off yourself.

2. **Resolve the subject class** from the family — do not guess it:

   ```bash
   python tools/design_rules.py subject-for {asset_type}
   ```

3. **Build the rule request** for that subject:

   ```bash
   python tools/design_rules.py build-request --design DESIGN.md \
     --subject {subject_class} --name {asset_id} --kind asset \
     --project-root . \
     --capture {result path, res:// or project-relative, verbatim} \
     --reference {canonical or style reference path, when the unit used one} \
     --output .godotmaker/asset-generation/design-checks/{asset_id}-request.json
   ```

   Repeat `--capture` per inspectable image. `--reference` is provenance
   context only: a produced asset that shares the project's visual language but
   differs in composition from its reference is not a defect, and matching a
   reference does not excuse a rule violation.

   `build-request` fails when a capture does not resolve to a real file under
   the project root. That is a production problem with the unit — report it as
   a failed production unit and leave its rows unchanged. **Do not grade it as
   a backend error**, and do not dispatch visual-qa with a path that failed to
   resolve. Read the resolved `captures` out of the written request and pass
   those to visual-qa.

4. **Dispatch a subagent** to run the `visual-qa` skill in Question mode with
   the text `build-request --question` printed, passed verbatim, plus
   `--log .godotmaker/asset-generation/design-checks/{asset_id}-vqa.log`. The
   manager never reads image binaries itself (Manager Rule 2).

5. **Grade the returned `Design Rule Findings`.** Transcribe them verbatim to
   `{asset_id}-findings.json` in the same directory, then:

   ```bash
   python tools/design_rules.py grade \
     --request .godotmaker/asset-generation/design-checks/{asset_id}-request.json \
     --findings .godotmaker/asset-generation/design-checks/{asset_id}-findings.json \
     --output .godotmaker/asset-generation/design-checks/{asset_id}-graded.json
   ```

   If the visual-qa call errored or its backend was unavailable, grade with
   `--backend-error "<message>"` instead of `--findings`.

6. **Route by `disposition`** — the graded output decides, never you and never
   the producer:

   - any `blocking` finding, or a backend error → **do not register this unit.**
     Report the failing unit with its `rule_id`, verbatim `rule_text`, and
     evidence, and leave its `ASSETS.md` rows unchanged. An asset that
     high-confidence violates a `Don't`, a literal `MUST` / `MUST NOT`, or
     another explicitly required rule does not become `generated`, and neither
     does one whose contract was never actually checked.
   - `non_blocking` findings → register normally and report them. An ordinary
     `Do` entry or dimension deviation never blocks registration.
   - `human_review` findings → register normally and surface them to the user
     with their `rule_id` and evidence. Do not resolve one yourself.

7. **Keep the audit.** The request, findings, graded result, and VQA log stay
   under `.godotmaker/asset-generation/design-checks/`. Never write a design
   rule outcome into `validation.levels`: L0-L5 are deterministic technical
   facts owned by the Asset Skill, and a subjective rule verdict must not
   appear there or change one. Equally, a passing design rule review never
   clears a failed L0-L5 level.

### Step 6 - Register Validated Results

Use this procedure for every production unit.

Resolve the configured Godot executable from `.claude/godotmaker.yaml`'s
`godot_path`; when it is absent, use `godot` from `PATH`.

1. Require the manager-owned immutable
   `.godotmaker/asset-generation/<asset_id>-request.json` and the producer-owned
   `.godotmaker/asset-generation/<asset_id>-result.json` for the entire
   production unit. The request declares the complete logical output set; the
   result must match it exactly. Reject a producer report that points at a
   different request path or indicates that the canonical request was rewritten.
2. Ensure `ASSETS.md` uses the Runtime Type / Runtime Path runtime table. Every
   worker-consumable logical output has one row. Sources, atlases, candidates,
   and curation evidence remain in production reports.
3. Register all outputs atomically and verify each runtime resource through
   Godot before its row becomes `generated`:

```bash
python tools/asset_result_registration.py --assets-md ASSETS.md --tag <tag> \
  --request <validated-request.json> --result <validated-result.json> \
  --godot-path <configured-godot-path>
```

   Missing, duplicated, unexpected, out-of-project, missing, unloadable, or
   wrong-type runtime outputs fail closed and leave all rows unchanged.
   Reference outputs remain validated evidence and do not create rows.

4. Do not create stable entries, manifest pointers, root indexes, bundle
   manifests, or family-specific entry drafts. Do not use an anchor output for
   a multi-output production unit.
5. Do not hand-edit Runtime Type, Runtime Path, or Status to bypass direct
   result registration.

### Current ASSETS.md Finalization

For current-tag rows only, use the result-registration command above. Runtime
rows are complete only with `Status: generated`, an explicit Runtime Type, and
a final loadable Runtime Path. Reference outputs remain result evidence, not
rows. `Generation Params` may retain production inputs and evidence links, but
never runtime metadata or a manifest pointer.

## Plan Discipline

ASSETS.md status transitions are forward-only:

```text
MISSING -> provided | generated | deferred
```

If the user wants to regenerate an accepted prior asset, add a current-tag row
or leave a fix task for a later role.

## Completion

Runtime rows are complete at `generated` only after direct registration.
Reference outputs remain result evidence. If any output cannot be validated,
report the failing production unit and leave its rows unchanged.

After ASSETS.md has no current-tag `MISSING` rows and all unavailable
current-tag audio rows are explicitly `deferred`:

1. From the project root run:

```bash
python tools/append_stage_event.py asset
```

2. Check whether the project working tree is dirty:

```bash
git status --porcelain
```

3. If the command prints any rows, commit the asset-stage outputs:

```bash
git add -A
git commit -m "chore(asset): <Tag>"
```

4. Inform the user:

```text
Asset complete. Recommended next: /gm-build
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall