Five Phase Pass

If the arguments start with --baseline, run P5 only — audit all skills against the cumulative current stack (read AGENTS.md + README.md + git log --oneline to understand what the stack currently is). Skip P1–P4. Treat known prior changes (TS 7 / tsgo, asdf/Volta cleanup, PixiJS 8.18.1 first-party, TurboRepo generator, jotai-family removal) as already-shipped facts — the question is whether the skill ecosystem reflects them.

Otherwise treat the arguments as the change description (e.g. "remove jotai-family", "upgrade tsgo to 7.5", "add immer beside jotai"). If empty or ambiguous, ask before proceeding.

P1 — apps/web

Implement the change in apps/web/. Use the matching specialized skill from .agents/skills/. Source-code edits only.

P2 — generator template

Mirror P1's source-level changes into turbo/generators/templates/app/. Diffs must be literally identical except for {{name}} token substitution. New apps must be born clean.

P3 — regenerate test-project + gate

Regenerate apps/test-project from the updated template (or update in place if simpler). apps/test-project/ is gitignored — never commit it. It's the local materialization of the generator template, kept on disk as a sanity-check artifact for the pass. Committing it makes CI run a duplicate Playwright suite that races for the same Storybook port (6006) as apps/web and tears Storybook down with script "storybook" exited with code 1.

Before bun run check, run the kill-servers skill (or its inlined steps below) — leftover dev/preview/storybook processes from prior runs are the documented cause of intermittent ERR_CONNECTION_REFUSED on Playwright's parallel storybook workers. This is the single highest-yield way to make the gate go green on the first try.

pkill -f "storybook dev" || true; pkill -f "vite preview" || true; pkill -f "vite dev" || true
sleep 2
lsof -i :3000 -i :5173 -i :6006 2>/dev/null | grep LISTEN || echo "all clear"

Then run bun run check. Must be green before P4. Retry once on a known infra flake (cold prebundle cache, port race); a real failure stops the pass — do NOT silently .skip.

P3.4 — Dev fan-out smoke (dev orchestration changes only)

If P1 modified any of: root turbo.json, root package.json's dev script, any per-app package.json dev / storybook / biome:watch / stylelint:watch scripts, or turbo/generators/templates/app/package.json — smoke bun run dev and confirm all four co-runners actually stay alive. The gate (bun run check) does NOT exercise the dev workflow, so a broken watcher script (e.g. a tool that no longer ships --watch) or an inverted Turbo with direction passes the gate but breaks the iPad-over-LAN inner loop on next bun run dev.

pkill -f "storybook dev" 2>/dev/null; pkill -f "vite dev" 2>/dev/null; pkill -f "chokidar" 2>/dev/null; pkill -f "biome check" 2>/dev/null; pkill -f "stylelint" 2>/dev/null; sleep 2
(bun run dev > /tmp/dean-dev.log 2>&1 &) ; sleep 25; pgrep -af "vite dev|storybook dev|chokidar" | head -10; lsof -i :5173 -i :6006 2>/dev/null | grep LISTEN; pkill -f "turbo run dev"; pkill -f "vite dev"; pkill -f "storybook dev"; pkill -f "chokidar"

Pass criteria — all four must be true after 25s:

1. vite dev process alive, port 5173 LISTEN
2. storybook dev process alive, port 6006 LISTEN
3. chokidar ... biome check process alive (biome:watch wrapper)
4. chokidar ... stylelint process alive (stylelint:watch wrapper)

If any of the four exited or its port is silent, dev is broken. Inspect /tmp/dean-dev.log for the failure mode and fix at the orchestration source — with-direction in turbo.json (must be on the task you invoke, e.g. dev, NOT on the watcher), the per-app script (Biome 2.x and Stylelint 16 both ship NO native --watch — both are wrapped in chokidar-cli), or the root filter.

Skip this step for changes that don't touch dev orchestration (component edits, schemas, tests, docs).

P3.4.1 — Dev browser-console smoke (any P1 change)

The gate's Playwright runs against bun run preview (the production build), so dev-only runtime errors are invisible to it: react-scan is gated to import.meta.env.DEV, top-level-await module evaluation runs in dev only, side channels (anime.js, PixiJS) initialize via dev paths, and Vite's prebundle cache is dev-only. A broken applyEngineDefaults, a stale .vite/deps entry, or a ZodError when a persisted IDB record re-parses against a changed schema (Pillar 3) passes the gate green and reveals itself only when a human opens the browser.

