nccgs 2.1.1 → 3.0.0-rc.2

package/template/skills/feedback/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: feedback
+description: Send or prepare a feedback bundle for the NCCGS maintainers (what ran, what failed, what was blocked, tokens per task) with the person's note, and set the consent level (auto / manual / off). Use when something went wrong, when NCCGS suggests it, or when the session asks for consent.
+allowed-tools: Read, Bash, AskUserQuestion
+---
+
+# /feedback
+
+A bundle holds versions, doctor, per-task numbers, diagnostics and the person's note. No source code, screenshots, transcripts or credentials; project name and task titles are included. Where it goes is `feedback.endpoint` in `.nccgs/project.json`; a copy always stays under `.nccgs/feedback/`.
+
+1. **Consent first.** If `.nccgs/project.json` has `feedback.consent: "ask"` (or the session told you consent is not set), ask once with AskUserQuestion — options `auto` (send by itself when an issue is detected or every 7 days), `manual` (only suggest), `off` (never) — then `npx nccgs feedback --project . --consent <choice>`. `off` ends here.
+2. **What happened.** Ask in one question what to report (a problem now, an impression after some days, or the periodic bundle) and whether to include reports.
+3. `npx nccgs feedback --project . --since <days> --note "<their words>" [--with-reports] --send` (omit `--send` when they only want the file). The `.md` path and the send result print on stderr.
+4. Tell the person the three numbers (tasks closed / failed verifications / diagnostics), the top diagnostic line, whether it was sent (and the id) or where the file is.
+
+Never add `--send` without the person's yes in this session unless consent is `auto`.

