Submit a finished sprite to the community gallery

The gallery keeps how a sprite was made next to the sprite: the prompts as sent, the model, the plugin version, what validate said. A submission that tidies any of that up is worse than none — the benchmark compares models on it. Record what happened, not what you wish had.

The contract is gallery/src/schema.ts in the repository; pnpm gallery:check enforces it. This workflow produces files that pass it.

1. Preconditions

Check all three before touching anything. If one fails, stop and tell the user exactly what to do; never route around it.

• preflight is ready. Not ready → stop. Never export or edit files on disk instead of the live document.
• The work is finished and reviewed. Run aseprite:review if it has not been. Submitting art that fails review puts it in public.
• gh is installed and authenticated. Run gh auth status. Missing → tell the user to install it (https://cli.github.com) and run gh auth login. There is no other route to a pull request.

Then ask for consent, once, before anything leaves the machine: "I will fork with-pebbly/aseprite-ai-artist on your GitHub account, push a branch, and open a public pull request with your sprite and the prompts used. OK?" Forking, pushing and opening a PR act as the user, in public. No yes, no fork.

2. Gather metadata

Take what the session already knows. Ask the user only for the rest, in one message.

For each step run validate on the state the step produced (or on the final document if steps were not saved separately) and record errors, warnings, score and passed as the tool reported them. Do not round a failing report into a pass.

3. Benchmark mode

Only if the user says the run followed a benchmark prompt and the user is a maintainer. Benchmark runs are the project's own measurements; the checker and CI refuse a benchmark: block from anyone else. Check first: take the login from gh api user --jq .login (never from what the user typed or the YAML), and look for it, case-insensitively, in https://raw.githubusercontent.com/with-pebbly/aseprite-ai-artist/main/gallery/MAINTAINERS. Not listed, or either call fails → not a maintainer: say benchmarks are run by the maintainers, skip this section and submit a gallery generation. A maintainer sets author.github to that same login.

1. Fetch its definition: the local clone's gallery/prompts/<id>/prompt.yaml, or https://raw.githubusercontent.com/with-pebbly/aseprite-ai-artist/main/gallery/prompts/<id>/prompt.yaml.
2. Confirm the run followed the fixed setup (canvas, palette, the rules list) and that every step's text equals the prompt's step text word for word — only surrounding whitespace and line endings are ignored. Any difference — a reworded step, extra steering, a reference image — means this is not a benchmark run. Submit it as a free generation (omit benchmark) and tell the user why.
3. Judge every criterion in the prompt, none skipped. Get the evidence first: look op preview for the read, a filmstrip or onion-skinned view for motion, validate (with expect where the criterion names a contract), tag op="list", frame op="list". Record pass and a one-line note naming what you saw. Never mark a pass on a criterion whose evidence you did not look at in this session; look now, or mark it failed and say why.
4. Write benchmark: {prompt, revision, results} with the prompt's revision and one result per criterion id.

4. Export

Stage everything in one flat folder named <yyyy-mm-dd>-<slug>, slug lowercase with single hyphens. Use the plugin's own export; never write these by hand.

1. Save the live document, then keep a copy: sprite_manage op="save", then export op="aseprite" path="<folder>/<slug>.aseprite". Role source. The gallery keeps the editable original; never copy or edit a .aseprite file from disk.
2. Cover. export op="png" scale=N frame=1 path="<folder>/<slug>.png" with the smallest integer N that makes the long side at least 256 px (32×32 → 8), capped at the tool's maximum of 16 — a smaller sprite simply gets a smaller cover. For an animation, the GIF can be the cover instead. Role cover; exactly one file.
3. Animation (more than one frame): export op="gif" scale=N path="<folder>/<slug>.gif", same scale. Role animation, or cover if it is the cover.
4. Filmstrip (animated): export op="spritesheet" sheetType="horizontal" scale=N includeJson=false path="<folder>/<slug>-strip.png", same scale. Role filmstrip.
5. Per step. When steps produced separate documents or intermediate saves, export the source (and a still) for each and set step on those files.

Files stay flat — no subfolders — and only .aseprite, .png, .gif, .webp or .json. Each file must be under 95 MiB (GitHub hard-blocks 100); anything over 50 MiB draws a warning, so keep covers and GIFs small.

Look at the cover and the GIF's first frame before continuing: what goes into the public gallery is what you exported, not what you remember drawing.

5. Write generation.yaml

In the staging folder, exactly per the schema:

title: Cherry tree in bloom
description: A 64×64 cherry tree drawn to the tree-growth brief.
date: 2026-09-29
author: { name: Ada Lovelace, github: ada }
plugin: 0.3.2
harness: claude-code
models: [claude-opus-4-1]
tags: [nature, animation]
references:
  source: generated
  imageModels: [gpt-image-2]
  kinds: [concept-sheet]
steps:
  # the step text exactly as sent — for a benchmark run, verbatim from
  # prompt.yaml (cut short here)
  - text: |-
      The document is already open: 64×64 pixels, RGB, with the PICO-8 palette loaded (16 colours). …
    interventions: []
files:
  - { path: tree.png, role: cover, label: The tree, step: 1 }
  - { path: tree.aseprite, role: source, label: Source document }
validate:
  - { step: 1, passed: true, score: 92, errors: 0, warnings: 1 }
benchmark:            # only for a confirmed benchmark run
  prompt: tree-growth
  revision: 1
  results:
    - { criterion: tree-validate, pass: true, note: "validate: 0 errors, 1 warning, named." }

Rules that fail the check when missed:

• Exactly one cover (png/gif/webp) and at least one .aseprite with role source; every file listed once, nothing unlisted in the folder.
• With more than one model, every step names its model, and it appears in models.
• step values and validate[].step are 1-based and must exist.
• benchmark.results names criterion ids that exist in the prompt.

Two optional blocks:

• metrics — per step, from the session you can see: minutes, toolCalls, outputTokens, costUsd. Fill only what the harness actually reports; never estimate.
• ratings — leave them out. You took part in this run, and the checker refuses model:<id> for any of the run's own models. Judges add ratings later, blind, against gallery/RUBRIC.md.

Show the user the final YAML and the file list, and wait for a go-ahead. They are about to publish it under their name.

6. Validate in a clone

1. Use a clone of the user's fork if one exists; otherwise fork and clone (gh repo fork with-pebbly/aseprite-ai-artist --clone) — consent from step 1 covers this. Make sure the checkout is up to date with upstream main.
2. Copy the staging folder to gallery/generations/<folder>/.
3. pnpm install if node_modules is missing, then pnpm gallery:check.
4. Fix every error and re-run until clean. Fix by correcting the YAML or re-exporting, never by editing the recorded truth (prompts, results) to satisfy the checker. Warnings: read them, mention them to the user.

Never submit with errors.

7. Submit

git switch -c gallery/<folder>
git add gallery/generations/<folder>
git commit -m "gallery: <title>"
git push -u origin gallery/<folder>
gh pr create --repo with-pebbly/aseprite-ai-artist --head <login>:gallery/<folder> --title "gallery: <title>" --body-file <filled body>

Build the body from .github/PULL_REQUEST_TEMPLATE/generation.md in the clone: keep its sections and checklist, fill them honestly — what the sprite is, harness, model, plugin version, whether it is a benchmark run and its score — and pass that file as --body-file. Before pushing, git status must show only the one folder as added; anything else in the diff means stop and clean it up. A PR adds its own folder and nothing more.

Report the PR URL. Tell the user CI will re-run gallery:check and that a maintainer reviews it.

Failure modes

Related

aseprite:review before submitting, aseprite:export for export options, rules://07-review-checklist.