Canonical quick check — always run bun run check:runtime before completing. It probes the local ports (5173/3010); if a server is up it headless-loads the app and fails on the "Something broke" error boundary or any runtime ZodError; if no server is running it skips (exit 0) and never starts one. For a deeper sweep (all console errors/warnings, 4xx/5xx responses, blank-page detection), use the fuller inline smoke below.

An empty error log is NOT proof the page works. A blank page can render without throwing — React rendered into an empty body, hydration silently no-op'd because the target element is missing, etc. The smoke MUST also assert visible content.

After P3 (and P3.4 if applicable), with bun run dev already up:

// /tmp/dean-smoke.mjs — adjust the playwright path to match the workspace install
import { chromium } from "/abs/path/to/node_modules/playwright/index.js";
const browser = await chromium.launch();
const page = await (await browser.newContext()).newPage();
const errs = []; const failed = [];
page.on("pageerror", (e) => errs.push(`PAGE: ${e.message}`));
page.on("console", (m) => { if (m.type() === "error" || m.type() === "warning") errs.push(`[${m.type()}] ${m.text()}`); });
page.on("response", (r) => { if (r.status() >= 400) failed.push(`${r.status()} ${r.url()}`); });
// Don't use `networkidle` — Vite HMR and opt-in TanStack DevTools can keep
// websockets open and the wait would never resolve. DOM + an explicit h1-wait
// is the contract: every dean-stack route renders an h1.
await page.goto("http://localhost:5173/", { waitUntil: "domcontentloaded", timeout: 30000 });
await page.waitForSelector("h1", { timeout: 15000 });
await page.waitForTimeout(1500);
const innerText = await page.evaluate(() => document.body.innerText);
const innerHtmlLen = await page.evaluate(() => document.body.innerHTML.length);
const title = await page.title();
const h1 = await page.$$eval("h1", (els) => els.map((e) => e.textContent));
console.log("ERRORS:", errs.length || "(none)", errs.join("\n"));
console.log("FAILED:", failed.length || "(none)", failed.join("\n"));
console.log("TITLE:", title, "H1:", JSON.stringify(h1), "BODY_LEN:", innerHtmlLen);
console.log("BODY:", innerText.slice(0, 200));
await browser.close();
const blank = innerText.trim().length < 5;
process.exit(errs.length + failed.length === 0 && !blank ? 0 : 1);

bun /tmp/dean-smoke.mjs   # exit 0 = pass; non-zero = fix the cause

Pass criteria — ALL must be true:

1. pageerror list empty
2. No error / warning console messages
3. No 4xx/5xx responses
4. document.body.innerText.trim().length >= 5 — proves the page actually rendered something visible, not just an empty React shell

The most common failure modes:

1. Stale Vite prebundle cache after a renamed import — rm -rf apps/<name>/node_modules/.vite and restart dev
2. Side-channel API misuse — e.g. utils.set(engine, ...) instead of engine.defaults.foo = ... (animejs); app.stage.addChild(...) called during render instead of inside usePixiApp's setup (PixiJS)
3. Broken module evaluation chain — a top-level throw in client.tsx (or any module imported by it) breaks hydrateRoot and surfaces unrelated downstream errors like "react-scan failed to load"
4. Hydration target mismatch — TanStack Start in SPA mode renders the full document via __root__'s <html>...</html>. client.tsx must hydrateRoot(document, <StartClient />) (importing StartClient from @tanstack/react-start/client — the subpath export, NOT the main entry). hydrateRoot(document.getElementById("root"), ...) silently no-ops because no <div id="root"> exists in the SSR output, leaving the page blank with NO error.
5. Two React copies via Bun's hashed .bun/...@<hash> cache — produces "Invalid hook call" / "null useContext" errors. Add resolve.dedupe: ["react", "react-dom", "@tanstack/react-router"] to vite.config.ts.
6. react-scan v0.5.x + TanStack Router's HeadContent — react-scan's React-19 instrumentation breaks useContext inside HeadContent's useRouter. Symptom: app renders the route's error UI ("Something went wrong / Cannot read properties of null"). Mitigation: keep react-scan in Storybook only; do NOT load it in the app's client.tsx or via __root__'s head.scripts.
7. Missing static asset — typically /favicon.ico. dean-stack's __root__ route ships an inline data-URI favicon via head.links; verify it's still present.

Re-run after fixing — must reach exit 0 before P4.

