@delegance/claude-autopilot 5.5.2 → 7.2.0

package/dist/src/dashboard/upload/uploader.js

@@ -0,0 +1,330 @@
+// CLI uploader — snapshot, chunk, retry, finalize.
+//
+// Flow:
+//   1. Empty events.ndjson check → skip upload (Phase 2.2 returns 422 on
+//      expectedChunkCount=0; never call it).
+//   2. Snapshot events.ndjson + state.json to <runDir>/.upload-snapshot/.
+//   3. Bootstrap session: GET dashboard upload-session for resume; if 404
+//      mint fresh via POST /api/upload-session (Phase 2.2 endpoint, accepts
+//      Bearer clp_<key> via resolveCaller).
+//   4. PUT each chunk with x-chunk-prev-hash; retry transient 5xx.
+//   5. POST /api/runs/:runId/finalize with chainRoot + state.
+//   6. On success, delete the snapshot dir.
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { hashChunk, ZERO_HASH } from "./chain.js";
+import { sha256OfCanonical } from "./canonical.js";
+import { snapshotRun, deleteSnapshot, SnapshotMismatchError } from "./snapshot.js";
+const CHUNK_BYTES = 1024 * 1024; // 1 MiB matches server MAX_CHUNK_BYTES
+const DEFAULT_RETRY_DELAYS_MS = [1000, 4000, 16000, 64000];
+function resolveRetryDelays() {
+    // Test seam — let CI/tests override the exponential backoff schedule
+    // so transient-failure assertions don't add minutes to the suite.
+    const override = process.env.CLAUDE_AUTOPILOT_UPLOAD_RETRY_MS;
+    if (!override)
+        return DEFAULT_RETRY_DELAYS_MS;
+    return override
+        .split(',')
+        .map((s) => Number.parseInt(s.trim(), 10))
+        .filter((n) => Number.isFinite(n) && n >= 0);
+}
+export class UploadError extends Error {
+    status;
+    constructor(message, status = null) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Phase 3 — thrown when /api/upload-session returns 402 with a structured
+ * `limit_reached` payload. Auto-upload entry point detects this subclass
+ * and prints a friendly message without retrying or overriding the run's
+ * exit code.
+ */
+export class UploadLimitError extends UploadError {
+    payload;
+    constructor(message, payload) {
+        super(message, 402);
+        this.payload = payload;
+    }
+}
+function resolveBaseUrl(opts) {
+    return (opts.baseUrl ??
+        process.env.AUTOPILOT_DASHBOARD_BASE_URL ??
+        'https://autopilot.dev');
+}
+function checkAborted(signal) {
+    if (signal?.aborted) {
+        const reason = signal.reason;
+        const err = reason instanceof Error
+            ? reason
+            : new Error('upload aborted');
+        throw err;
+    }
+}
+async function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, ms);
+        if (signal) {
+            const onAbort = () => {
+                clearTimeout(t);
+                reject(new Error('aborted'));
+            };
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+async function readChunks(filePath) {
+    const handle = await fs.open(filePath, 'r');
+    try {
+        const stat = await handle.stat();
+        const total = stat.size;
+        const out = [];
+        let position = 0;
+        while (position < total) {
+            const remaining = total - position;
+            const size = remaining < CHUNK_BYTES ? remaining : CHUNK_BYTES;
+            const buf = Buffer.alloc(size);
+            const { bytesRead } = await handle.read(buf, 0, size, position);
+            if (bytesRead !== size) {
+                throw new UploadError(`short read at offset ${position}: ${bytesRead}/${size}`);
+            }
+            out.push(buf);
+            position += size;
+        }
+        return out;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function fetchWithRetry(url, init, fetchImpl, signal, is5xxRetryable) {
+    let lastErr = null;
+    const delays = resolveRetryDelays();
+    for (let attempt = 0; attempt <= delays.length; attempt++) {
+        checkAborted(signal);
+        try {
+            const res = await fetchImpl(url, init);
+            if (res.status >= 500 && res.status < 600 && is5xxRetryable && attempt < delays.length) {
+                const wait = delays[attempt];
+                await delay(wait, signal);
+                continue;
+            }
+            return res;
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw err;
+            lastErr = err;
+            if (attempt < delays.length) {
+                const wait = delays[attempt];
+                await delay(wait, signal);
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new UploadError('exhausted retries');
+}
+async function bootstrapSession(baseUrl, apiKey, runId, expectedChunkCount, expectedBytes, fetchImpl, signal) {
+    // Resume path first.
+    const resumeUrl = `${baseUrl}/api/dashboard/runs/${encodeURIComponent(runId)}/upload-session`;
+    const resumeRes = await fetchWithRetry(resumeUrl, {
+        method: 'GET',
+        headers: { authorization: `Bearer ${apiKey}` },
+        signal,
+    }, fetchImpl, signal, true);
+    if (resumeRes.status === 200) {
+        const data = await resumeRes.json();
+        return { session: data, resumed: true };
+    }
+    if (resumeRes.status !== 404) {
+        const text = await resumeRes.text().catch(() => '');
+        throw new UploadError(`resume bootstrap failed: ${resumeRes.status} ${text}`, resumeRes.status);
+    }
+    // Mint fresh via Phase 2.2 endpoint.
+    const mintUrl = `${baseUrl}/api/upload-session`;
+    const mintRes = await fetchWithRetry(mintUrl, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${apiKey}`,
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({ runId, expectedChunkCount, expectedBytes }),
+        signal,
+    }, fetchImpl, signal, true);
+    // Phase 3 — structured 402 means we hit a runs/storage cap. Surface as a
+    // typed error so the auto-upload caller can print a friendly message
+    // without retrying or overriding the run's exit code.
+    if (mintRes.status === 402) {
+        let parsed = {};
+        try {
+            parsed = await mintRes.json();
+        }
+        catch {
+            // fall through — message below still useful
+        }
+        const limit = parsed.limit ?? 'unknown';
+        const current = parsed.current ?? 0;
+        const max = parsed.max ?? 0;
+        const upgradeUrl = parsed.upgrade_url ?? '';
+        throw new UploadLimitError(`upload rejected — ${limit} cap reached (${current}/${max}). Upgrade at ${upgradeUrl}`, { limit, current, max, upgrade_url: upgradeUrl });
+    }
+    if (mintRes.status !== 201) {
+        const text = await mintRes.text().catch(() => '');
+        throw new UploadError(`mint failed: ${mintRes.status} ${text}`, mintRes.status);
+    }
+    const data = await mintRes.json();
+    return { session: { ...data, session: { ...data.session, nextExpectedSeq: 0 } }, resumed: false };
+}
+export async function uploadRun(runId, runDir, opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const baseUrl = resolveBaseUrl(opts);
+    const signal = opts.signal;
+    try {
+        // (1) Empty events check — skip cleanly so server's 422 isn't tripped.
+        const eventsPath = path.join(runDir, 'events.ndjson');
+        let eventsStat;
+        try {
+            eventsStat = await fs.stat(eventsPath);
+        }
+        catch {
+            return { ok: true, skipped: true };
+        }
+        if (eventsStat.size === 0) {
+            return { ok: true, skipped: true };
+        }
+        // (2) Snapshot.
+        checkAborted(signal);
+        const snap = await snapshotRun(runDir);
+        opts.onProgress?.({ kind: 'snapshot', bytes: snap.eventsBytes });
+        const chunks = await readChunks(snap.events);
+        const expectedChunkCount = chunks.length;
+        // (3) Bootstrap. Phase 3 — pass expectedBytes for storage cap preflight.
+        checkAborted(signal);
+        const { session, resumed } = await bootstrapSession(baseUrl, opts.apiKey, runId, expectedChunkCount, snap.eventsBytes, fetchImpl, signal);
+        const startSeq = session.session.nextExpectedSeq ?? 0;
+        opts.onProgress?.({ kind: 'session', resumed, nextExpectedSeq: startSeq });
+        // (4) Stream chunks. Walk the chain forward from seq 0 even when
+        // resuming so prev-hash for seq=startSeq is correct.
+        let prev = ZERO_HASH;
+        for (let i = 0; i < startSeq; i++) {
+            const chunk = chunks[i];
+            if (!chunk)
+                throw new UploadError(`missing chunk at seq ${i} during prefix replay`);
+            prev = hashChunk(prev, chunk);
+        }
+        let token = session.uploadToken;
+        let chainRoot = prev;
+        let reauthAttempts = 0; // bugbot HIGH — bound the 401 re-bootstrap retry
+        const MAX_REAUTH_ATTEMPTS = 1;
+        for (let seq = startSeq; seq < chunks.length; seq++) {
+            checkAborted(signal);
+            const chunk = chunks[seq];
+            if (!chunk)
+                throw new UploadError(`missing chunk at seq ${seq}`);
+            const thisHash = hashChunk(prev, chunk);
+            const url = `${baseUrl}/api/runs/${encodeURIComponent(runId)}/events/${seq}`;
+            const init = {
+                method: 'PUT',
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    'content-type': 'application/octet-stream',
+                    'x-chunk-prev-hash': prev,
+                },
+                body: chunk,
+                signal,
+            };
+            const res = await fetchWithRetry(url, init, fetchImpl, signal, true);
+            if (res.status === 200 || res.status === 201) {
+                prev = thisHash;
+                chainRoot = thisHash;
+                opts.onProgress?.({ kind: 'chunk-uploaded', seq, total: chunks.length });
+                continue;
+            }
+            if (res.status === 401) {
+                // bugbot HIGH — bound retries. Token might be expired, OR the API
+                // key is revoked (bootstrap succeeds but minted tokens are still
+                // 401). Without a counter, the loop spins forever.
+                if (reauthAttempts >= MAX_REAUTH_ATTEMPTS) {
+                    const text = await res.text().catch(() => '');
+                    throw new UploadError(`chunk ${seq} unauthorized after ${reauthAttempts} re-bootstrap attempt(s); check API key validity. ${text}`, res.status);
+                }
+                reauthAttempts++;
+                const reboot = await bootstrapSession(baseUrl, opts.apiKey, runId, expectedChunkCount, snap.eventsBytes, fetchImpl, signal);
+                token = reboot.session.uploadToken;
+                seq -= 1;
+                continue;
+            }
+            if (res.status === 409) {
+                // Duplicate chunk content with matching hash is treated as success
+                // by the server (RPC path); treat as success here too if hash agrees.
+                const text = await res.text().catch(() => '');
+                if (/duplicate/i.test(text)) {
+                    prev = thisHash;
+                    chainRoot = thisHash;
+                    opts.onProgress?.({ kind: 'chunk-uploaded', seq, total: chunks.length });
+                    continue;
+                }
+                throw new UploadError(`chunk ${seq} rejected: ${res.status} ${text}`, res.status);
+            }
+            const text = await res.text().catch(() => '');
+            throw new UploadError(`chunk ${seq} failed: ${res.status} ${text}`, res.status);
+        }
+        // (5) Finalize.
+        checkAborted(signal);
+        let stateJson = {};
+        try {
+            const raw = await fs.readFile(snap.state, 'utf-8');
+            stateJson = JSON.parse(raw);
+        }
+        catch {
+            stateJson = {};
+        }
+        // sha256 not strictly needed here — server recomputes — but include for parity.
+        void sha256OfCanonical(stateJson);
+        const finalizeUrl = `${baseUrl}/api/runs/${encodeURIComponent(runId)}/finalize`;
+        const finalRes = await fetchWithRetry(finalizeUrl, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${token}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                chainRoot,
+                expectedChunkCount,
+                stateJson,
+            }),
+            signal,
+        }, fetchImpl, signal, true);
+        if (finalRes.status !== 200) {
+            const text = await finalRes.text().catch(() => '');
+            throw new UploadError(`finalize failed: ${finalRes.status} ${text}`, finalRes.status);
+        }
+        opts.onProgress?.({ kind: 'finalized' });
+        // (6) Cleanup snapshot.
+        await deleteSnapshot(runDir);
+        return {
+            ok: true,
+            url: `${baseUrl}/runs/${encodeURIComponent(runId)}`,
+        };
+    }
+    catch (err) {
+        // Phase 3 — let UploadLimitError bubble so the auto-upload entry point
+        // can print the friendly message + preserve the run's exit code.
+        if (err instanceof UploadLimitError) {
+            throw err;
+        }
+        if (err instanceof SnapshotMismatchError) {
+            return { ok: false, error: `snapshot mismatch: ${err.message}` };
+        }
+        if (err.message === 'aborted') {
+            return { ok: false, error: 'aborted' };
+        }
+        return { ok: false, error: err.message ?? String(err) };
+    }
+}
+//# sourceMappingURL=uploader.js.map

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "5.5.2",
+  "version": "7.2.0",
   "type": "module",
+  "publishConfig": {
+    "tag": "next"
+  },
   "description": "Autonomous development pipeline for Claude Code: brainstorm → spec → plan → implement → migrate → validate → PR → review → merge. Multi-model, local-first, every phase a skill you can intervene in.",
   "keywords": [
     "claude-autopilot",
@@ -15,6 +18,10 @@
     "pipeline"
   ],
   "license": "MIT",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/axledbetter/claude-autopilot.git"
@@ -52,20 +59,28 @@
   ],
   "scripts": {
     "test": "node scripts/test-runner.mjs",
+    "test:adapters:live": "node --test --import=tsx tests/adapters/live/vercel.cert.ts tests/adapters/live/fly.cert.ts tests/adapters/live/render.cert.ts",
+    "test:rls": "node --test --import=tsx tests/rls/*.test.ts",
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json && node scripts/post-build-rewrite-imports.mjs",
     "prepublishOnly": "npm run build && npm test",
-    "autoregress": "tsx scripts/autoregress.ts"
+    "autoregress": "tsx scripts/autoregress.ts",
+    "db:start": "bash scripts/db/start-supabase.sh",
+    "db:stop": "bash scripts/db/stop-supabase.sh",
+    "db:reset": "bash scripts/db/reset-supabase.sh"
   },
   "dependencies": {
+    "@supabase/supabase-js": "^2.97.0",
     "ajv": "^8",
     "ajv-formats": "^3.0.1",
+    "canonicalize": "^3.0.0",
     "dotenv": ">=16",
     "js-yaml": "^4",
     "minimatch": ">=9",
     "proper-lockfile": "^4.1.2",
     "shell-quote": "^1.8.3",
-    "tsx": ">=4"
+    "tsx": ">=4",
+    "ulid": "^3.0.2"
   },
   "optionalDependencies": {
     "@anthropic-ai/sdk": "^0.91.1",
@@ -78,6 +93,7 @@
     "@types/node": "^25",
     "@types/proper-lockfile": "^4.1.4",
     "@types/shell-quote": "^1.7.5",
+    "supabase": "^2.20.0",
     "typescript": "^6"
   },
   "peerDependencies": {

package/scripts/autoregress.ts

@@ -259,7 +259,7 @@ async function cmdGenerate(args: string[]): Promise<number> {
     let snapContent: string;
     try {
       const response = await client.responses.create({
-        model: process.env.CODEX_MODEL ?? 'gpt-5.3-codex',
+        model: process.env.CODEX_MODEL ?? 'gpt-5.5',
         instructions: 'You write TypeScript snapshot tests. Output ONLY the file contents, no markdown fences.',
         input: prompt,
         max_output_tokens: 2000,

package/scripts/test-runner.mjs

@@ -4,6 +4,10 @@ import { spawnSync } from 'node:child_process';
 
 const files = [];
 for await (const f of glob('tests/**/*.test.ts')) {
+  // RLS tests require a live Supabase stack + env credentials; they run
+  // from a dedicated workflow (.github/workflows/db-tests.yml) via
+  // `npm run test:rls`, not from the general test runner.
+  if (f.startsWith('tests/rls/') || f.startsWith('tests\\rls\\')) continue;
   files.push(f);
 }
 files.sort();

package/skills/claude-autopilot.md

@@ -47,7 +47,7 @@ Each phase writes its output to disk. Claude can stop, the user can edit the art
    - PR review finds criticals → fix on branch, push, re-review (max 2 rounds).
    - Bugbot finds real bugs → fix, push, re-triage (max 3 rounds).
    - Unrecoverable failure → stop, report what completed, show what remains.
-4. **Codex review is part of the loop, not optional.** The pipeline explicitly dispatches to `gpt-5.3-codex` for spec review, plan review, and PR review. This is the multi-model moat — don't skip it.
+4. **Codex review is part of the loop, not optional.** The pipeline explicitly dispatches to `gpt-5.5` for spec review, plan review, and PR review. This is the multi-model moat — don't skip it.
 5. **Skills are swappable.** `review-2pass` and `council` are alternative review phases — a user can configure which runs. The pipeline doesn't hardcode Claude or Codex.
 
 ## Phase outputs

package/skills/make-interfaces-feel-better/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: make-interfaces-feel-better
+description: Craft-and-feel polish for an interface that already works correctly and is already simple. Use when the user says "feels off", "feels clunky", "not quite right", "doesn't feel polished", "lacks soul", "feels cheap", "add some life to it", "make it feel expensive", "feels like AI slop", or wants motion/typography/microcopy/color work that isn't about fixing bugs or alignment. This is the vibes layer — assumes correctness and subtraction are already handled. If the screen is broken or cluttered, route to /ui-ux-pro-max or /simplify-ui first. Complements frontend-design:frontend-design (creative vision) but is scoped to tuning what exists.
+---
+
+# Make interfaces feel better — the craft layer
+
+This skill is for the pass where the interface already *works* and is already *simple*, but still feels mediocre. You are tuning emotion, not structure. If the user hasn't had the basics fixed yet, recommend `/ui-ux-pro-max` and `/simplify-ui` first; great feel on top of a broken layout is lipstick.
+
+## The diagnostic
+
+Before touching anything, ask yourself what specific feeling is off. Interfaces usually fail one of five feels:
+
+1. **Cheap** — cramped, low-contrast, unbranded, no texture, inconsistent.
+2. **Cold / clinical** — correct but soulless. Efficient but no character.
+3. **Heavy / laggy** — transitions stutter, state changes snap, nothing feels alive.
+4. **Disorganized** — elements fight for attention; no clear visual hierarchy.
+5. **Nervous / fussy** — too many animations, too many chips, too many accent colors.
+
+The fix for each is different. Name the feeling first, then apply the matching lever below.
+
+## Levers — in order of impact-per-minute
+
+### 1. Typography (highest leverage)
+
+- **Pair a display face with a body face.** One distinctive (Playfair, Fraunces, Söhne, Tiempos, Inter Display) + one refined (Inter, Figtree, Söhne, IBM Plex, Geist). Don't use Inter for everything.
+- **Use the display only at top levels** — page title, card titles ≥ 18px. Everything else body.
+- **Tighten line-height on display** (1.1–1.2) and loosen on body (1.5–1.65).
+- **Letter-spacing for uppercase** — eyebrows and section labels get `letter-spacing: 0.05em` or more.
+- **One tabular-nums for numeric data** — `font-variant-numeric: tabular-nums` on any column of amounts makes them snap into alignment.
+
+### 2. Color & contrast
+
+- **One dominant color, one accent, one destructive. No fourth.**
+- **Backgrounds are off-white or off-black, never pure.** `#F7F8F6`, `#0B0D0A` — feel warmer than `#FFFFFF` / `#000000`.
+- **Shadows with color** — `box-shadow: 0 2px 12px rgba(brand-color, 0.08)` feels branded; `rgba(0,0,0,0.08)` feels generic.
+- **Gradients only on one element at a time.** Usually the primary CTA or the hero. Gradients everywhere = AI-slop.
+
+### 3. Motion
+
+- **Page-load stagger is cheap delight.** 40–80ms stagger on cards/rows hitting the viewport; nothing fancier.
+- **Easing: `cubic-bezier(0.22, 1, 0.36, 1)` for enter/exit.** Not `ease-in-out`.
+- **200–280ms for small transitions, 400–600ms for modals/layouts.** Outside that range feels wrong.
+- **Never animate what the user didn't cause.** Auto-pulsing "new" badges are hostile.
+- **Respect `prefers-reduced-motion`** — drop transitions to 0.01s, keep only opacity/color changes.
+
+### 4. Microcopy
+
+- **Button verbs specific to the action.** Not "Submit" — "Send quote for review."
+- **Empty states with personality.** "No quotes yet. Start one — it takes about 3 minutes." Beats "No data."
+- **Error messages that acknowledge** — "That's not quite right — X needs to be Y" rather than "Invalid input."
+- **Success states that celebrate proportionally.** Saved draft = small checkmark. Bound a policy = confetti-adjacent.
+- **Loading copy that sets expectations.** "Matching you with carriers… usually 5 seconds" > spinner alone.
+
+### 5. Texture & depth
+
+Not every interface needs these, but they're how screens stop feeling generic:
+- **Noise overlay at 2–4% opacity** on dark backgrounds. Kills the plastic look.
+- **Subtle inner shadow on inputs** — `inset 0 1px 0 rgba(255,255,255,0.4)` on light themes suggests depth.
+- **Asymmetric card padding** — e.g., `24px 24px 20px 24px` sometimes feels better than all-24 because humans scan top-to-bottom.
+- **Left-align eyebrow decoration** — a 2px × 18px accent-color rule before a section label reads as editorial, not chrome.
+
+### 6. The small details
+
+- **Focus rings that feel on-brand** — `box-shadow: 0 0 0 3px rgba(brand, 0.2)` beats the default blue browser ring.
+- **Checkmark animation on save** — 300ms stroke-dash reveal, not a static green dot.
+- **Hover states that change border color**, not scale or shadow (which feel toy-like on dense forms).
+- **Caret-color matched to brand.** `caret-color: var(--brand)`.
+- **Chip alignment with inline icons** — baseline-align the icon to the text, don't center — centering looks off for small text.
+
+## What to avoid (AI-slop tells)
+
+- Purple-to-pink gradients on white.
+- "Gradient text" for things that aren't hero titles.
+- Emoji in UI chrome (buttons, headers).
+- `font-family: 'Inter', sans-serif` as the only typeface.
+- Drop-shadows the same size on cards, buttons, and modals (varied elevation is the whole point).
+- Buttons with `border-radius: 9999px` that are 32px tall (pill at small scale reads as "claimed to be premium, actually built in 20 min").
+- Glass-morphism backdrops without a real background image behind them.
+
+## Workflow
+
+1. **Name the feel.** In one sentence, write what's wrong. "Feels cheap because inputs have no shadow and everything is pure white on pure white." This grounds the rest.
+2. **Apply at most 3 levers from the list above.** Do not touch everything — diminishing returns.
+3. **Reload and look away and back.** Judge fresh, not against your memory of before.
+4. **Name one thing you resisted adding.** This keeps you honest — feel upgrades are often about resisting maximalism, not piling it on.
+5. **Show the user which levers you pulled** and invite them to push back on any that felt wrong.
+
+## Red flags during the pass
+
+If you catch yourself adding:
+- A new color variable that isn't in the design system
+- A third weight of the display font
+- An animation > 600ms
+- A shadow on a default-state button
+- An emoji inside a form label
+
+…stop. You're adding where you should be tuning.
+
+## Interactions
+
+- Runs best on a screen that already passed `/ui-ux-pro-max` and `/simplify-ui`.
+- Can safely coexist with `/ui` for a combined sweep.
+- If the user wants a redesign, escalate to `frontend-design:frontend-design`.

package/skills/simplify-ui/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: simplify-ui
+description: Ruthless subtraction pass on an existing UI — visual/UX reduction only. Use when the user says "cut it down", "too much going on", "too cluttered", "remove noise", "pare down", "less is more", "it's too busy", or wants the page trimmed without rebuilding it. This is the "remove before adding" lens — complementary to /ui (full polish pass), /ui-ux-pro-max (correctness audit), and /make-interfaces-feel-better (craft layer). For code-level deduplication, use the plugin /simplify instead.
+---
+
+# Simplify — remove before you add
+
+You are looking at a UI and cutting what doesn't earn its place. The default answer is **delete**. Every element has to justify why it survives. If you can't state its purpose in a short sentence, it goes.
+
+## The guiding question
+
+For every visible element on the screen, answer:
+
+> "What would break for the user if this weren't here?"
+
+If the answer is "nothing" or "aesthetics", delete it. If the answer names a concrete user failure, keep it — and then see if it can be smaller.
+
+## What to cut, in priority order
+
+### Tier 1 — cut without thinking
+
+1. **Section headers above single-item sections.** "LIABILITY COVERAGE" over a single field is structural vanity.
+2. **Helper text that restates the label.** "Enter your email address" under an "Email" field. Pick one.
+3. **Placeholders that duplicate labels.** Ditto.
+4. **Status pills identical to adjacent counts.** "5/5" badge next to a "5 of 5 complete" progress bar.
+5. **Default-zero values displayed as content.** `$0`, `0%`, `null` — render as empty.
+6. **Decorative icons** that don't carry meaning or affordance. Briefcase next to "Company" is ornament.
+7. **Explanatory captions** for patterns the user already knows ("Click Submit to submit").
+8. **"Powered by…" footers on internal tools.**
+9. **Animated spinners on < 200ms operations.** They flash and look broken.
+
+### Tier 2 — cut after a second look
+
+1. **Duplicate buttons.** "Save" at top and bottom of a form — keep one, usually the bottom if the form is long.
+2. **Multiple paths to the same action.** A "Create quote" primary button + a "+" FAB + a "New quote" menu item.
+3. **Breadcrumbs on 2-level-deep pages.** Overkill; use a back button.
+4. **Card shadows stacked on card borders.** Pick one.
+5. **Grid lines *and* alternating row backgrounds.** Pick one.
+6. **Count/progress indicators that update instantly.** If the user answered the field, they know.
+7. **Summary sentences above tables** that restate what the table shows. ("This table shows quotes. There are 3 quotes.")
+8. **Emoji or flag icons** next to text that already says the same thing.
+9. **Confirmation dialogs for non-destructive actions.** "Save draft?" — just save.
+
+### Tier 3 — cut with caution (verify with the user)
+
+1. **Tooltips on self-explanatory controls.** If the icon is standard (× for close), no tooltip needed — unless a11y is the reason.
+2. **Onboarding hints that persist after first use.**
+3. **Tutorial steps that could be inferred from labels.**
+4. **Analytics-only elements** that don't serve the user (tracking pixels belong in code, not chrome).
+
+## What not to cut (hold the line)
+
+- Labels, even when obvious — they are your a11y surface.
+- Error messages — always keep; tune the copy under `/make-interfaces-feel-better`.
+- Validation — never cut; maybe defer to blur instead of on-change.
+- Skip links and screen-reader-only text.
+- The single "Undo" or "Back" that lets users recover.
+
+## Density rules after simplification
+
+Once you've cut:
+- **3–6 fields per card.** Fewer = sleepy; more = oppressive.
+- **One accent color dominant per card.** Not one per chip.
+- **At most 2 type sizes per card** (label + input/value). Title of the card is the third.
+- **One CTA per screen region.** Multiple = the user has to choose, and they'd rather not.
+- **Zero horizontal scroll.** If the layout forces it on common widths, the layout is wrong.
+
+## Workflow
+
+1. **Screenshot or open the screen.** Read every visible string. Don't cut blind.
+2. **List every distinct element.** Cards, headers, chips, buttons, helper text, icons, images.
+3. **Mark each: keep / cut / reduce.** "Reduce" means the element stays but smaller/shorter/less prominent.
+4. **Cut Tier 1 items immediately.** No discussion.
+5. **Surface Tier 2/3 cuts as proposals** to the user before applying.
+6. **After the cut, measure.** Did vertical density improve? Did the primary action get more visible? If neither, you cut the wrong things.
+
+## Micro-patterns
+
+- **Collapse single-field sections into the parent card.** Don't delete the field, delete the section wrapper.
+- **Merge two adjacent chips with the same color into one.** "Required + Auto-filled" → "Auto-filled (required)".
+- **Replace "X of Y" with "Y - X remaining"** when remaining is what the user cares about.
+- **Fold secondary actions into an overflow menu (⋯).** Don't show 5 buttons when 1 primary + ⋯ works.
+- **Use whitespace as a divider** before reaching for a `<hr>` or border.
+
+## Red flags that you're over-cutting
+
+- Users can't tell which field is required.
+- A keyboard-only user can't move through the form.
+- A screen-reader user can't distinguish regions.
+- The page looks like a wireframe, not a product.
+- You removed something and then had to re-add it in the next session.
+
+## Interactions
+
+- Runs best after `/ui-ux-pro-max` (knows what's broken) and before `/make-interfaces-feel-better` (which adds back *quality*, not noise).
+- Combine with `/ui` for a full pass in one shot.
+- Do not run on a screen that's already minimalist — you'll cut into muscle.
+
+## One rule above all
+
+> Every element survives by earning its pixel count.
+
+If you wouldn't fight to keep it at the next design review, delete it now.