Skip to content

notque/vexjoy-agent / skills/game/game-dev

game-dev

Flagged

Game development: design, asset pipelines, Phaser, Unity CLI and builds, vanilla JS frontend, GM mode, match booking.

FileKindSize
SKILL.mdskill md14.7 KB
references/anchor-alignment.mdmarkdown16.0 KB
references/animate-scaffolds.mdmarkdown2.0 KB
references/arcade-physics.mdmarkdown7.4 KB
references/artifacts-and-prototyping.mdmarkdown1.5 KB
references/asset-sources.mdmarkdown7.9 KB
references/audit-and-red-team.mdmarkdown795 B
references/autonomous-improvement.mdmarkdown10.3 KB
references/backend-chain.mdmarkdown10.4 KB
references/bg-removal-local.mdmarkdown22.7 KB
references/build-scaffolds.mdmarkdown2.0 KB
references/capabilities/01-design-red-team-audit.mdmarkdown3.9 KB
references/capabilities/02-emotional-canvas-moodboard.mdmarkdown3.7 KB
references/capabilities/03-game-design-attribution-audit.mdmarkdown3.6 KB
references/capabilities/04-game-design-bartle-archetype-audit.mdmarkdown3.7 KB
references/capabilities/05-game-design-big-five-personality-audit.mdmarkdown3.6 KB
references/capabilities/06-game-design-brainstorm-methods.mdmarkdown3.9 KB
references/capabilities/07-game-design-core-loop-extractor.mdmarkdown3.7 KB
references/capabilities/08-game-design-craft-critique.mdmarkdown3.5 KB
references/capabilities/09-game-design-creative-unblocker.mdmarkdown3.5 KB
references/capabilities/10-game-design-design-pillars-extractor.mdmarkdown3.5 KB
references/capabilities/11-game-design-emotional-canvas.mdmarkdown3.6 KB
references/capabilities/12-game-design-failure-loop-audit.mdmarkdown3.8 KB
references/capabilities/13-game-design-fairness-frustration-audit.mdmarkdown3.6 KB
references/capabilities/14-game-design-fantasy-extractor.mdmarkdown3.6 KB
references/capabilities/15-game-design-feature-prioritization.mdmarkdown3.6 KB
references/capabilities/16-game-design-five-options.mdmarkdown3.5 KB
references/capabilities/17-game-design-flow-audit.mdmarkdown3.6 KB
references/capabilities/18-game-design-fogg-behavior-audit.mdmarkdown3.6 KB
references/capabilities/19-game-design-friction-journey-audit.mdmarkdown3.8 KB
references/capabilities/20-game-design-ftue-hero-journey-audit.mdmarkdown3.7 KB
references/capabilities/21-game-design-goal-density-and-immediacy-audit.mdmarkdown3.5 KB
references/capabilities/22-game-design-goal-framing.mdmarkdown3.5 KB
references/capabilities/23-game-design-granular-player-motivation-audit.mdmarkdown4.0 KB
references/capabilities/24-game-design-grow-design.mdmarkdown3.5 KB
references/capabilities/25-game-design-ideal-outcome-backcasting.mdmarkdown3.4 KB
references/capabilities/26-game-design-kpi-coverage-audit.mdmarkdown3.8 KB
references/capabilities/27-game-design-leaderboard-audit.mdmarkdown3.9 KB
references/capabilities/28-game-design-leaderboard-builder.mdmarkdown3.8 KB
references/capabilities/29-game-design-molyneux-lens.mdmarkdown3.5 KB
references/capabilities/30-game-design-multiplayer-feature-audit.mdmarkdown3.8 KB
references/capabilities/31-game-design-novelty-spectrum-audit.mdmarkdown3.6 KB
references/capabilities/32-game-design-one-page-design-doc.mdmarkdown3.8 KB
references/capabilities/33-game-design-one-thing-to-remove.mdmarkdown3.6 KB
references/capabilities/34-game-design-option-generation.mdmarkdown3.5 KB
references/capabilities/35-game-design-peak-end-audit.mdmarkdown3.6 KB
references/capabilities/36-game-design-perceived-randomness-audit.mdmarkdown3.7 KB
references/capabilities/37-game-design-pitch-deck-audit.mdmarkdown3.8 KB
references/capabilities/38-game-design-player-motivation-audit.mdmarkdown3.5 KB
references/capabilities/39-game-design-player-need-satisfaction-audit.mdmarkdown3.6 KB
references/capabilities/40-game-design-player-persona-extractor.mdmarkdown4.2 KB
references/capabilities/41-game-design-player-perspective-reframe.mdmarkdown3.7 KB
references/capabilities/42-game-design-player-segment-perception-audit.mdmarkdown3.6 KB
references/capabilities/43-game-design-player-values-mapper.mdmarkdown3.8 KB
references/capabilities/44-game-design-premium-pass-audit.mdmarkdown3.8 KB
references/capabilities/45-game-design-prosocial-session-chapters.mdmarkdown3.7 KB
references/capabilities/46-game-design-prototype-intent-audit.mdmarkdown3.7 KB
references/capabilities/47-game-design-prototyping-companion.mdmarkdown3.6 KB
references/capabilities/48-game-design-roadblock-reframing.mdmarkdown3.5 KB
references/capabilities/49-game-design-smart-goal-audit.mdmarkdown3.6 KB
references/capabilities/50-game-design-social-satisfaction-matrix.mdmarkdown3.7 KB
references/capabilities/51-game-design-systematizing-empathizing-audit.mdmarkdown3.6 KB
references/capabilities/52-game-design-thinking-fast-and-slow-audit.mdmarkdown3.6 KB
references/capabilities/53-game-design-transformative-reuse.mdmarkdown3.6 KB
references/capabilities/54-game-design-unknown-unknowns-prototyping.mdmarkdown3.6 KB
references/capabilities/55-game-design-zeigarnik-effect-audit.mdmarkdown3.6 KB
references/capabilities/56-game-dev-budget-estimator.mdmarkdown3.8 KB
references/capabilities/57-game-dev-first-steps.mdmarkdown3.6 KB
references/capabilities/58-game-dev-team-gap.mdmarkdown3.6 KB
references/capabilities/59-game-dev-time-estimator.mdmarkdown3.8 KB
references/capabilities/60-moodboard-generator.mdmarkdown4.0 KB
references/capabilities/61-software-team-conflict-patterns.mdmarkdown3.8 KB
references/capability-catalog.mdmarkdown18.4 KB
references/capability-map.mdmarkdown1.7 KB
references/capability-matrix.mdmarkdown12.5 KB
references/capacitor-ios.mdmarkdown7.3 KB
references/cognition-and-choice.mdmarkdown1.2 KB
references/cognitive-and-behavioral-lenses.mdmarkdown1.2 KB
references/combat-effects-upgrade.mdmarkdown13.3 KB
references/combat-effects-upgrade/css-3d-card-transforms.mdmarkdown10.1 KB
references/combat-effects-upgrade/css-particle-migration.mdmarkdown13.3 KB
references/combat-effects-upgrade/framer-motion-combat-juice.mdmarkdown11.9 KB
references/concept-and-loop.mdmarkdown1.5 KB
references/core-loop-and-pillars.mdmarkdown835 B
references/core-patterns.mdmarkdown8.2 KB
references/cpu-systems-harmony.mdmarkdown3.4 KB
references/creative-and-options.mdmarkdown2.0 KB
references/creative-direction.mdmarkdown1.3 KB
references/deploy.mdmarkdown5.3 KB
references/design-artifacts.mdmarkdown1.0 KB
references/emotion-and-presentation.mdmarkdown1.1 KB
references/error-catalog.mdmarkdown22.6 KB
references/fairness-and-failure.mdmarkdown1.2 KB
references/fairness-and-learning.mdmarkdown1.3 KB
references/fal-ai-image.mdmarkdown7.1 KB
references/frame-detection.mdmarkdown20.0 KB
references/full-diagnostic.mdmarkdown4.2 KB
references/game-asset-generator.mdmarkdown9.5 KB
references/game-audio.mdmarkdown7.5 KB
references/game-feel-patterns.mdmarkdown12.2 KB
references/game-pipeline.mdmarkdown11.5 KB
references/game-qa.mdmarkdown6.7 KB
references/game-sprite-pipeline.mdmarkdown33.4 KB
references/gm-brilliant-implementation.mdmarkdown13.4 KB
references/grid-shapes.mdmarkdown8.0 KB
references/meshyai.mdmarkdown7.3 KB
references/motion-pipeline.mdmarkdown7.6 KB
references/output-formats.mdmarkdown9.4 KB
references/pacing-and-return.mdmarkdown1.6 KB
references/performance.mdmarkdown7.8 KB
references/phaser-gamedev.mdmarkdown7.5 KB
references/pipeline-spec.jsonconfig23.5 KB
references/pixel-art-sprites.mdmarkdown8.7 KB
references/pixijs-combat-renderer.mdmarkdown12.1 KB
references/pixijs-combat-renderer/combat-visual-effects.mdmarkdown7.8 KB
references/pixijs-combat-renderer/pixi-2d-lighting.mdmarkdown6.6 KB
references/pixijs-combat-renderer/pixi-particle-systems.mdmarkdown9.2 KB
references/pixijs-combat-renderer/pixi-performance.mdmarkdown4.8 KB
references/pixijs-combat-renderer/pixi-post-processing.mdmarkdown6.3 KB
references/pixijs-combat-renderer/pixi-react-integration.mdmarkdown5.2 KB
references/planning-and-communication.mdmarkdown1.6 KB
references/planning-and-production.mdmarkdown1.8 KB
references/player-and-social.mdmarkdown2.3 KB
references/polish-scaffolds.mdmarkdown1.9 KB
references/progression-and-economy.mdmarkdown1.0 KB
references/promo-video.mdmarkdown6.6 KB
references/prompt-rules.mdmarkdown15.2 KB
references/quality-gates.mdmarkdown6.4 KB
references/rive-skeletal-animator.mdmarkdown7.6 KB
references/rive-skeletal-animator/rive-animation-library.mdmarkdown8.1 KB
references/rive-skeletal-animator/rive-async-patterns.mdmarkdown5.6 KB
references/rive-skeletal-animator/rive-character-pipeline.mdmarkdown5.6 KB
references/rive-skeletal-animator/rive-performance.mdmarkdown5.4 KB
references/rive-skeletal-animator/rive-react-setup.mdmarkdown9.9 KB
references/rive-skeletal-animator/rive-vs-spine-decision.mdmarkdown6.0 KB
references/road-to-aew-integration.mdmarkdown7.8 KB
references/social-and-competitive-design.mdmarkdown1.1 KB
references/social-and-competitive.mdmarkdown1.5 KB
references/spritesheets.mdmarkdown6.2 KB
references/stage-contracts.mdmarkdown11.1 KB
references/style-presets.mdmarkdown5.1 KB
references/subagent-delegation.mdmarkdown2.2 KB
references/tilemaps-and-physics.mdmarkdown13.6 KB
references/tilemaps.mdmarkdown7.0 KB
references/unity-batchmode-builds.mdmarkdown9.2 KB
references/unity-cli.mdmarkdown10.9 KB
references/unity-licensing.mdmarkdown5.0 KB
references/vfx-containment.mdmarkdown3.1 KB
references/workflow-dag.mdmarkdown4.1 KB
references/worldlabs.mdmarkdown7.9 KB
references/wrestler-archetypes.mdmarkdown7.2 KB
scripts/deterministic_idle.pyscript7.8 KB
scripts/fal_queue_image_run.pyscript9.4 KB
scripts/imgdiff.pyscript5.0 KB
scripts/meshy-generate.mjsscript11.1 KB
scripts/optimize-glb.mjsscript3.8 KB
scripts/portrait_pipeline.pyscript31.2 KB
scripts/qa_artifacts.pyscript14.4 KB
scripts/road_to_aew_integration.pyscript6.6 KB
scripts/row_job_status.pyscript8.6 KB
scripts/sprite_anchor.pyscript30.1 KB
scripts/sprite_assemble.pyscript16.0 KB
scripts/sprite_bg.pyscript28.5 KB
scripts/sprite_canvas.pyscript11.9 KB
scripts/sprite_generate.pyscript13.9 KB
scripts/sprite_pipeline.pyscript54.9 KB
scripts/sprite_process.pyscript13.5 KB
scripts/sprite_prompt.pyscript41.8 KB
scripts/sprite_slicing.pyscript38.7 KB
scripts/sprite_verify.pyscript58.5 KB
scripts/test_content_aware_extraction.pyscript13.4 KB
scripts/test_no_status_laundering.pyscript6.9 KB
scripts/test_phases_4_5_7_8.pyscript16.4 KB
scripts/test_pipeline_glue.pyscript20.9 KB
scripts/test_pipeline_patterns.pyscript10.9 KB
scripts/test_rc3_frames_distinct_threshold.pyscript14.2 KB
scripts/test_rc4_mass_centroid_default.pyscript8.3 KB
scripts/test_rc5_despill_pre_upscale.pyscript7.9 KB
scripts/test_slice_grid_cells.pyscript6.4 KB
scripts/test_slicer_strict_pitch_default.pyscript11.6 KB
scripts/test_verifier_cell_parity.pyscript9.0 KB
scripts/test_verify_gates.pyscript23.2 KB
scripts/tests/test_fal_queue_image_run.pyscript908 B
scripts/video_extract_frames.pyscript4.3 KB
scripts/video_process_frames.pyscript7.6 KB
scripts/video_select_frames.pyscript6.4 KB
scripts/with_server.pyscript5.8 KB

