Skip to content

0x0funky/agent-sprite-forge / skills/generate2dsprite

generate2dsprite

Verified

Make game-ready 2D characters, creatures, props, icons and FX as master stills, sprite sheets or animation clips. Plan size, motion and finish; generate the art (image generation is the default, through generate2dmedia route_media.py - the API when a key is configured, else the local Codex or Grok CLI); approve one master still per character; then key, slice, register, scale, palette, QA and export frames for a game engine (Aseprite JSON, Godot SpriteFrames or Sprite3D). HD finish by default, pixel finish on request. Character animation is one image-to-video clip per action from the master (video2dsprite); sheets are for FX, icons and props. Use for sprites, masters, sheets, frame-by-frame animation and packaging frames from any source. Not for maps, tiles or backgrounds (generate2dmap), video clips (video2dsprite), code-drawn art (codeart2d, only on request) or calling an image or video API by itself (generate2dmedia).

FileKindSize
SKILL.mdskill md17.1 KB
agents/openai.yamlconfig529 B
references/action-recipes.mdmarkdown13.8 KB
references/animation-planning.mdmarkdown9.1 KB
references/character-animation.mdmarkdown3.9 KB
references/engine-export.mdmarkdown13.7 KB
references/frames-and-clips.mdmarkdown16.2 KB
references/hibit.mdmarkdown7.1 KB
references/master-still.mdmarkdown15.1 KB
references/modes.mdmarkdown6.1 KB
references/palette-and-pixels.mdmarkdown12.0 KB
references/pixel-looks.mdmarkdown20.5 KB
references/processing.mdmarkdown14.2 KB
references/prompt-rules.mdmarkdown9.8 KB
references/runtime-integration.mdmarkdown10.6 KB
references/schemas/common.schema.jsonconfig12.9 KB
references/schemas/host.schema.jsonconfig18.8 KB
references/schemas/sprite.schema.jsonconfig80.7 KB
references/video-handoff.mdmarkdown7.8 KB
scripts/assemble_frames.pyscript51.9 KB
scripts/build_animation_clips.pyscript73.9 KB
scripts/export_engine.pyscript65.1 KB
scripts/forge_core.pyscript86.4 KB
scripts/forge_hibit.pyscript18.8 KB
scripts/forge_index.pyscript24.8 KB
scripts/forge_matte.pyscript71.6 KB
scripts/forge_palette.pyscript70.2 KB
scripts/forge_pixelgrid.pyscript74.0 KB
scripts/fx_pixelfx.pyscript26.0 KB
scripts/generate2dsprite.pyscript135.7 KB
scripts/hibit_fx.pyscript15.8 KB
scripts/make_anchor_layout.pyscript7.3 KB
scripts/make_layout_guide.pyscript6.1 KB
scripts/master_still.pyscript88.0 KB
scripts/palette_tool.pyscript40.6 KB
scripts/pixel_look.pyscript64.9 KB
scripts/pixel_reduce.pyscript15.2 KB
scripts/plan_guide.pyscript32.6 KB
scripts/scale_frames.pyscript37.8 KB
scripts/sheet_qc.pyscript70.3 KB

scripts/plan_guide.py

View on GitHub
#!/usr/bin/env python3
"""Plan a sprite sheet for the host image tool and draw a layout and pose guide (opt-in).

The host image tool keeps the requested aspect and returns about 1,572,864 px
(3:2 -> 1536x1024, 16:9 -> 1672x941, 1:1 -> 1254x1254, 2:1 -> 1774x887), so
prompts should name an aspect, never pixel sizes. This tool predicts that size,
picks rows and columns that give each pose the most room inside a 15% safe
frame, and writes into a new --output-dir:

  guide.png            layout and pose reference to attach to the generation call:
                       grey gutters, blue safe boxes, black ground line, root ticks
                       and, for --cycle run|walk, a NEAR (orange) / FAR (blue) leg
                       skeleton whose leading leg alternates between the halves
  guide.svg            the same drawing as vector art
  guide-annotated.png  the same with phase labels, for people (do not attach)
  prompt.txt           an aspect-only prompt block that explains the guide
  sheet-plan.json      the plan, the candidate layouts and a self-check

The self-check runs sheet_qc's leading-leg test on the guide's own skeleton and
checks that every pose stays inside its safe box; a failure exits 1 and
publishes nothing. Usage errors exit 2 (argparse); every other error prints one
"error: ..." line and exits 1. The guide is a generation aid that has not been A/B tested
with an image model: use it when a sheet keeps crossing cells or repeating the
leading leg, not as a default.

Run from the project root, for example:
  python "<skill-dir>/scripts/plan_guide.py" --frames 8 --cycle run --facing right --output-dir guides/hero-run
"""

