pixellab-pip: Instructions file for Codex

PixelLab Pip is an unofficial, agent-agnostic PixelLab workflow router shipped as a portable Agent Skill. It teaches coding agents to choose between documented PixelLab MCP tools, REST v2 endpoints, website/editor fallback, Aseprite, Pixelorama, and local asset assembly. The repository is mostly Markdown because the product is the routing contract itself — task detection, prompt normalization, image-role classification, credential handling, usage reporting, localization, and specialty workflows for sprites, tilesets, layered characters, edits, animation, and completion sounds — plus helper scripts, QA, and packaging manifests.

Project rules:

• Apply KISS and YAGNI to agent-facing/runtime and implementation work: additions, fixes, tests, tooling, manifests, and refactors. Make the smallest complete change that satisfies the current requirement without weakening functionality, correctness, safety, or efficiency. Shorter is not automatically better — challenge every cut and every addition.
• Add only what the current task requires, using verified PixelLab behavior where relevant and preserving applicable safety/correctness constraints. No speculative future-proofing, unused outputs/formats, compatibility paths without a current requirement, redundant examples, or optional machinery.
• Before planning or delegating agent-facing edits, read the target and relevant canonical guidance. Keep each runtime rule in one place (SKILL.md if global; one reference if specific) and retain it only if it adds an agent decision, action, safety boundary, or verification step. Otherwise consolidate or point to the existing rule. Apply this test to plans and subagent output; check the final diff for duplication before QA/commit.
• Reuse and simplify existing structure before creating a file, section, workflow, example, schema mapping, or helper. When new guidance replaces old guidance, remove the obsolete text in the same change.
• The KISS/YAGNI, runtime-content, canonical-placement, and reuse/consolidation rules above do not apply to docs/. docs/ is user-facing; follow the user's request and the document's own requirements.
• Never weaken protections for routing accuracy, public-vs-private PixelLab endpoint boundaries, secret/auth safety, paid-credit control, output integrity, or user trust. Simplify them through consolidation.
• Never write personal or machine-specific data into a non-gitignored file or commit message, docs/ included: the user's real absolute or home paths, OS username, location or timezone, email, hostname or IP, or anything else that identifies the user or their machine — availability is never a reason to record it. Use repo-relative paths and placeholders; if neither fits, omit the value. Gitignored paths (.local/, pixellab-pip-generations/) are exempt; secret and token values are not, and stay out of every file.

Content placement (progressive discovery):

• skills/pixellab-pip/SKILL.md — agent-facing canonical contract and lean router: triggers, guardrails, surface selection, pointers. It must classify common requests and point directly to any required reference.
• skills/pixellab-pip/references/*.md — agent-facing operational contracts loaded on demand: durable routing rules, schema mappings, safety constraints, verification. Never restate SKILL.md globals (it is always co-loaded); use a pointer.
• docs/ — human/developer research, evidence, and background; not required for normal runtime routing. Promote a finding into SKILL.md or references/ only when it changes agent behavior. (docs/pixellab/ terminology and routing research; docs/tools/ integration background; docs/developer.md repo structure and local install; docs/showcase/README.md showcase rules.)
• .local/ — temporary agent-generated or cache files.

Validate every edit: python dev-tools/qa.py (includes the unit tests). Commits: conventional <type>[optional scope]: <description>. Record user-facing changes under [Unreleased] in CHANGELOG.md; release steps: docs/developer.md#changelog.