P3.5 — Render-quality visual check (UI-touching changes only)

If P1 modified any *.tsx file (component, route, hook that fronts a side channel), after the gate passes, run a Playwright session with react-scan loaded — point at the affected story — and inspect for highlighted re-render boxes. react-scan is loaded automatically in Storybook dev via .storybook/preview.tsx (gated by import.meta.env.DEV); the Storybook Playwright project hits dev mode, so render highlights are live there. Not loaded in the app dev server — react-scan v0.5.x crashes TanStack Router's HeadContent; component-level re-render diagnostics happen in Storybook only until that incompatibility is resolved upstream. Unexpected highlights are real bugs — typically a side-channel violation (anime.js / PixiJS in render), an unstable atom return, or a nested component definition. Fix the cause; never add manual useMemo / useCallback / React.memo (forbidden — see react-compiler-rules). Skip this step for non-UI changes (docs, configs, schemas). There is intentionally no skill for react-scan — it has no version-specific deprecations or opinionated patterns.

P3.6 — React-doctor scanner pass (UI-touching changes only)

If P1 modified any *.tsx file, after the gate passes, run:

npx -y react-doctor@latest . --verbose --diff --fail-on error

--fail-on error blocks on real lint errors; score regressions are informational and surface in the final report (a 0–100 health score). Owned by the react-doctor skill — see .agents/skills/react-doctor/SKILL.md. Skip for non-UI changes. Deliberately NOT in bun run check — it's npx-resolved (not pinned), score-based (not pass/fail), and phones home by default — so it lives at the post-gate workflow tier instead. CI runs this advisory via .github/workflows/react-doctor.yml on PRs.

P4 — docs / owning skill

Update AGENTS.md, README.md, and the .agents/skills/<name>/SKILL.md that owns the changed tech (front-matter description, "Defers to", "When to invoke", patterns, anti-patterns, "Triggers on"). Update mermaid diagrams and known-gap entries in README if names changed.

Append to the <sweep-tokens> table below if this change introduces a new "we no longer use X" / "we renamed Y to Z" / "we excluded W" rule. That makes the change discoverable to all future P5 runs.

P5 — cross-skill audit (two roles, run in this order)

P5.0 — Mechanical sweep (orchestrator runs grep directly). Run grep -rn -E '<pattern>' .agents/skills/ AGENTS.md README.md for every entry in <sweep-tokens> below — exclude potential_skills/, node_modules, .turbo, dist/. Build a flat file:line:token list. For each hit, classify as either:

• Stale — token outside its allow-context (e.g. atomFamily not adjacent to "don't use" wording).
• Deliberate — token inside its allow-context (e.g. @pixi/ inside pixijs-migration-v8/SKILL.md).

Mechanical sweep covers literal substring drift exhaustively. Do NOT delegate this to agents — they skim and miss occurrences in cross-cutting boilerplate (the Pillar 4 means: bun run check runs … → tsc --noEmit → … line, "Defers to" lists, trigger word tables). The grep is bulletproof; the LLM is not.

For per-change runs: sweep only for the token(s) introduced by THIS change. For --baseline: sweep the full table.

P5.1 — Narrative agents (parallel Explore subagents). Spawn one agent per topic family (state: jotai+idb; build: vite+nitro+turborepo+biome+stylelint+tailwind+t3-env; types: ts+zod; testing: bun-test+playwright-+storybook-; canvas: pixijs-; framework: tanstack-+react-+animejs; runtime: bun+node). Pass each agent the P5.0 sweep findings for files in its scope so it does NOT duplicate the mechanical pass. Each agent's job is narrative only:

• Conceptual drift (e.g. "this skill frames PixiJS as third-party when it's first-party now")
• Self-contradictions (rule on L34 vs example on L164)
• Wrong package names (@tanstack/start vs @tanstack/react-start)
• Stale ownership claims, dead "Defers to" links, removed APIs in trigger lists
• Patterns inconsistent with the current Pillars

P5.2 — Aggregate + classify. Merge P5.0 stale-list + P5.1 findings, dedupe. For per-change runs: trivial substitutions (renamed token in a list, version bump in a pinned: comment) apply immediately and are reported. Narrative or load-bearing findings escalate to a punch list with file:line and proposed text — wait for user review. For --baseline runs: everything is a punch list, grouped by topic. Do not auto-edit.

Do not spawn subagents for P1/P2/P4 single-file edits or P3 single gate run.