package/template/skills/map-systems/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: map-systems
+description: Break the brief into systems and an ordered slice plan of measurable tasks (.nccgs/design/systems.md and slice.json) that /vertical-slice executes. Use after /brainstorm, or when a feature needs more than one task.
+allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion
+---
+
+# /map-systems
+
+Output: `.nccgs/design/systems.md` (the map) and `.nccgs/design/slice.json` (the plan), validated by `node .claude/nccgs/runtime/task/task.mjs plan --validate .nccgs/design/slice.json`.
+
+## Systems map
+
+From `.nccgs/design/brief.md` list the systems (3–6 for a slice): name, responsibility in one line, what it owns (state), what it reads from others, Unity surface (MonoBehaviour / plain C# / asset). Put the pure logic (timers, rules, spawning math) in plain C# classes so EditMode tests cover it without a scene. Note the two riskiest couplings.
+
+## Slice plan rules
+
+- 3–6 tasks, each one session of work, each closing with its own evidence. Order by risk: task 1 proves the tooling path (scene loads, input reaches the game, a screenshot shows something), later tasks add mechanics, the last adds feedback/HUD.
+- Every task is a full contract (see `protocols/evidence.md`): `id`, `title`, `files` in scope, `criteria` with assertions on artifacts `task verify` produces (`<id>-tests.json`, `<id>-playmode.json`, `<id>-console.json`, `<id>-observe.json`, `screens/<id>/NN.png`, `<id>-playtest-<name>.json`), `notes` (how to try it), `rigor`, `dependsOn`.
+- Numbers from the brief go into criteria as thresholds (coyote 0.10 s → an EditMode test at 0.08 s passes and 0.15 s fails). A subjective decision becomes a `kind: "manual"` criterion plus a playtest spec, never a vague assertion.
+- Each task has at least one observe criterion with a screenshot that can show the change; use `--shots` timing when the change lasts under a second.
+- Scope only files the task needs; the report marks anything else as outside the contract.
+
+Write `slice.json` as `{ "schemaVersion": 1, "name": "...", "tasks": [ ... ] }`, run the validator, fix what it reports. Show the user the task list (id, title, what it proves) with AskUserQuestion before finishing; move or merge tasks if they ask.
+
+End with: both paths, the validator result and `next: /vertical-slice` (or `/work` with `task open --plan <id>` for one task).

package/template/skills/playtest/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: playtest
+description: Measure how the game plays - run a scripted playtest with telemetry in the live Editor, have the playtester judge feel with evidence, and give the user options. Use for "does it feel right", tuning, difficulty, fairness questions.
+allowed-tools: Read, Glob, Grep, Write, Bash, Agent, AskUserQuestion
+---
+
+# /playtest
+
+Output: a playtest artifact under `.nccgs/evidence/measurements/`, the playtester's judgement, and a decision by the user.
+
+1. State the question in one line (what feel, which number or rule). Read `.claude/nccgs/protocols/playtest.md`.
+2. Write the spec to `.nccgs/design/playtests/<name>.json`: duration, key pattern or timeline, probes on the game's public static members (distance, alive, speed, counters), `stopWhen`. Two or three specs when the question compares behaviours (e.g. presses every 0.9 s vs 0.6 s, or seeds).
+3. Run each against an open task (open a `prototype` task `PT-<name>` if none is open): `node .claude/nccgs/runtime/task/task.mjs verify --id <task> --kind playtest --spec <file>`; add `--kind observe --shots ...` when the question is visual.
+4. Invoke the `nccgs-playtester` subagent with the artifact paths and the question. It returns the numbers, the judgement and 2–4 options.
+5. Put the options to the user with AskUserQuestion, with the evidence next to each. Record the decision in `.nccgs/state.md` (one line) through `task close --outcome partial --decide ...` of the prototype task, or in the open task's notes.
+
+Never tune a number without the user's decision; never report a feel judgement without the artifact behind it.

package/template/skills/status/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: status
+description: Read-only status of this NCCGS project - open tasks and their criteria, latest evidence and reviews, recent decisions, Unity/Editor state, pending updates, and the next concrete action. Use for "where are we", "status", "what's open", "what's next".
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# /status
+
+Output: a short status in prose (no more than ten lines) ending with one concrete next action. Do not change anything.
+
+0. `node .claude/nccgs/runtime/task/task.mjs project` → rewrites `.nccgs/project.html` (every task, open findings, tokens) and prints the counts. Mention the file path once so the user can open it.
+1. `node .claude/nccgs/runtime/task/task.mjs list` → open tasks. For each open task, `inspect --id <id>` → criteria pass/fail/unverified, `stale` (source changed since last verify), reviews passed vs needed, fix rounds used.
+2. `.nccgs/state.md` → the last three closed tasks and decisions.
+3. `unity status --format json` → which Editor is open for this project and whether Pipeline is `ready`.
+4. `.nccgs/cache/update-check.json` (if present) → pending NCCGS / Unity Skills / Unity CLI updates. Mention them in one line; never apply them.
+5. `.nccgs/events.jsonl` (last 20 lines) → recent agent calls and their models.
+
+Report: what is open and how close it is to closing, what evidence is missing, what the user still has to decide, and the single next command or question. If nothing is open, say what the last closed task was and suggest the next step from `state.md`.

package/template/skills/test/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: test
+description: Run or write Unity tests and runtime checks for this project and record them as task evidence - EditMode/PlayMode tests in the live Editor or a batch Editor, Play Mode observation with screenshots, console checks. Use for "run the tests", "does it still work", "add a test for X", "check the console".
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent
+---
+
+# /test
+
+Output: measurements under `.nccgs/evidence/measurements/` and screenshots under `.nccgs/evidence/screens/`, attached to a task, plus a short reading of what they show. If no task is open, open one with rigor `prototype` named after the check so the evidence has a home.
+
+## Run what exists
+
+```
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind tests --mode editor
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind tests --mode playmode --filter <Namespace.Class>
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind observe --keys Space --frames 2
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind console
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind command --name build -- unity build . --editor-version <ver>
+```
+Live Editor open → Pipeline `test run` (results in seconds, no domain reload for EditMode). No Editor → batch `unity test` with the project's own `--editor-version` (minutes; refuses if the project is open elsewhere).
+
+Read the result: `tests.json` has `passed/failed/skipped` and `failures[]` with messages. A failed test is a fact about the code until proven otherwise; do not weaken an assertion to make it pass.
+
+## Write a test
+
+- Put EditMode tests under `Assets/Tests/EditMode/` and PlayMode tests under `Assets/Tests/PlayMode/` (create the `.asmdef` with the Test Framework references if missing; check `Packages/manifest.json` for `com.unity.test-framework`).
+- Map each test to a criterion id in its name or a comment (`// criterion: dash-iframe`).
+- Test behaviour through the public surface the player feels (input → state → output), not private fields. Use `[UnityTest]` with `yield return null` for anything that needs frames.
+- Keep EditMode tests free of scene state; use PlayMode for physics, input and timing. A forgiveness mechanic (coyote time, input buffer) is a timing test: advance frames and assert the window, do not assert the implementation.
+- After adding tests, `unity command script recompile` then `unity command console status` must report `compilationFailed: false` before running.
+
+## Observe
+
+`--kind observe` enters Play Mode, waits, optionally presses keys, captures Game-view screenshots, reads the console, exits. Always open the screenshots with the Read tool and describe them; an all-blue screen on an empty scene is correct, a black or clipped one is a finding. On Unity 6.3 the Pipeline server drops for ~3 s after entering Play Mode; `verify` already waits, custom scripts must too.

package/template/skills/unity-foundation/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: unity-foundation
+description: Set up or audit a Unity project's baseline for NCCGS work - assembly definitions, EditMode and PlayMode test assemblies, input package, render pipeline, a smoke scene - as a measured task. Use on a fresh project or when tests cannot run.
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
+---
+
+# /unity-foundation
+
+Output: a closed task `FOUNDATION` whose evidence proves the project can run the loop, and `.nccgs/design/foundation.md` recording what exists.
+
+1. Audit, read-only: `Packages/manifest.json` (input system or legacy input, render pipeline, test framework, `com.unity.pipeline`), `Assets/` layout, existing `.asmdef`, existing tests, scenes in Build Settings, `ProjectSettings/ProjectVersion.txt`. Write the findings to `.nccgs/design/foundation.md` (present / missing / decision needed).
+2. Ask the user only about real forks: Input System vs legacy input when neither is set up, 2D vs 3D physics when unclear, which scene is the smoke scene.
+3. Open the task: `node .claude/nccgs/runtime/task/task.mjs open --id FOUNDATION --title "Project foundation" --rigor production --files "Assets/Scripts/Game.asmdef,Assets/Tests/EditMode/,Assets/Tests/PlayMode/,Assets/Scenes/<smoke>.unity" --criteria-json '[...]'` with criteria: `editmode` (a smoke EditMode test passes, `/passed gte 1`), `playmode` (a smoke PlayMode test loads the smoke scene, `--name playmode`), `compiles` (console ground truth), `observe` (Play Mode enters and exits with 0 exceptions, one screenshot).
+4. Create only what is missing: `Assets/Scripts/Game.asmdef` (runtime), `Assets/Tests/EditMode/Game.Tests.EditMode.asmdef` and `Assets/Tests/PlayMode/Game.Tests.PlayMode.asmdef` (test assemblies referencing Game, UnityEngine.TestRunner, UnityEditor.TestRunner, nunit precompiled, `UNITY_INCLUDE_TESTS`), one smoke test in each, and nothing else. Do not add packages without asking; `com.unity.pipeline` is installed with `unity pipeline install --project-path .` after the user agrees.
+5. Verify, review, close as in `/work`. Record in `foundation.md` the versions and the decisions taken.
+
+End with: the report path and what the next skill needs (`/brainstorm` for a new game, `/work` for a feature).

package/template/skills/vertical-slice/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: vertical-slice
+description: Execute the slice plan task by task - open each planned contract, run the full /work loop, stop at the first partial or blocked, finish with the project page and a changelog. Use after /map-systems.
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion
+---
+
+# /vertical-slice
+
+Output: every task in `.nccgs/design/slice.json` closed, in order, each with its report; then `.nccgs/project.html` and a release note.
+
+Loop:
+1. `node .claude/nccgs/runtime/task/task.mjs plan` → the plan status. If a task is `open`, continue it. If none is `ready`, stop and report.
+2. `node .claude/nccgs/runtime/task/task.mjs open --plan` opens the next ready task with its planned contract. Then run the `/work` loop from step 2 (edit) onward for that task — same rules, same evidence, same review. Read the planned `notes` and `criteria` before editing; the plan is the brief.
+3. On `close --outcome success`: continue with the next task. On `partial`, `blocked` or exhausted fix rounds: stop, say which task and why, and what the user must decide. Never skip a task or reorder without asking.
+4. After the last task: `node .claude/nccgs/runtime/task/task.mjs project` and `npx nccgs release --project . --from <date the slice started> --name <slice name>`; give the user both paths and the three numbers per task (criteria, tests, review).
+
+Budget: one task per context window is normal. If the context is getting long, close the current task first; the next session picks up from `plan`.

package/template/skills/work/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: work
+description: Implement a feature, fix or change in this Unity project end to end - contract, edit, run, look, fix, independent review, close, report. Use for any request that changes code, scenes, prefabs or assets ("add", "implement", "fix", "change", "make X do Y").
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Agent, AskUserQuestion
+---
+
+# /work
+
+Output: a closed task with a one-page report under `.nccgs/reports/<id>.md`, or an honest `partial`/`blocked` report. Stop when `task close` succeeds, when the fix rounds are exhausted, or when a decision needs the user.
+
+## 1. Brief and contract (before editing anything)
+
+1. Restate the request in three lines: outcome, what the player will see, what must not change. Read `.nccgs/state.md` for decisions already made.
+2. If the request involves a subjective choice (mechanic, feel, layout, tuning numbers), present 2-4 options with trade-offs using AskUserQuestion. Do not pick for the user.
+3. Decide rigor: `prototype` (no review, up to 6 fix rounds) for throwaway or exploration, `production` (one review) for anything that stays, `release` (two reviews) for release-critical. Default comes from `.nccgs/project.json`.
+4. Write criteria as measurable assertions (see `.claude/nccgs/protocols/evidence.md`). Each criterion points at an artifact `task verify` will produce. A player-visible change gets the `observe` criterion automatically at rigor ≥ production.
+5. Open the task. If `.nccgs/design/slice.json` has this work planned, `node .claude/nccgs/runtime/task/task.mjs open --plan <id>` opens it with the planned contract (flags still override); otherwise:
+   ```
+   node .claude/nccgs/runtime/task/task.mjs open --title "..." --rigor production --files "Assets/Scripts/Player/Dash.cs,Assets/Scenes/Arena.unity" --criteria-json '[...]' --notes "How to try it: ..."
+   ```
+   Keep the returned task id; every later command uses it.
+
+## 2. Edit
+
+- Read the affected flow first (callers, shared state, serialization). Follow `.claude/nccgs/ponytail/engineering.md`.
+- Edit only files in scope. If the scope turns out to be wrong, say so and re-open with the right scope; do not creep.
+- Use `unity command` for scene/prefab/component changes. For C#, after editing run `unity command script recompile` and `unity command console status` to catch compile errors before any test.
+- Tasks that are too large for one context: delegate to the `nccgs-implementer` subagent with the task id, criteria and files; it runs the same loop and hands back.
+
+## 3. Run and look
+
+```
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind tests [--mode editor|playmode] [--filter Name]
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind observe [--keys Space] [--frames 3] [--match-log "\[Runner\] jump"]
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind observe --keys Space --hold-key 60 --shots 380,1200 --match-log "\[Runner\] jump"   # timed: frames at exact ms after the press
+node .claude/nccgs/runtime/task/task.mjs verify --id <id> --kind tests --mode playmode --name playmode   # writes <id>-playmode.json
+```
+`verify` picks the live Editor when one is open (Pipeline `test run`, screenshots, console) and a batch Editor otherwise. It prints the criteria status.
+
+Then **look**: open each screenshot under `.nccgs/evidence/screens/<id>/` with the Read tool and read the console summary in `.nccgs/evidence/measurements/<id>-observe.json`. Describe what you see in one line each. Decide from what is on screen.
+
+- Objective failure (red test, exception, wrong screen): fix it. `node .claude/nccgs/runtime/task/task.mjs fix --id <id>` counts the round; when it reports `exhausted`, stop and report partial.
+- Subjective doubt (feels wrong, layout questionable): ask the user with 2-4 options and the screenshot paths. Do not guess.
+- Feel/balance questions you can measure: write a playtest spec (`.claude/nccgs/protocols/playtest.md`), run `task verify --id <id> --kind playtest --spec <file>`, and hand the artifact to the `nccgs-playtester` subagent; it returns the judgement and options for the user.
+
+## 4. Independent review (rigor ≥ production)
+
+```
+node .claude/nccgs/runtime/task/task.mjs review --id <id>
+```
+This writes `.nccgs/evidence/review/<id>-prompt.md`. Invoke the `nccgs-reviewer` subagent with that file as its prompt (paste the file contents). When it has written the verdict file:
+```
+node .claude/nccgs/runtime/task/task.mjs review --id <id> --import --model <model it ran as>
+```
+CHANGES_REQUIRED: fix the findings (counts a fix round), re-verify, re-review. BLOCKED: report blocked with the reason.
+PASS with MEDIUM/LOW findings: fix what is cheap, then record each one you addressed with `task review --id <id> --resolve <index or title words> --reason "..."`; leave the rest open with no comment (the report lists them as open). Never resolve a finding you did not act on.
+
+## 5. Close and report
+
+```
+node .claude/nccgs/runtime/task/task.mjs close --id <id> --outcome success
+```
+`close` refuses `success` when a criterion fails, the source changed after the last verify, or the review is missing; then fix, re-verify, or close as `partial`/`blocked` with `--outcome`. It writes the report (`.nccgs/reports/<id>.md` and a self-contained `<id>.html` with the screenshots and token cost), refreshes `.nccgs/project.html` and updates `.nccgs/state.md`. End your reply with the report path and the three numbers the report leads with (criteria, tests, review); the token cost is in the report, do not estimate it yourself.
+
+Reply to the user with: the outcome, the report path, the two most important things you saw on screen, and any decision still open. Never write "DONE" for a task that is not closed.

package/tools/feedback-worker/README.md

@@ -0,0 +1,12 @@
+# NCCGS feedback receiver
+
+One Cloudflare Worker that turns a feedback bundle into a GitHub issue, so bundles can be read, labelled and closed like any other issue.
+
+Setup (once, by the maintainer):
+
+1. Create the repository `LacBird/nccgs-feedback` (private is fine). Labels are created on demand by the API.
+2. Create a fine-grained personal access token limited to that repository with **Issues: read and write** only.
+3. `npm i -g wrangler && wrangler login`, then in this folder: `wrangler secret put GITHUB_TOKEN`, optionally `wrangler secret put INGEST_KEY`, and `wrangler deploy`. The URL is `https://nccgs-feedback.<account>.workers.dev/v1/bundle`.
+4. Put that URL in `DEFAULT_CONFIG.feedback.endpoint` (`runtime/core/project.mjs`) before the next release, or users set `feedback.endpoint` in `.nccgs/project.json`.
+
+What a client sends: `{ bundle, markdown }` as built by `nccgs feedback` (≤ 512 KB). What the issue contains: the Markdown summary and, under a collapsed block, the JSON bundle. No code, screenshots, transcripts or credentials are in a bundle; project name and task titles are.

package/tools/feedback-worker/worker.js

@@ -0,0 +1,39 @@
+// NCCGS feedback receiver — a Cloudflare Worker. POST /v1/bundle {bundle, markdown} → one GitHub issue
+// in FEEDBACK_REPO. Secrets: GITHUB_TOKEN (fine-grained, Issues: read/write on that repo only).
+// Vars: FEEDBACK_REPO ("owner/name"). Optional: INGEST_KEY (clients send header x-nccgs-key).
+// Limits: 512 KB body, 20 bundles per IP per day (KV binding RATE optional; without it no limit).
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    if (request.method === "GET" && url.pathname === "/") return new Response("nccgs feedback receiver", { status: 200 });
+    if (request.method !== "POST" || url.pathname !== "/v1/bundle") return json({ error: "not found" }, 404);
+    if (env.INGEST_KEY && request.headers.get("x-nccgs-key") !== env.INGEST_KEY) return json({ error: "unauthorized" }, 401);
+    const len = Number(request.headers.get("content-length") || 0);
+    if (len > 512 * 1024) return json({ error: "too large" }, 413);
+    let payload; try { payload = await request.json(); } catch { return json({ error: "bad json" }, 400); }
+    const b = payload?.bundle;
+    if (!b || b.schemaVersion !== 1 || typeof payload.markdown !== "string") return json({ error: "bad bundle" }, 400);
+    if (env.RATE) {
+      const ip = request.headers.get("cf-connecting-ip") || "unknown";
+      const key = `rate:${ip}:${new Date().toISOString().slice(0, 10)}`;
+      const n = Number(await env.RATE.get(key) || 0);
+      if (n >= 20) return json({ error: "rate limited" }, 429);
+      await env.RATE.put(key, String(n + 1), { expirationTtl: 86400 });
+    }
+    const t = b.totals || {};
+    const topDiag = Object.entries(t.diagnostics || {}).sort((a, c) => c[1] - a[1])[0];
+    const title = `[feedback] nccgs ${b.nccgs} · ${(b.platform || "").split(" ")[0]} · ${t.closed ?? 0}/${t.tasks ?? 0} closed · ${t.failedVerifications ?? 0} failed verify${topDiag ? ` · ${topDiag[0]}×${topDiag[1]}` : ""}${b.trigger ? ` · ${b.trigger}` : ""}`;
+    const jsonText = JSON.stringify(b, null, 1);
+    const details = jsonText.length < 60000 ? `\n\n<details><summary>bundle.json</summary>\n\n\`\`\`json\n${jsonText}\n\`\`\`\n</details>` : `\n\n_bundle.json omitted (${jsonText.length} bytes); diagnostics count ${(b.diagnostics || []).length}._`;
+    const labels = ["feedback", `v${b.nccgs}`, ...(b.trigger && b.trigger !== "manual" ? ["auto"] : []), ...((t.failedVerifications ?? 0) > 0 || topDiag ? ["has-issues"] : [])];
+    const gh = await fetch(`https://api.github.com/repos/${env.FEEDBACK_REPO}/issues`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${env.GITHUB_TOKEN}`, accept: "application/vnd.github+json", "content-type": "application/json", "user-agent": "nccgs-feedback-worker", "x-github-api-version": "2022-11-28" },
+      body: JSON.stringify({ title: title.slice(0, 250), body: payload.markdown.slice(0, 60000) + details, labels })
+    });
+    if (!gh.ok) return json({ error: "github", status: gh.status, detail: (await gh.text()).slice(0, 300) }, 502);
+    const issue = await gh.json();
+    return json({ id: issue.number, url: issue.html_url }, 201);
+  }
+};
+const json = (o, status = 200) => new Response(JSON.stringify(o), { status, headers: { "content-type": "application/json" } });

package/tools/feedback-worker/wrangler.toml

@@ -0,0 +1,12 @@
+name = "nccgs-feedback"
+main = "worker.js"
+compatibility_date = "2026-01-01"
+
+[vars]
+FEEDBACK_REPO = "LacBird/nccgs-feedback"
+
+# secrets (set with `wrangler secret put`): GITHUB_TOKEN, optionally INGEST_KEY
+# optional rate limit:
+# [[kv_namespaces]]
+# binding = "RATE"
+# id = "<kv id>"

package/unity-skills/2d-pixel-perfect/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: 2d-pixel-perfect
+description: Sets up, diagnoses, and fixes pixel perfect 2D rendering with PixelPerfectCamera in URP or Built-in. Use when a retro-style or pixel art 2D game looks blurry, jittery, or misaligned. Not for HD 2D or high-resolution art.
+---
+
+Set up, diagnose, and fix pixel perfect 2D rendering in Unity projects.
+
+---
+
+## ⚠ There Are Two Completely Separate Implementations
+
+Pixel perfect rendering in Unity is **not one system** — it is two separate, incompatible implementations, one per render pipeline. **Always detect the pipeline before writing or diagnosing any code.** 
+
+| | URP | Built-in |
+|---|---|---|
+| **Component** | `UnityEngine.Rendering.Universal.PixelPerfectCamera` | `UnityEngine.U2D.PixelPerfectCamera` |
+| **Package** | Built into URP — no extra install | `com.unity.2d.pixel-perfect` v6.0.0+ |
+| **API style** | Enums (`gridSnapping`, `cropFrame`) | Booleans (`pixelSnapping`, `upscaleRT`, `cropFrameX/Y`) |
+
+**Do not install `com.unity.2d.pixel-perfect` in a URP project.**
+
+**→ Always call `DetectPipeline()` first** (`references/pipeline-detection.cs`), then branch your setup, diagnostics, and fixes based on the result.
+
+---
+
+## When NOT to use this skill
+
+- **HD 2D or high-resolution 2D games** — pixel snapping and point filtering will make smooth art look wrong
+- **UI-only scenes** — use Canvas Scaler instead
+- **HDRP projects** — Pixel Perfect Camera is not supported
+
+---
+
+## Critical Reminders
+
+⚠ **Detect the render pipeline first** — URP and Built-in use different Pixel Perfect Camera components that are not interchangeable.
+⚠ **Filter Mode = Point is the #1 fix** — bilinear filtering is Unity's default and is almost always the cause of blurry sprites.
+⚠ **Anti-Aliasing must be disabled** — in Quality Settings and on the camera. AA actively blurs pixel edges.
+
+## Key Principles
+
+### 1. Pipeline Detection & Camera Component Selection
+
+See the two-path comparison table at the top of this file. Assembly name note: the standalone Built-in package installs into a `Runtime/` folder, but the asmdef `"name"` field is `Unity.2D.PixelPerfect` — no `Runtime` suffix. HDRP is unsupported — see the HDRP fallback section under Common Issues.
+
+**→ Code: `references/pipeline-detection.cs`** — `DetectPipeline()`, `GetPixelPerfectCameraType()`, and migration mismatch check.
+
+### 2. Diagnostic-First Approach
+
+Always diagnose before making changes. Report findings, then fix only what is broken.
+
+### 3. Work in the correct scope
+
+Default to scene scope. Scan project-wide only when the user explicitly requests it.
+
+---
+
+## Diagnostic Checklist
+
+**Sprite import settings:**
+- [ ] Filter Mode = `Point (no filter)` on all in-scope sprites
+- [ ] Mip Maps = disabled
+- [ ] Compression = `None` / Uncompressed
+- [ ] PPU consistent across all sprites in scene
+- [ ] Sprite pivots set to Custom / Pixels mode — a center pivot on an odd-dimension sprite (e.g. 15×15) lands at 7.5px, causing 0.5px misalignment
+
+**→ Code: `references/sprite-settings.cs`** — `GetImporter()` and `FixSpriteImportSettings()`.
+
+**Editor snap settings:**
+- [ ] Grid Size = `1 / assetsPPU` on all axes (e.g. PPU 16 → 0.0625, PPU 100 → 0.01)
+- [ ] Grid Snapping enabled in the Grid and Snap overlay
+- [ ] To snap existing GameObjects: select them → Align Selected → All Axes
+
+**Camera setup:**
+- [ ] Camera projection = Orthographic
+- [ ] Pixel Perfect Camera component present and correct type for pipeline
+- [ ] `allowHDR`, `allowMSAA`, `allowDynamicResolution` all `false`
+- [ ] Scene view shows two green bounding boxes on the camera gizmo — solid = visible area, dotted = reference resolution
+
+**→ Code: `references/camera-setup-urp.cs`** — full URP camera + PP Camera configuration.
+**→ Code: `references/camera-setup-builtin.cs`** — Built-in standalone configuration.
+
+**Project quality settings:**
+- [ ] Anti-Aliasing = 0 in Quality Settings
+- [ ] Anisotropic Filtering = Disabled
+
+---
+
+## API Reference
+
+Full property/method tables, `GridSnapping` and `CropFrame` enum values, and recommended configurations:
+**→ `references/api-reference.md`** — read this when writing or reviewing camera setup code.
+
+Quick enum summary:
+
+**`GridSnapping`**: `None` · `PixelSnapping` (standard) · `UpscaleRenderTexture` (authentic low-res; incompatible with post-processing and UI text)
+
+**`CropFrame`**: `None` · `Pillarbox` · `Letterbox` · `Windowbox` (safest default) · `StretchFill`
+
+---
+
+## Reference Resolution
+
+Choose before building any assets. Never change after asset production starts.
+
+| Reference resolution | 1080p | 1440p | 4K |
+|---|---|---|---|
+| 320 × 180 | 6× | 8× | 12× |
+| 480 × 270 | 4× | ~5.3× | 8× |
+| 640 × 360 | 3× | 4× | 6× |
+
+320×180 is the safest general choice. For screens with no integer fit (e.g. 1366×768), use `cropFrame = Windowbox` to add black bars rather than stretching to a fractional scale.
+
+---
+
+## Migration & Compatibility
+
+### URP project with the Built-in standalone component
+
+**Symptom**: `DetectPipeline()` returns URP but camera has `UnityEngine.U2D.PixelPerfectCamera`. Symptoms are subtle because the standalone component has `ENABLE_URP` conditional code.
+
+**Fix**:
+1. Remove `com.unity.2d.pixel-perfect` from Package Manager
+2. Remove `UnityEngine.U2D.PixelPerfectCamera` from each camera
+3. Add `UnityEngine.Rendering.Universal.PixelPerfectCamera`
+4. Reconfigure — booleans (`pixelSnapping`, `upscaleRT`, `cropFrameX/Y`) become enums (`gridSnapping`, `cropFrame`)
+
+**→ Detection code: `references/pipeline-detection.cs`** (bottom of file).
+
+### Old URP namespace (pre-Unity 2022 / URP pre-13.x)
+
+**Symptom**: Compiler errors referencing `UnityEngine.Experimental.Rendering.Universal`.
+
+**Fix**: Replace `using UnityEngine.Experimental.Rendering.Universal;` with `using UnityEngine.Rendering.Universal;`. Update any assembly-qualified type strings. The `[MovedFrom]` attribute handles serialization automatically — components on GameObjects survive the upgrade.
+
+---
+
+## Common Issues & Solutions
+
+### Blurry sprites
+**Fix**: Set Filter Mode to Point on all in-scope sprites, disable Mip Maps, disable AA in Quality Settings.
+**→ Code: `references/sprite-settings.cs`**
+
+### Tilemap gaps between tiles
+Work through in order — workarounds like negative cell gap or PPU = 31.99 break when the camera moves.
+
+| # | Check | Fix |
+|---|---|---|
+| 1 | Sprite Atlas with Tight Packing off, Padding ≥ 4, Sprite Packer Mode enabled? | Enable Sprite Packer Mode in Editor settings; on the atlas set Padding ≥ 4 and turn Tight Packing off |
+| 2 | Mipmaps disabled on tileset textures and atlas? | Disable Generate Mip Maps |
+| 3 | AA = 0, MSAA off on camera? | Disable AA globally |
+| 4 | Compression = None? | RGBA 32-bit uncompressed |
+| 5 | All tile sprites have even pixel dimensions? | Odd dimensions cause 0.5px grid offset |
+| 6 | PPU = tile pixel width? (16×16 → PPU 16) | PPU mismatch leaves physical gaps |
+| 7 | Gaps only during camera movement after all above pass? | Use PP Camera pixel snapping; do not use `cellGap = -0.01f` |
+
+### Cinemachine conflict
+**Cause**: Both Cinemachine and the Pixel Perfect Camera write to orthographic size every frame.
+
+**Fix**: Add `CinemachinePixelPerfect` extension via the Add Extension dropdown on each Virtual Camera. Do not add it via `AddComponent` in code.
+
+**Known limitations**:
+- Camera blends between virtual cameras are not pixel-perfect during transitions
+- `UpscaleRenderTexture` reduces valid pixel-perfect ortho sizes, which may cause framing to deviate
+- Target Group + Framing Transposer causes visible choppiness (no fix available)
+
+### Post-processing blur with `upscaleRT`
+**Cause**: Post-processing runs after the PP Camera upscales the render texture.
+
+**Simple fix**: Disable `upscaleRT`. Post-processing then runs at native screen resolution.
+
+**Advanced fix (Unity 6 URP)**: Inject a `ScriptableRendererFeature2D` at `RenderPassEvent2D.AfterRenderingPostProcessing`. Use 2D-specific base classes — `ScriptableRendererFeature` (3D base class) is silently ignored in a URP 2D renderer.
+
+### UI text blurry with `upscaleRT`
+**Status**: Known Unity bug, declined to fix (still present Unity 6, 2025).
+
+**Root causes**: (A) Canvas renders into the low-res buffer and is upscaled with the scene. (B) TMP's SDF gradient threshold is miscalibrated at low reference resolutions.
+
+**Fixes in order of reliability**:
+1. `Screen Space - Overlay` on Canvas — bypasses the camera, renders at native resolution
+2. Dedicated UI camera with no PP Camera component, `Screen Space - Camera` mode
+3. Unity 6 only: `Font Material → Debug Settings → Sharpness = 1` (mitigates B, not A)
+
+### Physics / render desync (micro-stutter)
+**Cause**: Physics runs at a fixed timestep; interpolated positions produce fractional values that snap to different pixels each frame.
+
+**Fix**:
+- Enable `Rigidbody2D.interpolation = RigidbodyInterpolation2D.Interpolate` on physics-driven sprites
+- Set `Time.fixedDeltaTime = 1f / 60f` to match target frame rate
+- Keep camera tracking in `LateUpdate`, not `FixedUpdate`
+
+### Non-integer scaling / pixel decimation
+**Cause**: Screen resolution is not a clean integer multiple of the reference resolution.
+
+**Fix**: Choose a reference resolution from the table above. Use `cropFrame = Windowbox` when no integer fit exists.
+
+### Missing URP 2D Renderer
+**Fix**:
+1. `Assets > Create > Rendering > URP 2D Renderer Data`
+2. Assign it to your URP Asset under Renderer List
+3. Requires `com.unity.render-pipelines.universal` 12.0+
+
+### HDRP fallback
+Pixel Perfect Camera is unsupported in HDRP.
+
+**Built-in / Unity 5.x**: Use `RenderTexture` + `Graphics.Blit` with `FilterMode.Point`.
+
+**Unity 6 URP**: Use `ScriptableRendererFeature2D` + `ScriptableRenderPass2D` injected at `RenderPassEvent2D.AfterRendering` with `AddRasterRenderPass`. Note: `OnRenderImage` and `Graphics.Blit` are incompatible with Unity 6's render graph.

package/unity-skills/2d-pixel-perfect/references/api-reference.md

@@ -0,0 +1,81 @@
+# PixelPerfect Skill — Full API Reference
+
+## URP `PixelPerfectCamera` (`UnityEngine.Rendering.Universal`)
+API is identical since Unity 2023.2 through latest Unity 6 versions.
+
+### Properties
+
+| Property | Type | Access | Description |
+|---|---|---|---|
+| `assetsPPU` | `int` | get/set | Must match Pixels Per Unit on all sprites in scene |
+| `refResolutionX` | `int` | get/set | Base resolution width |
+| `refResolutionY` | `int` | get/set | Base resolution height |
+| `cropFrame` | `CropFrame` | get/set | How to handle aspect ratio differences |
+| `gridSnapping` | `GridSnapping` | get/set | Snapping mode — replaces old `pixelSnapping`/`upscaleRT` bools |
+| `orthographicSize` | `float` | get only | PP Camera's calculated ortho size (different from `Camera.orthographicSize`) |
+| `pixelRatio` | `int` | get only | Actual scale factor applied (e.g. 6 on 1080p with 320×180 ref res) |
+| `requiresUpscalePass` | `bool` | get only | True when `gridSnapping = UpscaleRenderTexture` |
+
+### Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `RoundToPixel(Vector3)` | `Vector3` | Snaps world-space position to pixel grid. Adapts to current `gridSnapping`. |
+| `CorrectCinemachineOrthoSize(float)` | `float` | Returns nearest pixel-perfect ortho size. Used by the Cinemachine extension. |
+
+### Static
+
+**`UnityEngine.U2D.PixelPerfectRendering.pixelSnapSpacing`** (static float) — world-space size of one screen pixel. Formula: `Camera.orthographicSize * 2f / Camera.pixelHeight`. Set manually in custom setups that bypass the PP Camera component (e.g. HDRP fallback, custom SRP).
+
+---
+
+## `GridSnapping` Enum
+
+| Value | Old standalone equivalent | Behaviour |
+|---|---|---|
+| `None` | `pixelSnapping = false`, `upscaleRT = false` | No snapping. |
+| `PixelSnapping` | `pixelSnapping = true` | Snaps SpriteRenderers at render-time. Transforms stay at float precision. |
+| `UpscaleRenderTexture` | `upscaleRT = true` | Renders at ref res then upscales. Incompatible with post-processing and UI text. |
+
+---
+
+## `CropFrame` Enum
+
+| Value | Old standalone equivalent | Behaviour |
+|---|---|---|
+| `None` | both false | No cropping. Scene stretches to fill screen. |
+| `Pillarbox` | `cropFrameX = true, cropFrameY = false` | Black bars left and right. |
+| `Letterbox` | `cropFrameX = false, cropFrameY = true` | Black bars top and bottom. |
+| `Windowbox` | both true, `stretchFill = false` | Black bars all sides. Safest default. |
+| `StretchFill` | both true, `stretchFill = true` | Fills screen maintaining aspect ratio. Enables component-level Filter Mode. |
+
+**Filter Mode** (only active when `StretchFill` — separate from per-sprite texture Filter Mode):
+- `Retro AA` — default. Integer upscale to nearest multiple, then bilinear to screen. Recommended.
+- `Point` — nearest-neighbour all the way to screen. Can lose pixel-perfectness at non-integer scale factors.
+
+---
+
+## Recommended Configurations
+
+| Use case | `gridSnapping` | `cropFrame` | Notes |
+|---|---|---|---|
+| Standard pixel art | `PixelSnapping` | `Windowbox` | Safe default. Compatible with post-processing and UI. |
+| Authentic low-res look | `UpscaleRenderTexture` | `Windowbox` | No post-processing. Separate UI camera required. |
+| Performance on 4K/HiDPI | `UpscaleRenderTexture` | `Windowbox` | Renders fewer pixels. Same UI caveat. |
+| Full-screen stretch | `PixelSnapping` | `StretchFill` | Use `Retro AA` filter, not Point. |
+
+---
+
+## Standalone Built-in (`UnityEngine.U2D.PixelPerfectCamera`)
+All booleans, no enums. No `RoundToPixel`, `CorrectCinemachineOrthoSize`, `requiresUpscalePass`, or `orthographicSize`.
+
+| Property | Type | Constraint |
+|---|---|---|
+| `assetsPPU` | `int` | — |
+| `refResolutionX` / `refResolutionY` | `int` | — |
+| `pixelSnapping` | `bool` | Silently ignored when `upscaleRT = true` |
+| `upscaleRT` | `bool` | When true, `pixelSnapping` has no effect |
+| `cropFrameX` | `bool` | Black bars left/right |
+| `cropFrameY` | `bool` | Black bars top/bottom |
+| `stretchFill` | `bool` | Only functional when **both** `cropFrameX` and `cropFrameY` are `true` |
+| `pixelRatio` | `int` readonly | Same semantics as URP `pixelRatio` |

package/unity-skills/2d-pixel-perfect/references/camera-setup-builtin.cs

@@ -0,0 +1,40 @@
+// PixelPerfect Skill — Built-in Standalone Camera Setup
+// -------------------------------------------------------
+// Assembly: Unity.2D.PixelPerfect
+using UnityEngine;
+using UnityEngine.U2D;
+
+namespace PixelPerfect
+{
+    public static class CameraSetupBuiltIn
+    {
+        public static PixelPerfectCamera ConfigureCamera(Camera camera, int refResX, int refResY, int targetPPU)
+        {
+            var pp = camera.gameObject.GetComponent<PixelPerfectCamera>()
+                  ?? camera.gameObject.AddComponent<PixelPerfectCamera>();
+
+            // Same base settings as URP
+            camera.orthographic = true;
+            camera.orthographicSize = (refResY / 2f) / targetPPU;
+            camera.allowHDR = camera.allowMSAA = camera.allowDynamicResolution = false;
+            QualitySettings.antiAliasing = 0;
+            QualitySettings.anisotropicFiltering = AnisotropicFiltering.Disable;
+
+            pp.assetsPPU      = targetPPU;
+            pp.refResolutionX = refResX;
+            pp.refResolutionY = refResY;
+            pp.pixelSnapping  = true;    // silently ignored when upscaleRT = true
+            pp.upscaleRT      = false;
+            pp.cropFrameX     = true;    // black bars left/right
+            pp.cropFrameY     = true;    // black bars top/bottom — both true = Windowbox equivalent
+            pp.stretchFill    = false;   // only functional when BOTH cropFrameX and cropFrameY are true
+
+            // Read-only: pp.pixelRatio (int) — same semantics as URP pixelRatio
+            //
+            // Note: No RoundToPixel, CorrectCinemachineOrthoSize, requiresUpscalePass,
+            //       or orthographicSize on the standalone component.
+
+            return pp;
+        }
+    }
+}