scripts/portrait_pipeline.py

View on GitHub
#!/usr/bin/env python3
"""
Portrait-mode end-to-end orchestrator (Phases A-E).

Chains:
    A: prompt build + backend dispatch
    B: bg removal (chroma key default; rembg opt-in)
    C: trim and re-canvas with bottom anchor
    D: dimension validation (width 350-850, height 900-1100, aspect 1:1.5-1:2.5)
    E: project-aware deploy (road-to-aew if --target road-to-aew)

Usage:
    python3 portrait_pipeline.py \\
        --display-name "Bangkok Belle Nisa" \\
        --description "kabuki makeup, Thai national colors" \\
        --style slay-the-spire-painted --archetype showman --gimmick heel \\
        --tier act2 --target road-to-aew --regen-manifest --seed 42

--dry-run skips the backend call and uses a synthetic fixture for
post-processing validation. Useful for CI smoke tests.
"""

from __future__ import annotations

import argparse
import json
import logging
import os
import shutil
import sys
import tempfile
import time
from datetime import datetime, timezone
from pathlib import Path

logger = logging.getLogger("sprite-pipeline.portrait_pipeline")

try:
    from PIL import Image, ImageDraw
except ImportError as e:
    logger.error("Pillow not installed: %s", e)
    sys.exit(1)

SCRIPT_DIR = Path(__file__).resolve().parent
sys.path.insert(0, str(SCRIPT_DIR))

import sprite_bg
import sprite_generate
import sprite_process
import sprite_prompt
from sprite_verify import (
    verify_anchor_consistency,
    verify_frames_distinct,
    verify_frames_have_content,
    verify_no_magenta,
)

# See ADR-199. Distinct from generic pipeline error rc=1 so callers can
# branch on "verifier said no" vs "the pipeline blew up".
VERIFIER_EXIT_CODE = 2


def _detect_backends_available() -> dict[str, bool]:
    """Best-effort backend availability for the verifier failure JSON.

    Cheap shutil/env checks only; we never spawn ``codex --version`` here.
    Mirrors sprite_pipeline._detect_backends_available; duplicated by
    design (per CLAUDE.md "three-line repetition is better than premature
    abstraction") rather than introducing a new module solely for this.
    """
    nano_script = sprite_generate.find_nano_banana_script()
    return {
        "codex": shutil.which("codex") is not None,
        "nano_banana": nano_script is not None
        and bool(os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")),
    }


def _emit_verifier_result(
    gates_run: list[str],
    failures: list[dict],
    elapsed_seconds: float,
) -> int:
    """Print the structured verifier JSON to stdout and return the exit code.

    Per ADR-199. JSON shape:

        {passed, gates_run, failures, backends_available, elapsed_seconds}

    Returns ``VERIFIER_EXIT_CODE`` (2) when failures is non-empty; else 0.
    """
    payload = {
        "passed": len(failures) == 0,
        "gates_run": gates_run,
        "failures": failures,
        "backends_available": _detect_backends_available(),
        "elapsed_seconds": round(elapsed_seconds, 3),
    }
    print(json.dumps(payload, indent=2))
    return 0 if payload["passed"] else VERIFIER_EXIT_CODE


def _make_fixture_portrait(output: Path) -> None:
    """Synthesize a 600x950 magenta-bg PNG with a simple figure for smoke tests."""
    img = Image.new("RGBA", (600, 950), (255, 0, 255, 255))
    d = ImageDraw.Draw(img)
    # head
    d.ellipse((250, 80, 350, 200), fill=(220, 180, 150, 255), outline=(40, 20, 20, 255), width=4)
    # body
    d.rectangle((220, 200, 380, 600), fill=(180, 40, 40, 255), outline=(40, 20, 20, 255), width=4)
    # legs
    d.rectangle((230, 600, 290, 870), fill=(60, 60, 80, 255), outline=(40, 20, 20, 255), width=4)
    d.rectangle((310, 600, 370, 870), fill=(60, 60, 80, 255), outline=(40, 20, 20, 255), width=4)
    # arms
    d.rectangle((150, 220, 220, 480), fill=(180, 40, 40, 255), outline=(40, 20, 20, 255), width=4)
    d.rectangle((380, 220, 450, 480), fill=(180, 40, 40, 255), outline=(40, 20, 20, 255), width=4)
    output.parent.mkdir(parents=True, exist_ok=True)
    img.save(output, format="PNG")


def _make_fixture_portrait_loop(output: Path, cell: int = 512) -> None:
    """Synthesize a 1024x1024 2x2 grid of near-identical figures for smoke tests."""
    img = Image.new("RGBA", (cell * 2, cell * 2), (255, 0, 255, 255))
    d = ImageDraw.Draw(img)
    for r in range(2):
        for c in range(2):
            ox, oy = c * cell, r * cell
            # eye state: 0 open, 2 closed (blink), 1+3 open
            blink = (r * 2 + c) == 2
            chest_offset = 0 if (r * 2 + c) == 0 else (-3 if (r * 2 + c) == 1 else 3)
            # head
            d.ellipse(
                (ox + 200, oy + 80, ox + 312, oy + 200),
                fill=(220, 180, 150, 255),
                outline=(40, 20, 20, 255),
                width=4,
            )
            # eyes
            eye_y = oy + 130
            if blink:
                d.line((ox + 225, eye_y, ox + 245, eye_y), fill=(40, 20, 20, 255), width=3)
                d.line((ox + 270, eye_y, ox + 290, eye_y), fill=(40, 20, 20, 255), width=3)
            else:
                d.ellipse((ox + 225, eye_y - 5, ox + 245, eye_y + 5), fill=(40, 20, 20, 255))
                d.ellipse((ox + 270, eye_y - 5, ox + 290, eye_y + 5), fill=(40, 20, 20, 255))
            # body (with chest variation)
            d.rectangle(
                (ox + 180 - chest_offset, oy + 200, ox + 332 + chest_offset, oy + 380),
                fill=(180, 40, 40, 255),
                outline=(40, 20, 20, 255),
                width=4,
            )
    output.parent.mkdir(parents=True, exist_ok=True)
    img.save(output, format="PNG")


def _snake_case(name: str) -> str:
    """Mirror road_to_aew_integration.snake_case for orchestration use."""
    parts = name.strip().split()
    while parts and parts[0].lower() in {"the", "a", "an"}:
        parts.pop(0)
    s = " ".join(parts).lower()
    cleaned = []
    for ch in s:
        if ch.isalnum():
            cleaned.append(ch)
        elif ch.isspace() or ch == "-":
            cleaned.append("_")
    out = "".join(cleaned)
    while "__" in out:
        out = out.replace("__", "_")
    return out.strip("_")


def _run_pipeline_body(args: argparse.Namespace, work_dir: Path, name: str) -> int:
    """Portrait pipeline body. ``work_dir`` lifetime is bounded by caller.

    See ADR-200 for the lifecycle contract: ``--output-dir`` set means
    the user owns the directory; unset means the caller wraps this in a
    ``tempfile.TemporaryDirectory`` that reaps on exit.
    """
    work_dir.mkdir(parents=True, exist_ok=True)

    started = datetime.now(timezone.utc)
    phases: list[dict] = []

    # Phase A: prompt
    prompt_path = work_dir / f"{name}_prompt.txt"
    metadata_path = work_dir / f"{name}_prompt.json"
    prompt_argv = [
        "build-portrait",
        "--style",
        args.style,
        "--description",
        args.description or args.display_name or "",
        "--seed",
        str(args.seed),
        "--output",
        str(prompt_path),
        "--metadata-out",
        str(metadata_path),
    ]
    if args.archetype:
        prompt_argv.extend(["--archetype", args.archetype])
    if args.gimmick:
        prompt_argv.extend(["--gimmick", args.gimmick])
    if args.tier:
        prompt_argv.extend(["--tier", args.tier])
    if args.style_string:
        prompt_argv.extend(["--style-string", args.style_string])
    rc = sprite_prompt.main(prompt_argv)
    if rc != 0:
        return rc
    phases.append({"phase": "A1", "name": "prompt-build", "rc": rc})

    # Phase A: backend dispatch (or fixture in dry-run)
    raw_path = work_dir / f"{name}_raw.png"
    if args.dry_run:
        _make_fixture_portrait(raw_path)
        phases.append({"phase": "A2", "name": "generate", "rc": 0, "dry_run": True})
    else:
        gen_argv = [
            "generate-portrait",
            "--prompt-file",
            str(prompt_path),
            "--output",
            str(raw_path),
            "--seed",
            str(args.seed),
        ]
        rc = sprite_generate.main(gen_argv)
        if rc != 0:
            return rc
        phases.append({"phase": "A2", "name": "generate", "rc": rc})

    # Phase B: bg removal
    nobg_path = work_dir / f"{name}_nobg.png"
    rc = sprite_process.main(
        [
            "remove-bg",
            str(raw_path),
            "--output",
            str(nobg_path),
            "--bg-mode",
            args.bg_mode,
            "--chroma-threshold",
            str(args.chroma_threshold),
        ]
    )
    if rc != 0:
        return rc
    phases.append({"phase": "B", "name": "remove-bg", "rc": rc, "mode": args.bg_mode})

    # Phase C: trim and re-canvas
    trimmed_path = work_dir / f"{name}_trimmed.png"
    rc = sprite_process.main(
        [
            "normalize",
            "--mode",
            "portrait",
            "--input",
            str(nobg_path),
            "--output",
            str(trimmed_path),
            "--target-w",
            str(args.target_w),
            "--target-h",
            str(args.target_h),
        ]
    )
    if rc != 0:
        return rc
    phases.append({"phase": "C", "name": "trim-center", "rc": rc})

    # Phase D: validate dimensions
    validate_argv = ["validate-portrait", str(trimmed_path)]
    if args.force_dimensions:
        validate_argv.append("--force")
    rc = sprite_process.main(validate_argv)
    phases.append({"phase": "D", "name": "validate", "rc": rc, "force": args.force_dimensions})
    if rc != 0:
        return rc

    # Phase E: deploy (or local copy)
    final_path = work_dir / f"{name}.png"
    # Context-managed open ensures the source handle is closed
    # deterministically (ADR-200 file-handle hygiene).
    with Image.open(trimmed_path) as im:
        im.save(final_path, format="PNG")
    if args.target == "road-to-aew":
        deploy_argv = [
            "deploy",
            "--source",
            str(final_path),
            "--display-name",
            args.display_name or name,
        ]
        if args.player:
            deploy_argv.extend(["--player", args.player])
        if args.target_dir:
            deploy_argv.extend(["--target-dir", args.target_dir])
        if args.regen_manifest:
            deploy_argv.append("--regen-manifest")
        if args.dry_run:
            deploy_argv.append("--dry-run")
        from road_to_aew_integration import main as deploy_main

        rc = deploy_main(deploy_argv)
        phases.append({"phase": "E", "name": "deploy", "rc": rc, "target": "road-to-aew"})
        if rc != 0:
            return rc
    else:
        phases.append({"phase": "E", "name": "deploy", "rc": 0, "target": "local", "path": str(final_path)})

    # Metadata sidecar
    sidecar = {
        "name": name,
        "display_name": args.display_name,
        "seed": args.seed,
        "style_preset": args.style,
        "archetype": args.archetype,
        "gimmick": args.gimmick,
        "tier": args.tier,
        "dry_run": args.dry_run,
        "started_at": started.isoformat(),
        "completed_at": datetime.now(timezone.utc).isoformat(),
        "phases": phases,
        "output_dir": str(work_dir),
    }
    (work_dir / f"{name}_metadata.json").write_text(json.dumps(sidecar, indent=2), encoding="utf-8")

    logger.info(
        "[portrait] PASS: %s written to %s (phases: %d)",
        name,
        work_dir,
        len(phases),
    )

    # Phase F: verifier gates (ADR-199). Default-on; opt out with --no-verify.
    # Portrait mode runs the subset of gates that apply to a single static
    # image:
    #   - verify_no_magenta: catches residual chroma-key bleed-through.
    #
    # Gates NOT run for portrait mode (and why):
    #   - verify_pixel_preservation: ADR-199 lists it for portraits, but the
    #     function fundamentally takes grid+cell_size and slices both raw and
    #     final into per-cell tiles. A variable-dimension single portrait
    #     does not have a meaningful cell grid; treating the whole image as
    #     one 1x1 cell with raw_size != final_size produces a misleading
    #     area_ratio and false-positive "lossy" verdicts. The dominant
    #     defect surface for portraits is chroma bleed, which verify_no_magenta
    #     covers cleanly. Documented as a deviation from ADR-199's literal
    #     gate list with rationale.
    #   - verify_grid_alignment / _frames_have_content / _frames_distinct /
    #     _anchor_consistency: per-cell gates over a grid sheet. Not
    #     applicable to a single-portrait output.
    if not getattr(args, "verify", True):
        logger.warning("--no-verify opted out; output not validated")
        return 0

    final_path = work_dir / f"{name}.png"
    if not final_path.exists():
        return _emit_verifier_result(
            gates_run=[],
            failures=[{"check": "asset_exists", "file": str(final_path), "details": "missing"}],
            elapsed_seconds=0.0,
        )
    started_verify = time.perf_counter()
    gates_run: list[str] = []
    failures: list[dict] = []
    try:
        gates_run.append("verify_no_magenta")
        result = verify_no_magenta(final_path)
        if not result.get("passed", True):
            failures.append({"check": "verify_no_magenta", "file": str(final_path), "details": result})
    except Exception as e:  # pragma: no cover - defensive
        failures.append({"check": "verify_no_magenta", "file": str(final_path), "details": f"error: {e}"})
    elapsed = time.perf_counter() - started_verify
    return _emit_verifier_result(gates_run=gates_run, failures=failures, elapsed_seconds=elapsed)


def run_pipeline(args: argparse.Namespace) -> int:
    """Portrait pipeline entry point.

    When ``--output-dir`` is set, the directory is preserved (user owns
    its lifecycle). When unset, a ``tempfile.TemporaryDirectory`` is
    created and reaped on exit (ADR-200).
    """
    name = args.name or (_snake_case(args.display_name) if args.display_name else "unnamed_portrait")
    if args.output_dir:
        return _run_pipeline_body(args, Path(args.output_dir), name)
    with tempfile.TemporaryDirectory(prefix=f"portrait_{name}_") as td:
        return _run_pipeline_body(args, Path(td), name)


def _run_portrait_loop_body(args: argparse.Namespace, work_dir: Path, name: str) -> int:
    """Portrait-loop pipeline body. ``work_dir`` lifetime is bounded by caller.

    See ADR-200: when ``--output-dir`` is set the user owns the
    directory; otherwise the caller wraps this in a
    ``tempfile.TemporaryDirectory`` that reaps on exit.
    """
    work_dir.mkdir(parents=True, exist_ok=True)

    started = datetime.now(timezone.utc)
    phases: list[dict] = []

    cell = args.loop_cell_size  # default 512
    canvas = cell * 2  # 1024 by default

    # Phase A1: prompt
    prompt_path = work_dir / f"{name}_prompt.txt"
    metadata_path = work_dir / f"{name}_prompt.json"
    prompt_argv = [
        "build-portrait-loop",
        "--style",
        args.style,
        "--description",
        args.description or args.display_name or "",
        "--seed",
        str(args.seed),
        "--output",
        str(prompt_path),
        "--metadata-out",
        str(metadata_path),
    ]
    if args.archetype:
        prompt_argv.extend(["--archetype", args.archetype])
    if args.gimmick:
        prompt_argv.extend(["--gimmick", args.gimmick])
    if args.tier:
        prompt_argv.extend(["--tier", args.tier])
    if args.style_string:
        prompt_argv.extend(["--style-string", args.style_string])
    rc = sprite_prompt.main(prompt_argv)
    if rc != 0:
        return rc
    phases.append({"phase": "A1", "name": "prompt-build", "rc": rc})

    # Phase A2: generate (or fixture in dry-run).
    # Portrait-loop produces a 2x2 grid (canvas = cell * 2), which is square by
    # construction. We MUST NOT call `generate-portrait` here -- that subcommand
    # forces aspect_ratio="4:5" which crops the bottom row of the grid. Use
    # `generate-character` instead (aspect_ratio="1:1") so the backend returns
    # a square sheet matching our cell layout.
    raw_path = work_dir / f"{name}_raw.png"
    if args.dry_run:
        _make_fixture_portrait_loop(raw_path, cell=cell)
        phases.append({"phase": "A2", "name": "generate", "rc": 0, "dry_run": True})
    else:
        gen_argv = [
            "generate-character",
            "--prompt-file",
            str(prompt_path),
            "--output",
            str(raw_path),
            "--seed",
            str(args.seed),
        ]
        rc = sprite_generate.main(gen_argv)
        if rc != 0:
            return rc
        phases.append({"phase": "A2", "name": "generate", "rc": rc})

    # Phase D: per-cell extract + bg removal.
    # Use sprite_process.slice_grid_cells: derives cell pitch from the actual
    # raw size (cols * cell_size if exact, raw_size/cols otherwise) instead of
    # assuming the raw is already a clean canonical canvas. Image-gen backends
    # routinely return sizes like 1254x1254 for an 8x8 grid; a whole-image
    # resize before slicing is the bug we are NOT doing here.
    # Context-managed open: close the source PNG handle once we have
    # the in-memory RGBA copy (ADR-200 file-handle hygiene).
    with Image.open(raw_path) as raw_im:
        sheet = raw_im.convert("RGBA")
    raw_frames: list[Image.Image] = [c.convert("RGBA") for c in sprite_process.slice_grid_cells(sheet, 2, 2, cell)]
    phases.append(
        {
            "phase": "D",
            "name": "extract",
            "rc": 0,
            "frames": 4,
            "raw_size": list(sheet.size),
            "canvas_size": canvas,
        }
    )

    # Phase E: bg removal per cell
    nobg_frames: list[Image.Image] = []
    for fr in raw_frames:
        # Use the same despill+fade+dilate chain as the spritesheet pipeline.
        p1 = sprite_process.chroma_pass1(fr, sprite_process.MAGENTA, args.chroma_threshold)
        p2 = sprite_process.chroma_pass2_edge_flood(
            p1,
            sprite_process.MAGENTA,
            sprite_process.DEFAULT_PASS2_THRESHOLD,
            despill_strength=sprite_process.DEFAULT_DESPILL_STRENGTH,
        )
        if sprite_process.HAS_NUMPY:
            import numpy as np  # local import; matched to sprite_process

            arr = np.array(p2.convert("RGBA"))
            arr = sprite_process.alpha_fade_magenta_fringe(arr)
            arr = sprite_process.color_despill_magenta(arr)
            # Interior magenta spill (catches full-opacity pink streaks the
            # generator painted INSIDE the silhouette). Must run BEFORE
            # kill_pink_fringe so neutralized pixels are not re-classified.
            arr = sprite_process.neutralize_interior_magenta_spill(arr)
            arr = sprite_process.dilate_alpha_zero(arr, sprite_process.DEFAULT_ALPHA_DILATE_RADIUS)
            # Final pink-fringe alpha kill at silhouette edges.
            arr = sprite_process.kill_pink_fringe(arr)
            p2 = Image.fromarray(arr, "RGBA")
        nobg_frames.append(p2)
    phases.append({"phase": "E", "name": "remove-bg", "rc": 0})

    # Phase F: ground-line anchor across the 4 frames (drift-free)
    ground_line_y = sprite_process.detect_ground_line(nobg_frames, cell)
    anchored_frames: list[Image.Image] = [
        sprite_process.apply_ground_line_anchor(fr, ground_line_y, cell, cell) for fr in nobg_frames
    ]
    phases.append(
        {
            "phase": "F",
            "name": "anchor",
            "rc": 0,
            "ground_line_y": ground_line_y,
        }
    )

    # Phase H: assemble outputs
    out_dir = work_dir / "out"
    out_dir.mkdir(parents=True, exist_ok=True)

    sheet_out = Image.new("RGBA", (cell * 2, cell * 2), (0, 0, 0, 0))
    for i, fr in enumerate(anchored_frames):
        r, c = divmod(i, 2)
        sheet_out.paste(fr, (c * cell, r * cell), fr)
    sheet_out.save(out_dir / f"{name}_sheet.png", format="PNG")

    # Per-frame PNGs
    frames_dir = out_dir / f"{name}_frames"
    frames_dir.mkdir(parents=True, exist_ok=True)
    for i, fr in enumerate(anchored_frames):
        fr.save(frames_dir / f"{name}_frame_{i:02d}.png", format="PNG")

    # Animated WebP (full 8-bit alpha; preferred output). No palette
    # quantization, so silhouettes stay clean.
    webp_path = out_dir / f"{name}.webp"
    anchored_frames[0].save(
        webp_path,
        save_all=True,
        append_images=anchored_frames[1:],
        duration=200,
        loop=0,
        format="WebP",
    )

    # Animated GIF (200ms per frame = 800ms loop) — compatibility fallback.
    # Matte-composite each frame over neutral mid-gray BEFORE quantizing.
    # See sprite_process.matte_composite docstring for the rationale.
    gif_path = out_dir / f"{name}.gif"
    gif_imgs = [
        sprite_process.matte_composite(fr, matte=(40, 40, 40)).convert("P", palette=Image.Palette.ADAPTIVE)
        for fr in anchored_frames
    ]
    gif_imgs[0].save(
        gif_path,
        save_all=True,
        append_images=gif_imgs[1:],
        duration=200,
        loop=0,
        optimize=False,
        disposal=2,
    )
    phases.append({"phase": "H", "name": "assemble", "rc": 0})

    # Metadata sidecar
    sidecar = {
        "name": name,
        "mode": "portrait-loop",
        "display_name": args.display_name,
        "seed": args.seed,
        "style_preset": args.style,
        "archetype": args.archetype,
        "gimmick": args.gimmick,
        "tier": args.tier,
        "frame_count": 4,
        "cell_size": cell,
        "canvas_size": canvas,
        "ground_line_y": ground_line_y,
        "frame_duration_ms": 200,
        "loop_duration_ms": 800,
        "dry_run": args.dry_run,
        "started_at": started.isoformat(),
        "completed_at": datetime.now(timezone.utc).isoformat(),
        "phases": phases,
        "output_dir": str(out_dir),
    }
    (work_dir / f"{name}_metadata.json").write_text(json.dumps(sidecar, indent=2), encoding="utf-8")

    logger.info(
        "[portrait-loop] PASS: %s written to %s (4 frames, ground_line_y=%s)",
        name,
        out_dir,
        ground_line_y,
    )

    # Phase I: verifier gates (ADR-199). Portrait-loop runs the gate subset
    # that applies to animated 2x2 frames:
    #   - verify_no_magenta: residual chroma bleed
    #   - verify_frames_have_content: catches a blank cell (the despill
    #     chain ate one of the four frames)
    #   - verify_frames_distinct: catches the "all four frames identical"
    #     failure (ground-line anchor with zero variation = no animation)
    #   - verify_anchor_consistency: catches drift across the loop
    #
    # verify_grid_alignment is not run because portrait-loop frames are
    # tightly framed faces; the alignment gate's "character touches cell
    # edge" failure pattern doesn't apply when the pose deliberately fills
    # the cell vertically (head + shoulders).
    # verify_pixel_preservation is not run because the raw is upstream of
    # per-cell extraction here -- there is no canonical raw-sheet to
    # final-sheet pair on disk in this pipeline (raw_path is the whole
    # canvas, not a sheet at the same grid pitch as out/{name}_sheet.png).
    if not getattr(args, "verify", True):
        logger.warning("--no-verify opted out; output not validated")
        return 0

    sheet_path = out_dir / f"{name}_sheet.png"
    if not sheet_path.exists():
        return _emit_verifier_result(
            gates_run=[],
            failures=[{"check": "asset_exists", "file": str(sheet_path), "details": "missing"}],
            elapsed_seconds=0.0,
        )
    started_verify = time.perf_counter()
    gates_run: list[str] = []
    failures: list[dict] = []

    def _record(name_: str, result: dict) -> None:
        gates_run.append(name_)
        if not result.get("passed", True):
            failures.append({"check": name_, "file": str(sheet_path), "details": result})

    cols, rows = 2, 2
    try:
        _record("verify_no_magenta", verify_no_magenta(sheet_path))
    except Exception as e:  # pragma: no cover - defensive
        failures.append({"check": "verify_no_magenta", "file": str(sheet_path), "details": f"error: {e}"})
    try:
        _record(
            "verify_frames_have_content",
            verify_frames_have_content(sheet_path, cols, rows, cell),
        )
    except Exception as e:  # pragma: no cover - defensive
        failures.append({"check": "verify_frames_have_content", "file": str(sheet_path), "details": f"error: {e}"})
    try:
        # Portrait-loop frames are intentionally near-identical (subtle
        # breath + blink). Use the same relaxed dup_pct threshold the
        # verify_asset_outputs orchestrator uses for portrait-loop mode
        # (max_duplicate_pct=100.0); the gate then only fires if EVERY
        # cell is byte-identical, which would itself be a pipeline bug.
        _record(
            "verify_frames_distinct",
            verify_frames_distinct(sheet_path, cols, rows, cell, max_duplicate_pct=100.0),
        )
    except Exception as e:  # pragma: no cover - defensive
        failures.append({"check": "verify_frames_distinct", "file": str(sheet_path), "details": f"error: {e}"})
    try:
        # Portrait-loop has a fixed camera, so drift is more obvious; use
        # the tighter 4px stddev threshold from verify_asset_outputs.
        _record(
            "verify_anchor_consistency",
            verify_anchor_consistency(sheet_path, cols, rows, cell, max_centroid_y_stddev_px=4.0),
        )
    except Exception as e:  # pragma: no cover - defensive
        failures.append({"check": "verify_anchor_consistency", "file": str(sheet_path), "details": f"error: {e}"})
    elapsed = time.perf_counter() - started_verify
    return _emit_verifier_result(gates_run=gates_run, failures=failures, elapsed_seconds=elapsed)


def run_portrait_loop(args: argparse.Namespace) -> int:
    """Portrait-loop pipeline entry point.

    Phases:
      A1: prompt build (build-portrait-loop)
      A2: backend dispatch (Codex CLI; or fixture in dry-run) — produces a
          1024x1024 PNG with 2x2 cells (512x512 each)
      D:  per-cell extract + per-cell bg removal
      F:  ground-line anchor across the 4 frames (drift-free)
      H:  PNG sheet + animated GIF + animated WebP + per-frame PNGs

    When ``--output-dir`` is set, the directory is preserved (user owns
    its lifecycle). When unset, a ``tempfile.TemporaryDirectory`` is
    created and reaped on exit (ADR-200).
    """
    name = args.name or (_snake_case(args.display_name) if args.display_name else "portrait_loop")
    if args.output_dir:
        return _run_portrait_loop_body(args, Path(args.output_dir), name)
    with tempfile.TemporaryDirectory(prefix=f"portrait_loop_{name}_") as td:
        return _run_portrait_loop_body(args, Path(td), name)


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--prompt", help="Free-form prompt; alternative to --description")
    parser.add_argument("--description", help="Character description text")
    parser.add_argument("--display-name", help="Character display name (e.g., 'Bangkok Belle Nisa')")
    parser.add_argument("--name", help="Override snake_case ID (default: derived from --display-name)")
    parser.add_argument("--style", default="slay-the-spire-painted")
    parser.add_argument("--style-string", help="Free-form style fragment for --style custom")
    parser.add_argument("--archetype", help="powerhouse, technical, high-flyer, ...")
    parser.add_argument("--gimmick", help="face, heel, manager, referee, ...")
    parser.add_argument("--tier", choices=["act1", "act2", "act3"])
    parser.add_argument("--seed", type=int, default=0)
    parser.add_argument(
        "--output-dir",
        help=(
            "Working output directory. When unset, a temporary directory "
            "is created and cleaned up automatically. When set, the "
            "directory is preserved (you own its lifecycle)."
        ),
    )
    parser.add_argument("--target", choices=["road-to-aew", "local"], default="local")
    parser.add_argument("--target-dir", help="Override road-to-aew root (default: ~/road-to-aew)")
    parser.add_argument("--player", choices=["male", "female"], help="Deploy as player sprite")
    parser.add_argument("--regen-manifest", action="store_true", help="Run npm run generate:sprites after deploy")
    parser.add_argument(
        "--bg-mode",
        choices=list(sprite_bg.BG_MODE_CHOICES),
        default="chroma",
        help=(
            "Background removal (ADR-204 unified vocabulary): "
            "chroma=two-pass magenta despill (default), "
            "gray-tolerance=road-to-aew #3a3a3a algorithm, "
            "rembg=opt-in ML, auto=chroma with rembg fallback."
        ),
    )
    parser.add_argument("--chroma-threshold", type=int, default=30)
    parser.add_argument("--target-w", type=int, default=600)
    parser.add_argument("--target-h", type=int, default=980)
    parser.add_argument("--force-dimensions", action="store_true")
    parser.add_argument(
        "--dry-run", action="store_true", help="Skip backend; use synthetic fixture for post-processing"
    )
    parser.add_argument(
        "--verify",
        action=argparse.BooleanOptionalAction,
        default=True,
        help=(
            "Run verifier gates as the last pipeline step (default ON). "
            "Portrait gates: verify_no_magenta. Portrait-loop gates: "
            "verify_no_magenta, verify_frames_have_content, "
            "verify_frames_distinct, verify_anchor_consistency. "
            "On failure, prints structured JSON to stdout and exits with "
            "code 2. Opt out with --no-verify (logs WARNING). "
            "See ADR-199 for the contract."
        ),
    )
    parser.add_argument(
        "--mode",
        choices=["portrait", "portrait-loop"],
        default="portrait",
        help=(
            "portrait (default): single static PNG. "
            "portrait-loop: 2x2 = 4-frame subtle idle (breathing + blink); "
            "outputs sheet, GIF, WebP, per-frame PNGs."
        ),
    )
    parser.add_argument(
        "--loop-cell-size",
        type=int,
        default=512,
        help="Cell size for portrait-loop mode (default 512 → 1024x1024 canvas).",
    )
    # Logging level controls (ADR-202). Mutually exclusive; default INFO.
    log_group = parser.add_mutually_exclusive_group()
    log_group.add_argument(
        "--quiet",
        "-q",
        action="store_true",
        help="Suppress INFO log records; only emit WARNING and above on stderr.",
    )
    log_group.add_argument(
        "--verbose",
        "-v",
        action="store_true",
        help="Emit DEBUG-level diagnostic log records on stderr.",
    )
    return parser


def configure_logging(quiet: bool, verbose: bool) -> None:
    """Configure the root logger for sprite-pipeline scripts (ADR-202).

    --quiet → WARNING, --verbose → DEBUG, default → INFO. Records are
    formatted as ``[<logger-name>] LEVEL: message`` and written to stderr
    so structured stdout (verifier JSON, generated paths) stays clean.
    """
    level = logging.WARNING if quiet else (logging.DEBUG if verbose else logging.INFO)
    logging.basicConfig(
        level=level,
        format="[%(name)s] %(levelname)s: %(message)s",
        stream=sys.stderr,
        force=True,
    )


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    configure_logging(quiet=args.quiet, verbose=args.verbose)
    if not args.description and args.prompt:
        args.description = args.prompt
    if args.mode == "portrait-loop":
        return run_portrait_loop(args)
    return run_pipeline(args)


if __name__ == "__main__":
    sys.exit(main())
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall