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.

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:

python tools/append_stage_event.py asset

Then stop with:

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_modelProvider doc
nativereferences/providers/native.md
codexreferences/providers/codex.md
gemini:<model> or geminireferences/providers/gemini.md
openai:<model> or openaireferences/providers/openai.md
grok:<model> or grokreferences/providers/grok.md
wan:<model> or wanreferences/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 unitFirst entry document
character-bundleFirst-class character-bundle Asset Skill
fx-bundleFirst-class fx-bundle Asset Skill
ui-kitFirst-class ui-kit Asset Skill
card-kitFirst-class card-kit Asset Skill
compact-prop-packFirst-class compact-prop-pack Asset Skill
background-mapFirst-class background-map Asset Skill
platform-stripFirst-class platform-strip Asset Skill
portraitFirst-class portrait Asset Skill
scene-prop-setFirst-class scene-prop-set Asset Skill
tilesetFirst-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:

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:

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:

FamilyProduction contract in the brief
background-mapFirst-class Asset Skill: background-map
character-bundleFirst-class Asset Skill: character-bundle
fx-bundleFirst-class Asset Skill: fx-bundle
platform-stripFirst-class Asset Skill: platform-strip
portraitFirst-class Asset Skill: portrait
ui-kitFirst-class Asset Skill: ui-kit
card-kitFirst-class Asset Skill: card-kit
scene-prop-setFirst-class Asset Skill: scene-prop-set
compact-prop-packFirst-class Asset Skill: compact-prop-pack
tilesetFirst-class Asset Skill: tileset

Brief shape:

## 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:

    python tools/design_rules.py subject-for {asset_type}
    
  3. Build the rule request for that subject:

    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:

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

  1. 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.
  2. 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:

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:
python tools/append_stage_event.py asset
  1. Check whether the project working tree is dirty:
git status --porcelain
  1. If the command prints any rows, commit the asset-stage outputs:
git add -A
git commit -m "chore(asset): <Tag>"
  1. Inform the user:
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: 471kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall