Studio

Take any Aseprite request end to end

The other workflows each do one thing well. This one decides which of them the request needs, runs them in the order that keeps mistakes cheap, and owns the result until it is finished. It does not replace them: at every step, read the workflow it names and follow that — do not do the step from memory.

Procedure

1. Pick the Aseprite, then preflight. Two places the work can happen: live, the user's open window, which they watch and can undo; or headless, a batch Aseprite this server runs with no window, where the only results are your look previews and the files you save. Decide before the first call, from the request — see Live or headless below — and pass it: preflight mode="headless" or preflight mode="live". When the request says nothing either way, call preflight without mode and keep the mode the server started in.

   If not ready, stop and tell the user what to fix. Nothing below works without Aseprite, and editing files on disk instead is never an acceptable recovery. In headless there is no window: show previews as you go and save (sprite_manage op save_as) before reporting.

2. Read the room. sprite_info on whatever is open. An open sprite changes the plan: "make it bigger" means a sprite that exists, and its canvas and palette answer questions you would otherwise have to ask.

3. Classify the request against the table below. Most requests are one row; a big one ("animated knight, export for Godot") chains several. Write the chain down before starting — it is the plan you report progress against.

4. Decide once whether to ask. Open-ended requests start with aseprite:brief, which puts every decision to the user in one message. Specific requests ("add a 1px outline", "export this as a GIF") do not — just do them. Never ask more than once per stage: a user who asked for a whole animation does not want to approve every frame.

5. Design before drawing. Anything new — a character, a prop, a scene, an animation — goes through aseprite:concept before a pixel is placed: it writes the art spec (scenario, palette, poses), turns it into a prompt for an image model, and offers the user two ways on: generate a concept sheet or storyboard with that prompt and send it back, or continue without one. That offer rides in the brief's message when there is a brief, so the user still answers once. If they will send references, stop and wait; when the images arrive, aseprite:concept reads them into a PixelSpec and imports them. If the user already supplied reference art, skip the prompt and go straight to reading it.

6. Run the chain. For each stage, read its skill (skill://<name>) and follow it. Hand a stage to a specialist agent when your harness has one (see below) — the agent reads the same rules, so the result is the same whether it runs or you do.

7. Look after every stage that changed pixels. look op preview for the read, op ascii when position matters, op compare when there is a reference. A stage is done when you have seen its result, not when its tool reported success.

8. Get judged by someone who did not draw it. For anything you drew or changed, hand the result to the pixel-critic agent where the harness has one — never grade your own work in place of it; you know what you meant, so you see it. Give it the document name and the brief, nothing about how it was made. Elsewhere, run aseprite:review and do its cold read first.

   The critique decides whether you iterate at all. A draft ships as it is when its critique has no BLOCKING finding and scores 7/10 or more — note its other findings in your report and stop. Below that, or while any BLOCKING finding remains, fix it — at most three fix rounds. Stopping a weak draft only because nothing was marked BLOCKING leaves it weak.

   Each round fixes the BLOCKING findings, or when there are none the one change the critic names as its first fix — never a general polish. A fresh critic always finds something, and each finds something different; polishing on that alone rebuilds parts that already worked. The guards below are what keep a round from doing that:

   • Snapshot before you touch it. export op="png" the current frame (or op="gif" for an animation) to a scratch path, and keep an exact copy of every layer you will change — export op="aseprite" to a scratch path, or the layer's rows from look op="ascii". Restoring means writing those rows back as a grid at the same x/y, or opening the copy and layer op="duplicate" toSprite=<document>.
   • Fix, don't redraw. A fix changes the pixels the finding points at — read that region with look op="ascii", change those rows, write them back as a grid — or recolours a mass that is too dark (recolor). If the round changed more than about a quarter of a layer's opaque pixels, it was a redraw: restore the snapshot and make the smaller fix. Never touch pixels the brief says must stay as they are.
   • Decide by comparison, not by score. Scores from separate critic calls are not on one scale — the same tree drew 5/10 from one critic and 4/10 from the next. After the fix, export the new version next to the snapshot, and give one critic call both images, in an order it cannot read anything into (a.png, b.png, coin-flipped), asking which is the better sprite for the brief and whether the BLOCKING finding is gone. Keep the fix only if it picks the new one; otherwise restore. Two rounds in a row that the comparison rejects end the loop.

   Do not change pixels after the last critique; anything you edit afterwards goes back to the critic. A critique whose cold read did not name your subject is the most important finding you will get: the picture does not say what you think it says. Report each round: the BLOCKING finding, what you changed, and which version the comparison chose.

9. Report in a few lines: what exists now (document, layers, tags, files written), what you decided on the user's behalf, what you compromised on and why — including where the sprite departs from the reference on purpose. Show it — a look preview or the exported file's path, not an adjective.

Live or headless

Read the flags first, then the request. The first row that matches decides.

Strip the flag from the request before reading the rest of it: --headless a knight is a request for a knight.

Then the one rule that matters: the mode is chosen from the request, never from a failure. If live preflight says Aseprite is not attached, do not switch to headless to get the work done anyway — tell the user, and if the work would suit headless, offer it as one question ("Aseprite isn't open — open it, or should I work headless and save the files to …?"). Switch only on their answer. A user who wanted to watch in their window and got files instead has been ignored, and the .aseprite they had open is a file you were never meant to write.

Switching mid-task is allowed when the user asks for it; each side keeps its own documents. Headless refuses to open or save a file the user's window has open (file_open_in_editor) — that refusal is the answer, not an obstacle to route around. Say which mode you used in the report.