from __future__ import annotations

import argparse
import json
import math
import sys
from fractions import Fraction
from pathlib import Path
from typing import Any, Sequence

import numpy as np
from PIL import Image, ImageDraw, ImageFont

sys.path.insert(0, str(Path(__file__).resolve().parent))
import forge_core  # noqa: E402  (this skill's vendored copy)
import sheet_qc  # noqa: E402  (sibling: the leading-leg test used by the self-check)

TOOL = {"name": "plan_guide.py", "version": forge_core.FORGE_PACKAGE_VERSION}  # the package version (D29)
SCHEMA = "generate2dsprite.sheet_plan.v1"
PLAN_NAME = "sheet-plan.json"
HOST_BUDGET_PX = 1536 * 1024  # observed host image area (3 of 3 calls within +-0.031%, report v2 3.3.1)
# Most cells a planned grid may hold: about 39 px per cell on a 1.5-megapixel host image. It bounds --frames and
# the layout search, which spun for minutes on --frames 99999999 (r2-conventions finding 13).
MAX_CELLS = 1024
MAX_BUDGET_PX = 4096 * 4096  # largest host image the guides are drawn for (they are drawn at the predicted size)
STANDARD_ASPECTS = ("3:2", "2:3", "1:1", "16:9", "9:16", "2:1", "1:2")
CYCLES = ("run", "walk", "none")
NEAR = (255, 122, 0)
FAR = (32, 80, 160)
BODY = (110, 110, 110)
GUTTER = (200, 200, 200)
SAFE = (0, 170, 255)
INK = (0, 0, 0)

# Key poses of one half-cycle for a side view facing right. Angles are degrees from straight down,
# positive forward: (thigh, knee bend) for leg A (the contact leg of this half) and leg B. In the
# first half A is NEAR, in the second half A is FAR, so the leading leg alternates.
# Columns: name, A, B, body lift in thigh lengths, A on the ground, B on the ground.
RUN_KEYS = (
    ("contact", (30, 5), (-28, 75), 0.00, True, False),
    ("down", (5, 50), (-10, 110), 0.00, True, False),
    ("passing", (-15, 10), (22, 95), 0.00, True, False),
    ("flight", (-34, 35), (36, 15), 0.14, False, False),
)
WALK_KEYS = (
    ("contact", (24, 4), (-24, 18), 0.00, True, False),
    ("down", (12, 22), (-20, 55), 0.00, True, False),
    ("passing", (-4, 6), (14, 70), 0.00, True, False),
    ("up", (-18, 4), (26, 30), 0.00, True, False),
)
PHASE_TEXT = {
    "contact": "{a} leg reaches forward, heel on the ground line; {b} leg trails{b_lift}",
    "down": "{a} leg under the body, knee bent, carrying the weight; {b} leg folds up behind",
    "passing": "{a} leg pushes off behind; {b} knee swings forward past it",
    "flight": "both feet off the ground; {b} leg reaches forward for the next contact, {a} leg trails",
    "up": "{a} leg straightens under the body (highest hip); {b} foot swings forward, just clear of the ground",
}


class PlanError(ValueError):
    """A user-facing problem, printed as 'error: ...'."""


# --------------------------------------------------------------------------- planning

def parse_aspect(text: str) -> tuple[int, int]:
    """'3:2' -> (3, 2)."""
    try:
        width, height = (int(part) for part in text.split(":"))
    except ValueError:
        raise PlanError(f"Aspects look like 3:2; got {text!r}.") from None
    if width < 1 or height < 1:
        raise PlanError(f"Aspects need positive sides; got {text!r}.")
    return width, height


def parse_ratio(text: str) -> float:
    """'0.98', '384/391' or '4:5' -> width / height."""
    try:
        value = float(Fraction(text.replace(":", "/")))
    except (ValueError, ZeroDivisionError):
        raise PlanError(f"--envelope-aspect is width/height such as 1.0, 384/391 or 4:5; got {text!r}.") from None
    if not 0.1 <= value <= 10:
        raise PlanError(f"--envelope-aspect must be between 0.1 and 10; got {text!r}.")
    return value


def predict_size(aspect: tuple[int, int], budget: int = HOST_BUDGET_PX) -> tuple[int, int]:
    """Host output size for a requested aspect: the aspect is kept and the area is about ``budget`` px."""
    ratio = aspect[0] / aspect[1]
    return forge_core.round_half_up(math.sqrt(budget * ratio)), forge_core.round_half_up(math.sqrt(budget / ratio))


def candidate_layouts(frames: int, aspects: Sequence[str], *, envelope_aspect: float, safe: float,
                      budget: int = HOST_BUDGET_PX, max_empty: int = 1) -> list[dict]:
    """Every rows x cols grid holding ``frames`` poses (at most ``max_empty`` spare cells, at most MAX_CELLS
    cells) for each aspect, largest motion envelope first (report v2 plan_and_guide).

    Only the columns that fit are visited, ceil(frames / rows) up to cells / rows, so the search is
    linear in the cell count instead of quadratic."""
    layouts = []
    cells_max = min(frames + max_empty, MAX_CELLS)
    for order, text in enumerate(aspects):
        aspect = parse_aspect(text)
        width, height = predict_size(aspect, budget)
        for rows in range(1, cells_max + 1):
            for cols in range(-(-frames // rows), cells_max // rows + 1):
                cell_w, cell_h = width / cols, height / rows
                safe_w, safe_h = cell_w * (1 - 2 * safe), cell_h * (1 - 2 * safe)
                envelope_h = min(safe_h, safe_w / envelope_aspect)
                layouts.append({
                    "aspect": text, "predicted_size": [width, height], "rows": rows, "cols": cols,
                    "empty_cells": rows * cols - frames, "cell": [round(cell_w, 1), round(cell_h, 1)],
                    "divides_exactly": width % cols == 0 and height % rows == 0,
                    "safe_box": [round(safe_w, 1), round(safe_h, 1)],
                    "envelope_px": [round(envelope_h * envelope_aspect, 1), round(envelope_h, 1)],
                    "_order": order,
                })
    layouts.sort(key=lambda item: (-item["envelope_px"][1], item["empty_cells"], item["_order"], item["rows"]))
    for item in layouts:
        item.pop("_order")
    return layouts


# --------------------------------------------------------------------------- skeleton

def gait_phases(frames: int, cycle: str) -> list[dict]:
    """Per-frame skeleton parameters: NEAR/FAR thigh and knee angles, lift and ground contacts.

    Each half-cycle samples the four key poses evenly (in-betweens interpolate
    the angles); the second half repeats the first with NEAR and FAR swapped.
    """
    keys = RUN_KEYS if cycle == "run" else WALK_KEYS
    half = frames // 2
    phases = []
    for index in range(frames):
        second = index >= half
        position = (index % half) * len(keys) / half
        low = int(math.floor(position))
        mix = position - low
        start = keys[low]
        if low + 1 < len(keys):
            end, swap = keys[low + 1], False
        else:  # the last key blends into the next half's contact, where A and B trade places
            end, swap = keys[0], True
        a_end, b_end = (end[2], end[1]) if swap else (end[1], end[2])
        a = tuple(start[1][k] + mix * (a_end[k] - start[1][k]) for k in range(2))
        b = tuple(start[2][k] + mix * (b_end[k] - start[2][k]) for k in range(2))
        lift = start[3] + mix * (end[3] - start[3])
        a_down = start[4] if mix < 0.5 else (end[5] if swap else end[4])
        b_down = start[5] if mix < 0.5 else (end[4] if swap else end[5])
        name = start[0] if mix == 0 else f"{start[0]}-{'contact' if swap else end[0]}"
        near_is_a = not second
        phases.append({
            "index": index, "name": name, "half": int(second),
            "near": a if near_is_a else b, "far": b if near_is_a else a, "lift": lift,
            "contact_leg": "near" if near_is_a else "far",
            "ground": {"near": a_down if near_is_a else b_down, "far": b_down if near_is_a else a_down},
        })
    return phases


def _leg(hip: tuple[float, float], thigh_deg: float, knee_deg: float, length: float,
         sign: float) -> list[tuple[float, float]]:
    """Hip, knee, ankle and toe of one leg; the shin bends backward from the thigh."""
    thigh = math.radians(thigh_deg)
    knee = (hip[0] + sign * length * math.sin(thigh), hip[1] + length * math.cos(thigh))
    shin = math.radians(thigh_deg - knee_deg)
    ankle = (knee[0] + sign * length * math.sin(shin), knee[1] + length * math.cos(shin))
    return [hip, knee, ankle, (ankle[0] + sign * 0.35 * length, ankle[1])]


def skeleton(phase: dict, *, keys: Sequence[tuple], root_x: float, ground_y: float, length: float,
             sign: float) -> dict:
    """Polylines of one pose: far leg and arm, body, head, near leg and arm (drawing order).

    The hip sits so the planted foot touches the ground line; with no planted
    foot (flight) it rises ``lift`` thigh lengths above the highest planted hip
    of the cycle's key poses.
    """

    def drop(thigh_knee: Sequence[float]) -> float:
        thigh, knee = (math.radians(value) for value in thigh_knee)
        return length * (math.cos(thigh) + math.cos(thigh - knee))

    planted = [drop(phase[side]) for side in ("near", "far") if phase["ground"][side]]
    standing = max(drop(key[1]) for key in keys if key[4])
    hip_y = ground_y - (max(planted) if planted else standing + phase["lift"] * length)
    hip = (root_x, hip_y)
    neck = (hip[0] + sign * 0.12 * length, hip[1] - 1.55 * length)
    head = (neck[0] + sign * 0.15 * length, neck[1] - 0.55 * length)
    shoulder = (neck[0], neck[1] + 0.25 * length)
    parts: dict[str, Any] = {"head": head, "head_r": 0.5 * length, "body": [hip, neck]}
    for side in ("far", "near"):
        parts[f"{side}_leg"] = _leg(hip, *phase[side], length, sign)
        swing = math.radians(-0.9 * phase[side][0])  # arms counter the leg on the same side
        elbow = (shoulder[0] + sign * 0.75 * length * math.sin(swing), shoulder[1] + 0.75 * length * math.cos(swing))
        hand = (elbow[0] + sign * 0.6 * length * math.sin(swing + math.radians(70)),
                elbow[1] + 0.6 * length * math.cos(swing + math.radians(70)) - 0.2 * length)
        parts[f"{side}_arm"] = [shoulder, elbow, hand]
    return parts


def _widths(length: float) -> dict:
    return {"leg": max(3, int(round(length * 0.18))), "arm": max(2, int(round(length * 0.14))),
            "body": max(4, int(round(length * 0.3))), "head": max(2, int(round(length * 0.08)))}


def draw_pose(draw: ImageDraw.ImageDraw, parts: dict, widths: dict) -> None:
    for side, color in (("far", FAR), ("near", NEAR)):
        if side == "near":
            draw.line(parts["body"], fill=BODY, width=widths["body"])
            cx, cy = parts["head"]
            radius = parts["head_r"]
            draw.ellipse((cx - radius, cy - radius, cx + radius, cy + radius), outline=BODY, width=widths["head"])
        draw.line(parts[f"{side}_leg"], fill=color, width=widths["leg"], joint="curve")
        draw.line(parts[f"{side}_arm"], fill=color, width=widths["arm"], joint="curve")


def _svg_pose(parts: dict, widths: dict) -> list[str]:
    def points(items: Sequence[Sequence[float]]) -> str:
        return " ".join(f"{x:.1f},{y:.1f}" for x, y in items)

    hexa = sheet_qc.hex_color
    out = []
    for side, color in (("far", FAR), ("near", NEAR)):
        if side == "near":
            out.append(f'<polyline points="{points(parts["body"])}" fill="none" stroke="{hexa(BODY)}" '
                       f'stroke-width="{widths["body"]}" stroke-linecap="round"/>')
            cx, cy = parts["head"]
            out.append(f'<circle cx="{cx:.1f}" cy="{cy:.1f}" r="{parts["head_r"]:.1f}" fill="none" '
                       f'stroke="{hexa(BODY)}" stroke-width="{widths["head"]}"/>')
        for limb, width in (("leg", widths["leg"]), ("arm", widths["arm"])):
            out.append(f'<polyline points="{points(parts[f"{side}_{limb}"])}" fill="none" stroke="{hexa(color)}" '
                       f'stroke-width="{width}" stroke-linecap="round" stroke-linejoin="round"/>')
    return out


def _offset(parts: dict, dx: float, dy: float) -> dict:
    """A copy of a pose moved by (dx, dy)."""
    moved = {key: [(x + dx, y + dy) for x, y in value] for key, value in parts.items()
             if key in ("body", "near_leg", "far_leg", "near_arm", "far_arm")}
    moved.update(head=(parts["head"][0] + dx, parts["head"][1] + dy), head_r=parts["head_r"])
    return moved


def _pose_bounds(parts: dict, widths: dict) -> tuple[float, float, float, float]:
    pad = max(widths.values()) / 2.0
    points = [point for key in ("body", "near_leg", "far_leg", "near_arm", "far_arm") for point in parts[key]]
    cx, cy = parts["head"]
    radius = parts["head_r"] + widths["head"] / 2.0
    xs = [x for x, _ in points] + [cx - radius, cx + radius]
    ys = [y for _, y in points] + [cy - radius, cy + radius]
    return min(xs) - pad, min(ys) - pad, max(xs) + pad, max(ys) + pad


# --------------------------------------------------------------------------- guide

def build_guide(plan: dict, *, cycle: str, facing: str, safe: float, gutter: float,
                envelope_aspect: float) -> dict:
    """Draw guide.png, the annotated copy and the SVG; return them with the per-cell geometry.

    Cells are forge_core.rounded_grid_boxes of the predicted size; one motion
    envelope (the smallest that fits every cell's safe box) sizes every skeleton,
    so all poses share one scale.
    """
    width, height = plan["predicted_size"]
    rows, cols, frames = plan["rows"], plan["cols"], plan["frames"]
    boxes = forge_core.rounded_grid_boxes(width, height, rows, cols)
    envelope_h = min(min((y1 - y0) * (1 - 2 * safe), (x1 - x0) * (1 - 2 * safe) / envelope_aspect)
                     for x0, y0, x1, y1 in boxes)
    sign = 1.0 if facing == "right" else -1.0
    guide = Image.new("RGB", (width, height), (255, 255, 255))
    annotated = Image.new("RGB", (width, height), (255, 255, 255))
    svg = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" '
           f'viewBox="0 0 {width} {height}">', f'<rect width="{width}" height="{height}" fill="#ffffff"/>']
    phases = gait_phases(frames, cycle) if cycle != "none" else []
    font = ImageFont.load_default()
    cells = []
    for index, (x0, y0, x1, y1) in enumerate(boxes):
        cell_w, cell_h = x1 - x0, y1 - y0
        band = max(2, forge_core.round_half_up(gutter * min(cell_w, cell_h)))
        sx0, sy0 = x0 + safe * cell_w, y0 + safe * cell_h
        sx1, sy1 = x1 - safe * cell_w, y1 - safe * cell_h
        if band >= min(sx0 - x0, sy0 - y0):
            raise PlanError(f"The {band} px gutter reaches the safe box; lower --gutter or raise --safe.")
        ground_y = sy1
        root_x = sx0 + (0.55 if facing == "right" else 0.45) * (sx1 - sx0)
        record: dict[str, Any] = {"cell": [index // cols, index % cols], "box": [x0, y0, x1, y1],
                                  "safe_box": [round(sx0, 1), round(sy0, 1), round(sx1, 1), round(sy1, 1)],
                                  "gutter_px": band, "ground_y": round(ground_y, 1), "root_x": round(root_x, 1),
                                  "used": index < frames}
        for image in (guide, annotated):
            draw = ImageDraw.Draw(image)
            for strip in ((x0, y0, x1 - 1, y0 + band - 1), (x0, y1 - band, x1 - 1, y1 - 1),
                          (x0, y0, x0 + band - 1, y1 - 1), (x1 - band, y0, x1 - 1, y1 - 1)):
                draw.rectangle(strip, fill=GUTTER)
            draw.rectangle((sx0, sy0, sx1, sy1), outline=SAFE, width=3)
            if index < frames:
                draw.line((sx0, ground_y, sx1, ground_y), fill=INK, width=2)
                draw.line((root_x, ground_y - 12, root_x, ground_y + 12), fill=INK, width=2)
        svg.extend([
            f'<path d="M{x0},{y0}h{cell_w}v{cell_h}h{-cell_w}z M{x0 + band},{y0 + band}v{cell_h - 2 * band}'
            f'h{cell_w - 2 * band}v{-(cell_h - 2 * band)}z" fill="{sheet_qc.hex_color(GUTTER)}" fill-rule="evenodd"/>',
            f'<rect x="{sx0:.1f}" y="{sy0:.1f}" width="{sx1 - sx0:.1f}" height="{sy1 - sy0:.1f}" fill="none" '
            f'stroke="{sheet_qc.hex_color(SAFE)}" stroke-width="3"/>'])
        if index < frames:
            svg.extend([f'<line x1="{sx0:.1f}" y1="{ground_y:.1f}" x2="{sx1:.1f}" y2="{ground_y:.1f}" stroke="#000000" '
                        f'stroke-width="2"/>',
                        f'<line x1="{root_x:.1f}" y1="{ground_y - 12:.1f}" x2="{root_x:.1f}" y2="{ground_y + 12:.1f}" '
                        f'stroke="#000000" stroke-width="2"/>'])
        if index < len(phases):
            length = envelope_h / 4.8
            parts = skeleton(phases[index], keys=RUN_KEYS if cycle == "run" else WALK_KEYS, root_x=root_x,
                             ground_y=ground_y, length=length, sign=sign)
            widths = _widths(length)
            for image in (guide, annotated):
                draw_pose(ImageDraw.Draw(image), parts, widths)
            svg.extend(_svg_pose(parts, widths))
            bounds = _pose_bounds(parts, widths)
            toes = {side: parts[f"{side}_leg"][3] for side in ("near", "far")}
            ahead = "near" if (toes["near"][0] - toes["far"][0]) * sign > 0 else "far"
            record.update({"phase": phases[index]["name"], "pose_bounds": [round(value, 1) for value in bounds],
                           "inside_safe_box": bounds[0] >= sx0 and bounds[1] >= sy0 and bounds[2] <= sx1
                           and bounds[3] <= ground_y + widths["leg"],
                           "toe_ahead": ahead,
                           "foot_gap_px": {side: round(ground_y - max(parts[f"{side}_leg"][2][1], toes[side][1]), 1)
                                           for side in ("near", "far")},
                           "_parts": parts, "_widths": widths})
            label = (f"{index}: {phases[index]['name']} | contact leg {phases[index]['contact_leg'].upper()} | "
                     f"ahead {ahead.upper()}")
            ImageDraw.Draw(annotated).text((sx0 + 6, sy0 + 6), label, fill=INK, font=font)
        cells.append(record)
    svg.append("</svg>")
    return {"guide": guide, "annotated": annotated, "svg": "\n".join(svg) + "\n", "cells": cells, "phases": phases,
            "envelope_px": [round(envelope_h * envelope_aspect, 1), round(envelope_h, 1)]}


def self_check(guide: dict, *, cycle: str, facing: str, min_envelope: float, envelope_h: float) -> list[dict]:
    """Checks the guide must pass before it is published."""
    checks = [sheet_qc.check("min_envelope", "fail" if envelope_h < min_envelope else "pass",
                             round(envelope_h, 1), min_envelope,
                             note="predicted motion-envelope height per pose, in host pixels")]
    if cycle == "none":
        checks.append(sheet_qc.check("leg_alternation", "skipped", None, None, note="no skeleton without --cycle"))
        return checks
    used = [cell for cell in guide["cells"] if "phase" in cell]
    outside = [cell["cell"] for cell in used if not cell["inside_safe_box"]]
    checks.append(sheet_qc.check("skeleton_in_safe_box", "fail" if outside else "pass", outside, [],
                                 note="every pose, line widths included, inside its safe box"))
    grounded = []
    for cell, phase in zip(used, guide["phases"]):
        for side in ("near", "far"):
            gap = cell["foot_gap_px"][side]
            if phase["ground"][side] and abs(gap) > 1.0:
                grounded.append([cell["cell"], side, gap])
            if not any(phase["ground"].values()) and gap <= 0:
                grounded.append([cell["cell"], side, gap])
    checks.append(sheet_qc.check("ground_contact", "fail" if grounded else "pass", grounded, 1.0,
                                 note="planted feet touch the ground line; airborne poses clear it"))
    # The guide's own skeleton, drawn clean on transparency, must pass sheet_qc's leading-leg test.
    leads = []
    for cell in used:
        x0, y0, x1, y1 = cell["box"]
        model = Image.new("RGBA", (x1 - x0, y1 - y0), (0, 0, 0, 0))
        draw_pose(ImageDraw.Draw(model), _offset(cell["_parts"], -x0, -y0), cell["_widths"])
        leads.append(sheet_qc.leg_lead(np.asarray(model), facing=facing, near=[NEAR], far=[FAR]))
    verdict = sheet_qc.alternation_verdict(leads)
    checks.append(sheet_qc.check("leg_alternation", verdict["status"], [item["lead"] for item in verdict["leads"]],
                                 "lead differs between i and i+n/2", verdict=verdict["verdict"],
                                 pairs=verdict["pairs"],
                                 note="sheet_qc.py frames' NEAR/FAR test run on the guide's own skeleton"))
    return checks


def prompt_block(plan: dict, *, cycle: str, facing: str, phases: Sequence[dict]) -> str:
    """The aspect-only prompt text that explains the guide image."""
    rows, cols, frames = plan["rows"], plan["cols"], plan["frames"]
    width, height = plan["predicted_size"]
    lines = [
        f"Request aspect {plan['aspect']}. Do not state pixel sizes: the host image tool keeps the aspect and",
        f"returns about {width}x{height} for it (area about {HOST_BUDGET_PX:,} px).",
        "Attach guide.png as a layout and pose reference only. Do not draw any of its lines, boxes, colours,",
        "grey bands or stick figures.",
        f"- {frames} poses in {rows} rows x {cols} columns, read left to right, top row first"
        + (f"; leave the last {rows * cols - frames} cell(s) empty." if rows * cols > frames else "."),
        "- The grey band around every cell is empty gutter: no pixel of the character may enter it.",
        "- Keep the whole character (ears, tail, both feet, held items) inside the blue safe box of its cell.",
        "- The black line is the ground and the tick is the fixed root: one body scale and one root in every cell.",
        f"- The character faces {facing.upper()} in every cell.",
    ]
    if cycle != "none":
        half = frames // 2
        lines += [
            "- Match each cell's stick pose. ORANGE limbs are NEAR limbs (viewer side): normal brightness, drawn in",
            "  front. BLUE limbs are FAR limbs (away side): one shade darker, partly hidden behind the body.",
            "Poses (NEAR/FAR, never left/right):",
        ]
        for phase in phases:
            key = phase["name"].split("-")[0]
            a, b = phase["contact_leg"].upper(), ("FAR" if phase["contact_leg"] == "near" else "NEAR")
            b_lift = ", foot lifted" if cycle == "run" else ", heel lifted"
            text = PHASE_TEXT[key].format(a=a, b=b, b_lift=b_lift)
            if "-" in phase["name"]:
                text = f"between {key} and {phase['name'].split('-', 1)[1]}: " + text
            lines.append(f"{phase['index']} {key}: {text}.")
        lines.append(f"Frames {half}-{frames - 1} must not repeat frames 0-{half - 1}: the leg drawn in front swaps "
                     "between NEAR and FAR.")
    lines += [
        "Background: real transparency, or one flat chroma colour absent from the character.",
        "No text, labels, numbers, grid lines, shadows, dust or checkerboard.",
        "",
        "After generation: run sheet_qc.py spill on the raw sheet, then sheet_qc.py frames"
        + (f" --cycle {cycle}." if cycle != "none" else "."),
    ]
    if cycle != "none":
        lines += ["If the leading-leg test reports a duplicated half-cycle, regenerate only the second half,",
                  "attaching the first half and this guide."]
    return "\n".join(lines) + "\n"


# --------------------------------------------------------------------------- CLI

def run(args: argparse.Namespace) -> dict:
    if args.frames < 1:
        raise PlanError("--frames must be at least 1.")
    if args.frames > MAX_CELLS:
        raise PlanError(f"--frames must be at most {MAX_CELLS}: a host sheet of about 1.5 megapixels has no room "
                        "for more poses; split the action into several sheets.")
    if args.cycle != "none" and (args.frames % 2 or args.frames < 4):
        raise PlanError("--cycle run|walk needs an even number of frames, at least 4 (two half-cycles).")
    if not 0.0 <= args.safe < 0.45:
        raise PlanError("--safe is a fraction of the cell in [0, 0.45).")
    if not 0.0 < args.gutter < 0.2:
        raise PlanError("--gutter is a fraction of the cell in (0, 0.2).")
    if not 4096 <= args.budget <= MAX_BUDGET_PX:  # the guides are drawn at this size; 1e10 px never finished
        raise PlanError(f"--budget is the host image area in pixels (about 1572864, at most {MAX_BUDGET_PX}).")
    if args.max_empty < 0:
        raise PlanError("--max-empty must be 0 or more.")
    envelope_aspect = parse_ratio(args.envelope_aspect)
    aspects = list(STANDARD_ASPECTS) if args.aspect == "auto" else [args.aspect]
    for text in aspects:
        parse_aspect(text)
    layouts = candidate_layouts(args.frames, aspects, envelope_aspect=envelope_aspect, safe=args.safe,
                                budget=args.budget, max_empty=args.max_empty)
    if args.rows or args.cols:
        if not (args.rows and args.cols):
            raise PlanError("--rows and --cols go together.")
        if args.rows < 1 or args.cols < 1 or args.rows * args.cols > MAX_CELLS:
            raise PlanError(f"--rows and --cols must be positive with at most {MAX_CELLS} cells in all.")
        if args.rows * args.cols < args.frames:
            raise PlanError(f"{args.rows} x {args.cols} cells cannot hold {args.frames} frames.")
        layouts = candidate_layouts(args.frames, aspects, envelope_aspect=envelope_aspect, safe=args.safe,
                                    budget=args.budget, max_empty=args.rows * args.cols - args.frames)
        layouts = [item for item in layouts if item["rows"] == args.rows and item["cols"] == args.cols]
    if not layouts:
        raise PlanError("No grid fits; raise --max-empty.")
    chosen = dict(layouts[0], frames=args.frames)
    guide = build_guide(chosen, cycle=args.cycle, facing=args.facing, safe=args.safe, gutter=args.gutter,
                        envelope_aspect=envelope_aspect)
    chosen["envelope_px"] = guide["envelope_px"]  # measured on the whole-pixel cells that were drawn
    checks = self_check(guide, cycle=args.cycle, facing=args.facing, min_envelope=args.min_envelope_px,
                        envelope_h=chosen["envelope_px"][1])
    status = sheet_qc.worst_status([item["status"] for item in checks])
    if status == "fail":
        failed = "; ".join(f"{item['id']}={json.dumps(item['value'], ensure_ascii=True)}"
                           for item in checks if item["status"] == "fail")
        raise PlanError(f"guide self-check failed ({failed}); nothing was published")
    prompt = prompt_block(chosen, cycle=args.cycle, facing=args.facing, phases=guide["phases"])
    output_dir = Path(args.output_dir)
    with forge_core.staged_output(output_dir) as stage:
        forge_core.save_png(guide["guide"], stage / "guide.png")
        forge_core.save_png(guide["annotated"], stage / "guide-annotated.png")
        (stage / "guide.svg").write_bytes(guide["svg"].encode("ascii"))
        (stage / "prompt.txt").write_bytes(prompt.encode("ascii"))
        outputs = [forge_core.file_ref(stage / name, stage)
                   for name in ("guide.png", "guide.svg", "guide-annotated.png", "prompt.txt")]
        cells = [{key: value for key, value in cell.items() if not key.startswith("_")} for cell in guide["cells"]]
        plan = {
            "schema": SCHEMA,
            "request": {"frames": args.frames, "cycle": args.cycle, "facing": args.facing, "aspect": args.aspect,
                        "envelope_aspect": round(envelope_aspect, 4), "safe": args.safe, "gutter": args.gutter,
                        "budget_px": args.budget, "max_empty": args.max_empty},
            "predicted_size": chosen["predicted_size"], "aspect": chosen["aspect"],
            "layout": {key: chosen[key] for key in ("rows", "cols", "empty_cells", "cell", "divides_exactly",
                                                    "safe_box", "envelope_px")},
            "candidates": layouts[:8],
            "cells": cells,
            "phases": [{key: (list(value) if isinstance(value, tuple) else value) for key, value in phase.items()}
                       for phase in guide["phases"]],
            "prompt": "prompt.txt",
            "qa": {"status": status,
                   "method": "geometry of the drawn guide plus sheet_qc.leg_lead/alternation_verdict on its own "
                             "skeleton drawn clean on transparency",
                   "notProven": ["That an image model follows the guide: not A/B tested (report v2 P2-4).",
                                 "The host size rule was observed on 3 calls of one host tool; other tools differ."],
                   "checks": checks, "inputs": [], "outputs": outputs, "tool": dict(TOOL)},
            "tool": dict(TOOL),
        }
        forge_core.write_json(stage / PLAN_NAME, plan)
    return {"status": status, "output": str(output_dir), "metadata": str(output_dir / PLAN_NAME),
            "aspect": chosen["aspect"], "predicted_size": chosen["predicted_size"],
            "grid": [chosen["rows"], chosen["cols"]], "guide": str(output_dir / "guide.png")}


def _aspect(text: str) -> str:
    value = text.strip()
    if value == "auto":
        return value
    try:
        parse_aspect(value)
    except PlanError as error:
        raise argparse.ArgumentTypeError(str(error)) from None
    return value


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--frames", type=int, required=True,
                        help=f"number of poses in the sheet (1 to {MAX_CELLS})")
    parser.add_argument("--output-dir", required=True, help="new directory for the guide, prompt and plan")
    parser.add_argument("--cycle", choices=CYCLES, default="none",
                        help="run or walk draws the NEAR/FAR leg skeleton (default none: layout only)")
    parser.add_argument("--facing", choices=("right", "left"), default="right")
    parser.add_argument("--aspect", type=_aspect, default="auto",
                        help="host aspect W:H, or auto to try 3:2, 2:3, 1:1, 16:9, 9:16, 2:1 and 1:2 (default auto)")
    parser.add_argument("--rows", type=int, default=None, help="force the rows (with --cols)")
    parser.add_argument("--cols", type=int, default=None, help="force the columns (with --rows)")
    parser.add_argument("--envelope-aspect", default="1.0",
                        help="width/height of the whole action's motion envelope (default 1.0)")
    parser.add_argument("--safe", type=float, default=0.15, help="safe frame per cell side (default 0.15)")
    parser.add_argument("--gutter", type=float, default=0.04, help="empty band at each cell edge (default 0.04)")
    parser.add_argument("--max-empty", type=int, default=1, help="spare cells allowed (default 1)")
    parser.add_argument("--budget", type=int, default=HOST_BUDGET_PX,
                        help=f"host image area in pixels (default {HOST_BUDGET_PX}, at most {MAX_BUDGET_PX})")
    parser.add_argument("--min-envelope-px", type=float, default=0.0,
                        help="fail when a pose gets less envelope height than this many host pixels")
    return parser


def _run(argv: Sequence[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    summary = run(args)
    print(json.dumps(summary, ensure_ascii=True))
    return 0


def main(argv: Sequence[str] | None = None) -> int:
    """CLI entry (D26, D27): usage errors exit 2 (argparse); every other failure, a failed self-check
    included, prints one ``error: ...`` line and exits 1 with nothing published."""
    return forge_core.run_cli(_run, argv)


if __name__ == "__main__":
    raise SystemExit(main())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall