beaver-build 1.0.8 → 2.0.0

package/dist/index.js

@@ -38,6 +38,12 @@ var init_constants = __esm({
         value: "NUXT",
         description: "Upcoming...",
         disabled: true
+      },
+      HarnessOnly: {
+        display: "Apply AI Harness",
+        value: "HARNESS_ONLY",
+        description: "Add Claude Code harness to an existing project",
+        disabled: false
       }
     };
   }
@@ -288,10 +294,6 @@ var init_package_json = __esm({
       if (cart.testing === "PLAYWRIGHT") {
         scripts["test:e2e"] = "playwright test";
       }
-      if (cart.ai === "CLAUDE") {
-        scripts["docs:index"] = "node .claude/scripts/build-docs-index.mjs";
-        scripts["docs:lint"] = "node .claude/scripts/lint-docs-frontmatter.mjs";
-      }
       return JSON.stringify(
         {
           name: cart.projectName,
@@ -771,10 +773,55 @@ declare module '*.css' {
 });
 
 // src/scaffold/shared/claude-setup.ts
-var STATUS_ENUM, LANG_ENUM, docsTemplateMdTemplate, docsReadmeTemplate, docsIndexPlaceholderTemplate, docsSharedMjsTemplate, buildDocsIndexMjsTemplate, lintDocsFrontmatterMjsTemplate, docsFirstReminderShTemplate, claudeSettingsTemplate, docsSkillTemplate, docsWriterAgentTemplate, agentMemorySeedTemplate, buildClaudeFileMap;
+var AGENTS, TOOL_OVERRIDES, agentTools, agentMemoryFrontmatter, claudeHarnessTableTemplate, STATUS_ENUM, LANG_ENUM, docsTemplateMdTemplate, docsReadmeTemplate, docsIndexPlaceholderTemplate, docsSharedMjsTemplate, buildDocsIndexMjsTemplate, lintDocsFrontmatterMjsTemplate, docsFirstReminderShTemplate, TEST_WRITER_DEF, agentGuardMjsTemplate, claudeSettingsTemplate, docsSkillTemplate, docsWriterAgentTemplate, plannerAgentTemplate, advisorAgentTemplate, scoutAgentTemplate, plansReadmeTemplate, backlogReadmeTemplate, agentMemorySeedTemplate, validateStructureMjsTemplate, validatePlansMjsTemplate, buildClaudeFileMap;
 var init_claude_setup = __esm({
   "src/scaffold/shared/claude-setup.ts"() {
     "use strict";
+    AGENTS = [
+      {
+        name: "dev",
+        model: "sonnet",
+        writeScope: ["src/", "package.json", "tsconfig.json", "vite.config.ts", "biome.json", "eslint.config.js", ".github/"],
+        memory: true
+      },
+      {
+        name: "docs-writer",
+        model: "haiku",
+        writeScope: ["docs/"],
+        memory: true
+      },
+      {
+        name: "planner",
+        model: "sonnet",
+        writeScope: ["plans/"],
+        memory: true
+      },
+      {
+        name: "advisor",
+        model: "opus",
+        writeScope: [],
+        memory: true
+      },
+      {
+        name: "scout",
+        model: "haiku",
+        writeScope: [],
+        memory: false
+      }
+    ];
+    TOOL_OVERRIDES = {
+      advisor: "Read, Grep, Glob, Bash, WebFetch, WebSearch, Skill, TodoWrite",
+      scout: "Read, Grep, Glob, Skill"
+    };
+    agentTools = (agent) => {
+      if (TOOL_OVERRIDES[agent.name]) return TOOL_OVERRIDES[agent.name];
+      return agent.writeScope.length > 0 ? "Read, Grep, Glob, Write, Edit, Skill, TodoWrite" : "Read, Grep, Glob, Skill";
+    };
+    agentMemoryFrontmatter = (agent) => agent.memory ? "\nmemory: project" : "";
+    claudeHarnessTableTemplate = () => `| Brainstorming / trade-off analysis / "what's the best approach?" before any change | \`advisor\` | read-only; deepest source mental model; recommends, never edits |
+| Quick factual lookup about the code/docs (answer + \`path:line\`) | \`scout\` | read-only; cheap; for facts, not design reasoning |
+| Decomposing a story into a resumable plan | \`planner\` | owns \`plans/\`; writes phase files only, never code |
+| Analyzing requirements, writing/updating feature docs | \`docs-writer\` | owns \`docs/\`; rebuilds INDEX.md after every change |`;
     STATUS_ENUM = ["active", "draft", "deprecated"];
     LANG_ENUM = ["en", "vi"];
     docsTemplateMdTemplate = (flowEnum3, layerEnum3) => `---
@@ -831,14 +878,14 @@ Frontmatter-indexed task docs. \`INDEX.md\` is auto-generated \u2014 never hand-
 
 1. Copy \`docs/_template.md\`, fill ALL frontmatter fields (the index and lint are built from it).
 2. Save to the right directory per the table above.
-3. \`npm run docs:index\` \u2014 regenerates \`INDEX.md\`.
-4. \`npm run docs:lint\` \u2014 must pass before committing.
+3. \`node .claude/scripts/build-docs-index.mjs\` \u2014 regenerates \`INDEX.md\`.
+4. \`node .claude/scripts/lint-docs-frontmatter.mjs\` \u2014 must pass before committing.
 5. Commit the doc and \`INDEX.md\` together.
 `;
     docsIndexPlaceholderTemplate = () => `# Docs Index
 
 > Auto-generated by \`.claude/scripts/build-docs-index.mjs\` \u2014 do not edit by hand.
-> Run \`npm run docs:index\` to regenerate.
+> Run \`node .claude/scripts/build-docs-index.mjs\` to regenerate.
 `;
     docsSharedMjsTemplate = (flowEnum3, layerEnum3) => `// Shared helpers for docs tooling \u2014 single source of truth for the frontmatter schema.
 import { readdirSync, readFileSync } from 'fs';
@@ -903,7 +950,7 @@ export function walkDocs(dir = DOCS_DIR, records = []) {
 }
 `;
     buildDocsIndexMjsTemplate = () => `// Regenerates docs/INDEX.md from frontmatter. Deterministic (sorted) so diffs stay clean.
-// Run via: npm run docs:index
+// Run via: node .claude/scripts/build-docs-index.mjs
 import { writeFileSync } from 'fs';
 import { join } from 'path';
 import { walkDocs, DOCS_DIR } from './_docs-shared.mjs';
@@ -981,7 +1028,7 @@ writeFileSync(join(DOCS_DIR, 'INDEX.md'), lines.join('\\n').replace(/\\n+$/, '\\
 console.log('docs/INDEX.md updated \u2014 ' + records.length + ' doc(s), ' + withFm + ' with frontmatter.');
 `;
     lintDocsFrontmatterMjsTemplate = () => `// Validates every doc against the frontmatter schema. Exits non-zero on violation \u2192 CI-ready.
-// Run via: npm run docs:lint
+// Run via: node .claude/scripts/lint-docs-frontmatter.mjs
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { walkDocs, ENUMS, REQUIRED_FIELDS, DOCS_DIR } from './_docs-shared.mjs';
@@ -1052,6 +1099,88 @@ EOF
 fi
 exit 0
 `;
+    TEST_WRITER_DEF = {
+      name: "test-writer",
+      model: "haiku",
+      writeScope: ["src/", "test/", "tests/", "e2e/", "playwright/"],
+      memory: true
+    };
+    agentGuardMjsTemplate = (agents) => {
+      const scopesObj = {};
+      for (const agent of agents) {
+        scopesObj[agent.name] = agent.writeScope;
+      }
+      const scopesJson = JSON.stringify(scopesObj, null, 2);
+      return `// PreToolUse guard \u2014 registry-driven path enforcement.
+// Generated from the AGENTS registry; do not edit by hand.
+// Each agent may only write to its declared writeScope prefixes plus its own
+// .claude/agent-memory/<name>/ directory (implicit, added at runtime below).
+// Agents NOT in WRITE_SCOPES (unknown agents, main thread) pass through.
+// NOTE: writeScope is a heuristic backstop, not a precise ACL. Projects that
+// place test files under src/__tests__ instead of test/ or tests/ will need to
+// extend the test-writer scope \u2014 this guard is lenient for dev rather than tight.
+import { readFileSync } from 'fs';
+
+const WRITE_SCOPES = ${scopesJson};
+
+let payload;
+try {
+  payload = JSON.parse(readFileSync(0, 'utf-8'));
+} catch {
+  process.exit(0);
+}
+
+const agentType = payload.agent_type;
+// Unknown agent or main thread \u2014 pass through.
+if (!agentType || !(agentType in WRITE_SCOPES)) process.exit(0);
+
+const filePath = payload.tool_input?.file_path;
+if (!filePath) process.exit(0);
+
+// Normalize to a project-relative path when an absolute path is given.
+const cwd = payload.cwd ?? '';
+let rel = filePath;
+if (filePath.startsWith('/') && cwd && filePath.startsWith(cwd + '/')) {
+  rel = filePath.slice(cwd.length + 1);
+}
+
+const allowedPrefixes = WRITE_SCOPES[agentType];
+const memoryPrefix = \`.claude/agent-memory/\${agentType}/\`;
+
+// Always allow an agent to write its own memory dir (even read-only agents).
+if (rel.startsWith(memoryPrefix)) process.exit(0);
+
+// Read-only agents (empty writeScope): deny all other writes with a specific message.
+if (allowedPrefixes.length === 0) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: \`read-only agent may not write any file. \${agentType} attempted to write \${filePath}. Route implementation to the dev agent instead.\`,
+      },
+    })
+  );
+  process.exit(0);
+}
+
+// Allow if path is within the agent's declared scope.
+const allowed = allowedPrefixes.some((prefix) => rel.startsWith(prefix));
+
+if (allowed) process.exit(0);
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: \`\${agentType} may only write under [\${allowedPrefixes.join(', ')}] (and \${memoryPrefix}). Blocked write to \${filePath}. Route to the correct agent instead.\`,
+    },
+  })
+);
+process.exit(0);
+`;
+    };
     claudeSettingsTemplate = () => JSON.stringify(
       {
         permissions: {
@@ -1078,6 +1207,17 @@ exit 0
                 }
               ]
             }
+          ],
+          PreToolUse: [
+            {
+              matcher: "Write|Edit|MultiEdit",
+              hooks: [
+                {
+                  type: "command",
+                  command: 'node "$CLAUDE_PROJECT_DIR/.claude/scripts/agent-guard.mjs"'
+                }
+              ]
+            }
           ]
         },
         sandbox: {
@@ -1087,8 +1227,8 @@ exit 0
       null,
       2
     );
-    docsSkillTemplate = (projectName, slug, flowEnum3, layerEnum3) => `---
-name: ${slug}-docs
+    docsSkillTemplate = (projectName, slug4, flowEnum3, layerEnum3) => `---
+name: ${slug4}-docs
 description: How to find and write knowledge-base docs for ${projectName}. Use when asked "is there a doc about\u2026", "explain the X feature/flow", "document this", "write a spec", or the Vietnamese equivalents ("c\xF3 t\xE0i li\u1EC7u v\u1EC1\u2026", "gi\u1EA3i th\xEDch flow\u2026", "vi\u1EBFt docs/spec\u2026"). Also use before modifying any documented feature.
 ---
 
@@ -1112,14 +1252,14 @@ description: How to find and write knowledge-base docs for ${projectName}. Use w
 3. Keywords: lowercase, prefer real symbol/file names an engineer would grep for.
 4. Rebuild + validate, then commit doc and INDEX.md together:
    \`\`\`bash
-   npm run docs:index && npm run docs:lint
+   node .claude/scripts/build-docs-index.mjs && node .claude/scripts/lint-docs-frontmatter.mjs
    \`\`\`
 `;
-    docsWriterAgentTemplate = (projectName, slug) => `---
+    docsWriterAgentTemplate = (projectName, slug4, agent) => `---
 name: docs-writer
 description: "Documentation agent for ${projectName} \u2014 analyzes requirements from any source (conversation, tickets, Slack) and maintains docs/. <example>user: 'Here are the requirements for the profile page, write them up' \u2192 docs-writer <commentary>synthesizing requirements into a feature spec</commentary></example> <example>user: 'We just finished the auth refactor, document what changed' \u2192 docs-writer <commentary>post-task knowledge capture</commentary></example> <example>user: 'Update the home spec \u2014 the hero section was redesigned' \u2192 docs-writer <commentary>doc maintenance</commentary></example>"
-model: haiku
-memory: project
+model: ${agent.model}${agentMemoryFrontmatter(agent)}
+tools: ${agentTools(agent)}
 ---
 
 You are the documentation agent for ${projectName}. You own \`docs/\`.
@@ -1128,7 +1268,7 @@ You are the documentation agent for ${projectName}. You own \`docs/\`.
 
 1. Read \`.claude/agent-memory/docs-writer/MEMORY.md\`.
 2. Read \`docs/README.md\` (placement + naming rules) and \`docs/INDEX.md\` (what already exists).
-3. Load the \`${slug}-docs\` skill.
+3. Load the \`${slug4}-docs\` skill.
 
 ## Workflow
 
@@ -1136,7 +1276,7 @@ You are the documentation agent for ${projectName}. You own \`docs/\`.
 2. Check INDEX.md for an existing doc to update before creating a new one.
 3. Copy \`docs/_template.md\`; fill ALL frontmatter fields (feature, flow, layer, status, lang, keywords, updated). Specs describe WHAT, not HOW.
 4. Save per docs/README.md rules: \`docs/features/<feature>/<feature>.spec.en.md\` for feature specs, \`<topic>.en.md\` for findings, \`docs/architecture/\` for cross-cutting topics.
-5. Run \`npm run docs:index\` then \`npm run docs:lint\` \u2014 both must succeed.
+5. Run \`node .claude/scripts/build-docs-index.mjs\` then \`node .claude/scripts/lint-docs-frontmatter.mjs\` \u2014 both must succeed.
 6. If the feature introduces new domain nouns, add them to the \`trigger\` list in \`.claude/scripts/docs-first-reminder.sh\`.
 7. Report created/updated paths. Append lessons to \`.claude/agent-memory/docs-writer/MEMORY.md\`.
 
@@ -1145,28 +1285,675 @@ You are the documentation agent for ${projectName}. You own \`docs/\`.
 - Never hand-edit \`docs/INDEX.md\`.
 - Never edit application code \u2014 you write markdown and run the docs scripts only.
 - Never commit or push.
+`;
+    plannerAgentTemplate = (projectName, agent) => `---
+name: planner
+description: "Planning agent for ${projectName} \u2014 analyzes a request/story and produces a professional, detailed, resumable implementation plan under plans/. Splits work into phase files so a failure in one phase never breaks the whole flow; execution can resume from the unfinished phase. <example>user: 'Break this story into a step-by-step plan we can resume' \u2192 planner <commentary>resumable multi-phase plan</commentary></example> <example>user: 'Plan the rollout for the new feature' \u2192 planner <commentary>decompose a large feature into ordered, verifiable phases</commentary></example> <example>user: 'Fix this small bug' \u2192 dev, NOT planner <commentary>small, single-pass change \u2014 code directly</commentary></example> <example>user: 'Write a spec for X' \u2192 docs-writer, NOT planner <commentary>specs describe WHAT; plans describe HOW/when</commentary></example>"
+model: ${agent.model}${agentMemoryFrontmatter(agent)}
+tools: ${agentTools(agent)}
+---
+
+You are the planning agent for ${projectName}. You own \`plans/\`. You produce the plan; the \`dev\` agent executes it.
+
+## Onboarding protocol (in order, before writing any plan)
+
+1. Read \`.claude/agent-memory/planner/MEMORY.md\` \u2014 accumulated planning gotchas.
+2. Read \`plans/README.md\` \u2014 folder layout, file naming, and frontmatter contract.
+3. Read \`docs/INDEX.md\` and the relevant \`docs/features/<feature>/\` spec(s) \u2014 the spec is your source of truth for WHAT. If no relevant spec exists, STOP and tell the user to run the docs-writer agent first.
+4. Skim the code under change only enough to anchor the plan in real file paths.
+
+## Workflow
+
+1. Restate the request and surface ambiguity. If interpretations conflict, ask \u2014 do not guess.
+2. Decompose the work into the **minimum** set of ordered phases. Each phase is independently completable and leaves the repo in a working state. Do not invent speculative phases.
+3. Write \`plans/<slug>/00-overview.md\` (goal, scope, non-goals, and the **Ordered phases** tracker table \u2014 see below) and one \`plans/<slug>/NN-<phase>.md\` per phase.
+4. Every phase file MUST be resumable on its own \u2014 see Phase file contract. Reference real source paths and the relevant \`docs/\` spec.
+5. Report the created plan paths and the recommended starting phase. Append durable planning lessons to \`.claude/agent-memory/planner/MEMORY.md\`.
+
+## Phase file contract (this is what makes plans resumable)
+
+Each \`NN-<phase>.md\` begins with frontmatter:
+
+\`\`\`
+---
+phase: NN
+title: <short title>
+status: pending        # pending | in-progress | done | blocked
+depends_on: [<NN>, ...]
+---
+\`\`\`
+
+Body, in this order:
+- **Goal** \u2014 one sentence; what "done" means.
+- **Steps** \u2014 a \`- [ ]\` checklist; each item is a concrete, single action tied to a real path.
+- **Verify** \u2014 explicit, runnable success criteria. A phase is only \`done\` when these pass.
+- **Notes / risks** \u2014 gotchas, rollback hints.
+
+The executor resumes by finding the first phase whose \`status\` is not \`done\` and continuing at its first unchecked step.
+
+## Progress tracker (00-overview.md is the single index)
+
+\`00-overview.md\` is the only tracker \u2014 never add a separate \`index.md\` per folder. End it with an **Ordered phases** table that doubles as the resume-from view:
+
+\`\`\`
+| # | Phase | Status | Steps | Updated |
+|---|---|---|---|---|
+| 01 | <phase> | pending | 0/<n> | <ISO date> |
+\`\`\`
+
+- **Status** mirrors each phase file's frontmatter \`status\`; **Steps** is \`<checked>/<total>\` of that phase's \`- [ ]\` checklist; **Updated** is the ISO date the row last changed.
+- This table is the one place that aggregates across phases. Keep it in sync whenever a phase's status, step count, or block state changes; a \`blocked\` row carries its \`backlog/<id>\` link inline.
+
+## Backlog integration
+
+- A phase that the executor parks gets \`status: blocked\` and a link to a \`backlog/<id>\` entry (see \`backlog/README.md\`). Treat blocked phases as paused, not failed \u2014 they don't invalidate completed work.
+- When a backlog item is revived, read it for context and fold its **Suggested direction** into new or amended phases here. Backlog holds context; \`plans/\` holds the executable plan.
+
+## Hard rules
+
+- Write ONLY under \`plans/\` (and your own \`.claude/agent-memory/planner/\`). Never edit source code, never write code, never run/modify the build. Your toolset has no Bash, and a PreToolUse hook hard-blocks any write outside \`plans/\` \u2014 if you feel the urge to implement, produce the plan and hand off to \`dev\` instead.
+- Never write feature specs \u2014 that is docs-writer's job (specs = WHAT, plans = HOW/when). Flag when a spec is missing instead of writing one.
+- Plans are consumable artifacts: keep them concrete and current, not aspirational prose.
+- Never edit \`docs/INDEX.md\` or any docs/ file.
+- Never commit or push \u2014 a human does that.
+- Non-blocking follow-up work (spec gaps, deferred tasks, adjacent improvements) must be filed as a \`backlog/<NNNN>-<slug>.md\` entry (see \`backlog/README.md\`). Do NOT leave follow-up work as prose in a plan's overview or phase files \u2014 prose in done plans is archived and lost.
+`;
+    advisorAgentTemplate = (projectName, slug4, agent) => `---
+name: advisor
+description: "Read-only brainstorming & advisory agent for ${projectName} \u2014 the engineer who understands the source logic most deeply. Reads the code, reasons about trade-offs, and returns the best, most optimal recommendation; never edits anything. <example>user: 'Should this be one flat interface or split apart? Talk me through it' \u2192 advisor <commentary>design brainstorm / trade-off analysis, no code change</commentary></example> <example>user: 'What is the cleanest way to add this option without bloating things?' \u2192 advisor <commentary>wants the optimal approach before any implementation</commentary></example> <example>user: 'Add the option' \u2192 dev, NOT advisor <commentary>actual implementation belongs to dev</commentary></example> <example>user: 'Break this into a resumable plan' \u2192 planner, NOT advisor <commentary>plan artifacts belong to planner</commentary></example>"
+model: ${agent.model}${agentMemoryFrontmatter(agent)}
+tools: ${agentTools(agent)}
+---
+
+You are the advisor for ${projectName}. You are the engineer who holds the **deepest, most accurate mental model of the source** and the trade-offs baked into it. Your job is to read, reason, and recommend \u2014 to brainstorm with the user and hand them the single best path forward. You do not write code, docs, or plans; \`dev\`, \`docs-writer\`, and \`planner\` do that after you've clarified the thinking.
+
+## Onboarding protocol (in order, before advising)
+
+1. Read \`.claude/agent-memory/advisor/MEMORY.md\` \u2014 accumulated architectural insights and recurring trade-offs.
+2. Read \`docs/INDEX.md\` and the relevant \`docs/features/<feature>/\` spec(s) for the area in question \u2014 the spec is the source of truth for WHAT.
+3. Load the \`${slug4}-conventions\` skill for the project's patterns and rules.
+4. Read the actual source under discussion. Never advise from memory or assumption when the file is one Read away \u2014 ground every claim in a real path/line.
+
+## Workflow
+
+1. Restate the question and the real goal behind it. If interpretations conflict, surface them \u2014 don't silently pick one.
+2. Read enough source to be certain. Trace the real data flow rather than guessing at it.
+3. Brainstorm: lay out the viable options with their concrete trade-offs (simplicity, coupling, correctness, maintenance cost).
+4. **Give a recommendation, not a survey.** Name the single best option, say why it wins, and cite the files/lines that justify it. Note the cheapest next step and which agent owns it (\`dev\` / \`planner\` / \`docs-writer\`).
+5. Append durable architectural insights to \`.claude/agent-memory/advisor/MEMORY.md\`.
+
+## What "best advice" means here
+
+- Favor the **minimum** change that solves the problem. Call out over-engineering explicitly.
+- Optimal \u2260 clever. Prefer the option a senior engineer would call obvious over the one that's impressive.
+- When the user's instinct is wrong, say so plainly and explain the cost \u2014 pushing back is the job, not friction.
+
+## Hard rules
+
+- **Read-only. Never edit, create, or delete any file** \u2014 not source, not \`docs/\`, not \`plans/\`, not \`backlog/\`. The only file you ever write is your own \`.claude/agent-memory/advisor/MEMORY.md\` (insights). If a change is warranted, recommend it and route it to the owning agent.
+- Never run the build, never commit, never push.
+- Ground claims in real paths/lines; if you haven't read it, say so instead of asserting.
+- Hand off, don't implement: end with a clear, actionable recommendation and who should execute it.
+`;
+    scoutAgentTemplate = (projectName, slug4, agent) => `---
+name: scout
+description: "Fast, cheap read-only Q&A & lookup agent for ${projectName} \u2014 reads, synthesizes, and answers in a few sentences with path:line citations. Use for factual questions about the codebase/docs, not design reasoning (\u2192 advisor) or implementation (\u2192 dev). <example>user: 'What version does this project pin for X?' \u2192 scout <commentary>factual lookup, answer + cite the source</commentary></example> <example>user: 'Is there a spec for feature X yet?' \u2192 scout <commentary>doc existence check via docs/INDEX.md</commentary></example> <example>user: 'Should this be split apart? Talk me through the trade-offs' \u2192 advisor, NOT scout <commentary>design reasoning belongs to advisor</commentary></example> <example>user: 'Add the option' \u2192 dev, NOT scout <commentary>implementation belongs to dev</commentary></example>"
+model: ${agent.model}
+tools: ${agentTools(agent)}
+---
+
+You are scout for ${projectName}. You answer factual questions about the codebase and docs **quickly and cheaply** \u2014 read what you need, synthesize, and reply in a few sentences. You do not reason about design trade-offs (that is \`advisor\`), and you never edit anything (that is \`dev\` / \`docs-writer\` / \`planner\`).
+
+## Lookup protocol (DOCS-FIRST)
+
+1. If the question touches a documented feature, start at \`docs/INDEX.md\` and read the relevant \`docs/features/<feature>/\` spec before opening source. Load the \`${slug4}-docs\` skill when you need to locate a doc.
+2. Otherwise grep/glob to the right file fast. Trace the real data flow rather than guessing.
+3. Read only the lines you need to be certain \u2014 excerpts, not whole files. Stop as soon as you can answer.
+
+## Answer style
+
+- **Lead with the answer**, then a one-line why/where. Keep it to a few sentences.
+- **Always cite** the real \`path:line\` you got it from. If you didn't read it, say so \u2014 never assert from memory.
+- If the question is ambiguous, ask one short clarifying question instead of guessing.
+
+## Hard rules
+
+- **Read-only.** Never create, edit, or delete any file. No Bash, no build, no commit.
+- **Stay in your lane \u2014 hand off, don't expand scope:**
+  - Design / trade-off / "what's the best approach?" \u2192 recommend \`advisor\`.
+  - Implementation, bug fix, new option \u2192 recommend \`dev\`.
+  - Writing or updating docs \u2192 recommend \`docs-writer\`; multi-phase plan \u2192 \`planner\`.
+- If answering would require running code or reasoning through a non-trivial design decision, stop and route it rather than overreaching.
+`;
+    plansReadmeTemplate = () => `# plans/
+
+Resumable, phase-by-phase implementation plans authored by the \`planner\` agent and executed by the \`dev\` agent.
+
+A plan is a **consumable** artifact (short-lived, kept in sync with reality), distinct from \`docs/\` which holds long-lived feature specs (WHAT). Plans describe **HOW and in what order** work gets done.
+
+## Layout
+
+\`\`\`
+plans/
+  <slug>/
+    00-overview.md      goal, scope, non-goals, + the progress tracker (see below)
+    01-<phase>.md       one file per phase
+    02-<phase>.md
+    ...
+\`\`\`
+
+- \`<slug>\` is kebab-case, derived from the feature/story.
+- Phases are numbered \`NN-\` so they sort in execution order.
+
+\`00-overview.md\` is the single tracker for the plan \u2014 there is **no separate \`index.md\`**. Its **Ordered phases** table is the at-a-glance "where are we" view; each phase file's \`status\` frontmatter is the per-phase source of truth. The table aggregates across phases, so keep it in sync whenever a phase's status or step count changes.
+
+## Progress tracker (the Ordered phases table)
+
+\`00-overview.md\` ends with this table \u2014 it is what an executor reads first to know where to resume:
+
+\`\`\`
+| # | Phase | Status | Steps | Updated |
+|---|---|---|---|---|
+| 01 | <phase> | done | 5/5 | 2026-01-01 |
+| 02 | <phase> | in-progress | 2/6 | 2026-01-01 |
+\`\`\`
+
+- **Status** \u2014 mirrors the phase file's frontmatter \`status\` (\`pending | in-progress | done | blocked\`).
+- **Steps** \u2014 \`<checked>/<total>\` of the phase's \`- [ ]\` checklist; the quick "how far in" signal.
+- **Updated** \u2014 ISO date the row last changed.
+
+A \`blocked\` row should also carry the \`backlog/<id>\` link inline (e.g. \`blocked \u2192 backlog/0003\`).
+
+## Phase file frontmatter
+
+\`\`\`
+---
+phase: NN
+title: <short title>
+status: pending        # pending | in-progress | done | blocked
+depends_on: [<NN>, ...]
+---
+\`\`\`
+
+Body sections, in order: **Goal**, **Steps** (\`- [ ]\` checklist), **Verify** (runnable success criteria), **Notes / risks**.
+
+## Resuming a plan
+
+1. Open \`00-overview.md\` and read the **Ordered phases** table for overall progress.
+2. Find the first phase whose \`status\` is not \`done\`; its **Steps** cell shows how far in it is.
+3. Continue at its first unchecked \`- [ ]\` step in the phase file.
+4. After each step, update the phase's **Steps** count and **Updated** date in the table. When a phase's \`Verify\` passes, set its frontmatter \`status: done\` and flip the table row to \`done\`.
+
+A failure in one phase never invalidates completed phases \u2014 fix and resume from the unfinished phase.
+
+## Blocked phases \u2192 backlog
+
+If a phase can't proceed and the cause isn't fixable right now (missing info, needs a user decision, environment/out-of-scope), don't loop. Apply the **park rule** in \`backlog/README.md\`: set the phase \`status: blocked\`, file a \`backlog/<id>\` entry, link both ways (\`[[backlog/<id>]]\` from the phase; the entry's \`source:\` points back to the phase file), then move on to the next workable phase.
+
+## Plan lifecycle and archival
+
+When all phases are \`done\`, the plan becomes a completed artifact \u2014 it can either:
+- **Remain in \`plans/\`** as historical record (git preserves it; useful for auditing how the work was actually decomposed).
+- **Be archived** to \`plans/.archive/<slug>/\` (keep it searchable but out of the active directory).
+- **Be deleted** if context is not valuable (rare; prefer archival so git history is preserved).
+
+Choose based on project norms. The key: **plans are owned by whoever executed them** (usually \`dev\`) and the decision to archive/delete is theirs. Do not leave a stale plan in \`plans/\` \u2014 either keep it active (if next phases are coming) or archive it. The \`00-overview.md\` progress table is the arbiter: if all rows are \`done\` and no new work is queued, the plan is complete.
+`;
+    backlogReadmeTemplate = () => `# backlog/
+
+Unfinished work: blockers that can't be solved right now, technical debt, or anything **deliberately deferred** so it doesn't derail the current flow.
+
+How it differs from \`docs/\` and \`plans/\`:
+
+| | \`docs/\` | \`plans/\` | \`backlog/\` |
+|---|---|---|---|
+| Nature | WHAT \u2014 long-lived spec | HOW/when \u2014 phases to run | deferred work / blockers / tech debt |
+| Lifecycle | long-lived | consumable, deleted when done | append-only log, lives until \`resolved\` |
+| Author | docs-writer | planner | any agent that hits a blocker (usually \`dev\`) |
+
+A backlog item is **not** a plan. When an item is revived, \`planner\` reads it and produces new phases under \`plans/\` \u2014 backlog holds context, not the executable plan.
+
+## Park rule (this is what stops the token-wasting loop)
+
+Applies while executing a step/phase and hitting a problem:
+
+> If a step **fails twice** and the cause is **not fixable right now** \u2014 missing info, needs a user decision, environment error, or out of scope \u2014 then **STOP, do not retry a third time**:
+> 1. Set the owning phase \`status: blocked\` (see \`plans/README.md\`).
+> 2. File a new entry in \`backlog/\` (template below); its **Tried** section must list what already failed so it isn't repeated.
+> 3. Link both ways: the phase file points to \`backlog/<id>\`, the entry points back to the phase.
+> 4. Move on to the next workable phase/task. Tell the user it was parked \u2014 don't silently skip it.
+
+If the error is fixable on the spot, just fix it \u2014 this rule is only for real blockers.
+
+## Layout
+
+One item = one file: \`backlog/<NNN>-<slug>.md\` (\`NNN\` ascending so items sort and are easy to reference, e.g. "backlog/004").
+
+## Frontmatter
+
+\`\`\`
+---
+id: NNN
+title: <short title>
+status: open          # open | resolved | wontfix
+source: plans/<slug>/NN-<phase>.md   # or "conversation", or the originating file path
+severity: low         # low | medium | high
+created: YYYY-MM-DD
+---
+\`\`\`
+
+Body, in order:
+
+- **Symptom** \u2014 what happened and where (real file paths).
+- **Tried** \u2014 what was run/changed and how it failed. The most important section: prevents repeating failed attempts.
+- **Why parked** \u2014 why it can't be solved now (missing info / needs user / environment / out of scope).
+- **Suggested direction** \u2014 the next step if any, or the question the user needs to answer.
+
+Link to other phases/specs/items with \`[[path]]\`.
+
+## Lifecycle
+
+- When solved: set \`status: resolved\` and add a one-line conclusion at the end of the body \u2014 **don't delete the file** (keep the history). To drop it entirely, set \`status: wontfix\` with a reason.
+- When revived: hand the context to \`planner\` to create new phases under \`plans/\`; the entry stays \`open\` until the work is actually done.
 `;
     agentMemorySeedTemplate = (agentName) => `# ${agentName} \u2014 Agent Memory
 
-Append durable, non-obvious gotchas and patterns discovered while working \u2014 one bullet each, newest first. Link related docs/ files. Read this file at the start of every session.
+Append durable, non-obvious gotchas and patterns discovered while working \u2014 one bullet each, newest first. Link related docs/ files. Read this file at the start of every session.
+
+_(no entries yet)_
+`;
+    validateStructureMjsTemplate = (agents) => {
+      const scopesObj = {};
+      for (const agent of agents) {
+        scopesObj[agent.name] = agent.writeScope;
+      }
+      const scopesJson = JSON.stringify(scopesObj, null, 2);
+      return `// Mechanically checks derived invariants between the AGENTS registry, emitted
+// agent .md files, and the guard. Generated from the AGENTS registry at scaffold
+// time \u2014 do not edit by hand.
+// Run via: node .claude/scripts/validate-structure.mjs
+import { readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+// Baked at scaffold time from the AGENTS registry.
+const WRITE_SCOPES = ${scopesJson};
+
+// Minimal frontmatter parser (no external deps \u2014 inlined from _docs-shared.mjs pattern).
+function parseFrontmatter(content) {
+  const match = content.match(/^---\\n([\\s\\S]*?)\\n---/);
+  if (!match) return null;
+  const meta = {};
+  for (const line of match[1].split('\\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if (!key) continue;
+    // Strip inline comments.
+    value = value.replace(/\\s+#.*$/, '').trim();
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      meta[key] = inner === ''
+        ? []
+        : inner.split(',').map((item) => item.trim().replace(/^['"]|['"]$/g, ''));
+    } else {
+      meta[key] = value.replace(/^['"]|['"]$/g, '');
+    }
+  }
+  return meta;
+}
+
+const AGENTS_DIR = '.claude/agents';
+const errors = [];
+
+// 1. Read and parse all agent .md files.
+let agentFiles;
+try {
+  agentFiles = readdirSync(AGENTS_DIR).filter((f) => f.endsWith('.md'));
+} catch {
+  console.error('validate-structure: cannot read ' + AGENTS_DIR);
+  process.exit(1);
+}
+
+const parsed = [];
+for (const file of agentFiles) {
+  const fullPath = join(AGENTS_DIR, file);
+  const content = readFileSync(fullPath, 'utf-8');
+  const fm = parseFrontmatter(content);
+  if (!fm) {
+    errors.push(file + ': missing frontmatter block');
+    continue;
+  }
+  const name = fm.name ?? file.replace(/\\.md$/, '');
+  const toolsRaw = fm.tools ?? '';
+  parsed.push({ file, name, toolsRaw });
+}
+
+// 2. Check read-only constraint: if writeScope is empty, tools must not include Write or Edit.
+for (const { file, name, toolsRaw } of parsed) {
+  if (!(name in WRITE_SCOPES)) continue; // unknown agent \u2014 skip
+  const scope = WRITE_SCOPES[name];
+  if (scope.length > 0) continue; // write-capable agent \u2014 constraint does not apply
+  // Read-only agent: assert no Write/Edit in tools list.
+  const tools = toolsRaw.split(',').map((t) => t.trim());
+  for (const tool of tools) {
+    if (tool === 'Write' || tool === 'Edit') {
+      errors.push(
+        file + ': read-only agent "' + name + '" must not have "' + tool +
+        '" in its tools: list (writeScope is empty)'
+      );
+    }
+  }
+}
+
+// 3. Check uniqueness of primary owned directories (first element of writeScope).
+const primaryDirOwners = {};
+for (const [agentName, scope] of Object.entries(WRITE_SCOPES)) {
+  if (scope.length === 0) continue; // read-only agents have no primary dir
+  const primaryDir = scope[0];
+  if (primaryDirOwners[primaryDir]) {
+    errors.push(
+      'agents "' + primaryDirOwners[primaryDir] + '" and "' + agentName +
+      '" share the same primary owned directory "' + primaryDir + '"'
+    );
+  } else {
+    primaryDirOwners[primaryDir] = agentName;
+  }
+}
+
+if (errors.length > 0) {
+  console.error('validate-structure: failed with ' + errors.length + ' error(s):');
+  for (const error of errors) console.error('  - ' + error);
+  process.exit(1);
+}
+console.log('validate-structure: passed.');
+`;
+    };
+    validatePlansMjsTemplate = () => `// Mechanically checks plan/backlog consistency across four invariants.
+// Run via: node .claude/scripts/validate-plans.mjs
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const PLANS_DIR = 'plans';
+const BACKLOG_DIR = 'backlog';
+
+// Minimal frontmatter parser \u2014 same pattern as validate-structure.mjs (no external deps).
+function parseFrontmatter(content) {
+  const match = content.match(/^---\\n([\\s\\S]*?)\\n---/);
+  if (!match) return null;
+  const meta = {};
+  for (const line of match[1].split('\\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if (!key) continue;
+    value = value.replace(/\\s+#.*$/, '').trim();
+    if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      meta[key] = inner === ''
+        ? []
+        : inner.split(',').map((item) => item.trim().replace(/^['"]|['"]$/g, ''));
+    } else {
+      meta[key] = value.replace(/^['"]|['"]$/g, '');
+    }
+  }
+  return meta;
+}
+
+// Parse the "Ordered phases" Markdown table from an overview file body.
+// Returns array of { num, slug, status } where num is zero-padded (e.g. "01").
+// Only parses rows from the section headed "## Ordered phases" (case-insensitive).
+function parseOrderedPhasesTable(content) {
+  const rows = [];
+  // Find the "Ordered phases" section and extract only that table.
+  const sectionMatch = content.match(/##\\s+Ordered phases\\b[\\s\\S]*?(?=\\n##\\s|\\n---\\n|$)/i);
+  if (!sectionMatch) return rows;
+  const section = sectionMatch[0];
+  for (const line of section.split('\\n')) {
+    // Match data rows: | 01 | slug | status | ... |
+    if (!/^\\|\\s*\\d+\\s*\\|/.test(line)) continue;
+    const cells = line.split('|').map((c) => c.trim()).filter(Boolean);
+    if (cells.length < 3) continue;
+    const num = cells[0].padStart(2, '0');
+    const slug = cells[1];
+    const status = cells[2].toLowerCase();
+    rows.push({ num, slug, status });
+  }
+  return rows;
+}
+
+// Collect active plan dirs (skip .archive and README.md).
+function getActivePlanDirs() {
+  let entries;
+  try {
+    entries = readdirSync(PLANS_DIR, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory() && e.name !== '.archive' && !e.name.startsWith('.'))
+    .map((e) => e.name);
+}
+
+// Collect all plan dirs including .archive.
+function getAllPlanDirs() {
+  let entries;
+  try {
+    const archiveEntries = readdirSync(join(PLANS_DIR, '.archive'), { withFileTypes: true });
+    const activeEntries = readdirSync(PLANS_DIR, { withFileTypes: true });
+    return [
+      ...activeEntries.filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => ({ name: e.name, archived: false })),
+      ...archiveEntries.filter((e) => e.isDirectory()).map((e) => ({ name: e.name, archived: true })),
+    ];
+  } catch {
+    return getActivePlanDirs().map((name) => ({ name, archived: false }));
+  }
+}
+
+const errors = [];
+const warnings = [];
+
+// \u2500\u2500 Check A \u2014 Phase table \u2194 frontmatter status consistency \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+for (const planDir of getActivePlanDirs()) {
+  const overviewPath = join(PLANS_DIR, planDir, '00-overview.md');
+  if (!existsSync(overviewPath)) continue;
+  const overviewContent = readFileSync(overviewPath, 'utf-8');
+  const rows = parseOrderedPhasesTable(overviewContent);
+  for (const { num, slug, status: tableStatus } of rows) {
+    const phaseFile = join(PLANS_DIR, planDir, \`\${num}-\${slug}.md\`);
+    if (!existsSync(phaseFile)) {
+      warnings.push(\`WARN  \${phaseFile}: phase file not found (table row \${num} references it)\`);
+      continue;
+    }
+    const phaseContent = readFileSync(phaseFile, 'utf-8');
+    const fm = parseFrontmatter(phaseContent);
+    if (!fm) {
+      warnings.push(\`WARN  \${phaseFile}: missing frontmatter \u2014 cannot compare with table status\`);
+      continue;
+    }
+    const fmStatus = (fm.status ?? '').toLowerCase();
+    if (fmStatus !== tableStatus) {
+      warnings.push(
+        \`WARN  \${phaseFile}: phase frontmatter status "\${fmStatus}" but table row says "\${tableStatus}"\`
+      );
+    }
+  }
+}
+
+// \u2500\u2500 Check B \u2014 All-done plans not yet archived \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+for (const planDir of getActivePlanDirs()) {
+  const overviewPath = join(PLANS_DIR, planDir, '00-overview.md');
+  if (!existsSync(overviewPath)) continue;
+  const overviewContent = readFileSync(overviewPath, 'utf-8');
+  const rows = parseOrderedPhasesTable(overviewContent);
+  if (rows.length === 0) continue;
+  if (rows.every(({ status }) => status === 'done')) {
+    warnings.push(
+      \`WARN  plans/\${planDir}/00-overview.md: all phases done \u2014 consider archiving to plans/.archive/\`
+    );
+  }
+}
+
+// \u2500\u2500 Check C \u2014 Backlog ID uniqueness and sequence \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+const REQUIRED_BACKLOG_FIELDS = ['id', 'title', 'status', 'source', 'severity', 'created'];
+const VALID_BACKLOG_STATUSES = ['open', 'resolved', 'wontfix'];
+const seenIds = new Set();
+
+let backlogFiles;
+try {
+  backlogFiles = readdirSync(BACKLOG_DIR).filter((f) => /^\\d{4}-.*\\.md$/.test(f));
+} catch {
+  backlogFiles = [];
+}
+
+for (const file of backlogFiles) {
+  const filePath = join(BACKLOG_DIR, file);
+  const content = readFileSync(filePath, 'utf-8');
+  const fm = parseFrontmatter(content);
+  const prefix = file.slice(0, 4); // "0001"
+
+  if (!fm) {
+    errors.push(\`ERROR backlog/\${file}: missing frontmatter block\`);
+    continue;
+  }
+
+  // Required fields
+  for (const field of REQUIRED_BACKLOG_FIELDS) {
+    if (fm[field] === undefined || fm[field] === '') {
+      errors.push(\`ERROR backlog/\${file}: missing required frontmatter field "\${field}"\`);
+    }
+  }
+
+  // ID uniqueness
+  const id = fm.id ?? '';
+  if (id) {
+    if (seenIds.has(id)) {
+      errors.push(\`ERROR backlog/\${file}: duplicate id "\${id}"\`);
+    } else {
+      seenIds.add(id);
+    }
+
+    // ID/filename prefix match
+    if (id.padStart(4, '0') !== prefix) {
+      errors.push(\`ERROR backlog/\${file}: filename prefix "\${prefix}" does not match id "\${id}"\`);
+    }
+  }
+
+  // Status enum
+  const status = fm.status ?? '';
+  if (status && !VALID_BACKLOG_STATUSES.includes(status)) {
+    errors.push(
+      \`ERROR backlog/\${file}: invalid status "\${status}" (allowed: \${VALID_BACKLOG_STATUSES.join(', ')})\`
+    );
+  }
+}
+
+// \u2500\u2500 Check D \u2014 Two-way links between blocked phases and backlog entries \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// Collect all phase files (non-overview, non-archive).
+function collectPhaseFiles() {
+  const result = [];
+  for (const planDir of getActivePlanDirs()) {
+    let files;
+    try {
+      files = readdirSync(join(PLANS_DIR, planDir)).filter(
+        (f) => f.endsWith('.md') && f !== '00-overview.md'
+      );
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      result.push({ path: join(PLANS_DIR, planDir, f), rel: \`plans/\${planDir}/\${f}\` });
+    }
+  }
+  return result;
+}
+
+for (const { path: phaseFilePath, rel } of collectPhaseFiles()) {
+  const content = readFileSync(phaseFilePath, 'utf-8');
+  const fm = parseFrontmatter(content);
+  if (!fm || fm.status !== 'blocked') continue;
+
+  // Look for a backlog link in the body.
+  const bodyMatch = content.match(/^---\\n[\\s\\S]*?\\n---\\n([\\s\\S]*)$/);
+  const body = bodyMatch ? bodyMatch[1] : content;
+  const backlogLinkMatch = body.match(/backlog\\/(\\d{4})/g);
+
+  if (!backlogLinkMatch) {
+    warnings.push(\`WARN  \${rel}: status blocked but no backlog link found in body\`);
+    continue;
+  }
+
+  for (const linkStr of backlogLinkMatch) {
+    const id = linkStr.replace('backlog/', '');
+    // Find the backlog file with this prefix.
+    const matchingFile = (backlogFiles ?? []).find((f) => f.startsWith(id));
+    if (!matchingFile) {
+      warnings.push(\`WARN  \${rel}: references \${linkStr} but no backlog/\${id}-*.md file found\`);
+      continue;
+    }
+    const backlogContent = readFileSync(join(BACKLOG_DIR, matchingFile), 'utf-8');
+    const backlogFm = parseFrontmatter(backlogContent);
+    const source = backlogFm?.source ?? '';
+    if (!source.includes(rel.replace(\`plans/\`, ''))) {
+      warnings.push(
+        \`WARN  backlog/\${matchingFile}: source field "\${source}" does not reference \${rel}\`
+      );
+    }
+  }
+}
+
+// \u2500\u2500 Report \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+const totalErrors = errors.length;
+const totalWarnings = warnings.length;
+
+if (totalErrors > 0 || totalWarnings > 0) {
+  console.log(
+    \`validate-plans: \${totalErrors} error(s), \${totalWarnings} warning(s):\`
+  );
+  for (const e of errors) console.error('  ' + e);
+  for (const w of warnings) console.warn('  ' + w);
+}
 
-_(no entries yet)_
+if (totalErrors > 0) {
+  console.error(\`validate-plans: failed with \${totalErrors} error(s).\`);
+  process.exit(1);
+} else if (totalWarnings > 0) {
+  console.log(\`validate-plans: passed with \${totalWarnings} warning(s).\`);
+} else {
+  console.log('validate-plans: passed.');
+}
 `;
     buildClaudeFileMap = (params) => {
-      const { projectName, slug, flowEnum: flowEnum3, layerEnum: layerEnum3 } = params;
+      const { projectName, slug: slug4, flowEnum: flowEnum3, layerEnum: layerEnum3 } = params;
+      const agentDef = (name) => {
+        const found = AGENTS.find((a) => a.name === name);
+        if (!found) throw new Error(`Agent "${name}" not found in AGENTS registry`);
+        return found;
+      };
       const files = [
         { relativePath: "CLAUDE.md", content: params.claudeMd },
         { relativePath: ".claude/settings.json", content: claudeSettingsTemplate() },
         { relativePath: ".claude/scripts/_docs-shared.mjs", content: docsSharedMjsTemplate(flowEnum3, layerEnum3) },
         { relativePath: ".claude/scripts/build-docs-index.mjs", content: buildDocsIndexMjsTemplate() },
         { relativePath: ".claude/scripts/lint-docs-frontmatter.mjs", content: lintDocsFrontmatterMjsTemplate() },
+        { relativePath: ".claude/scripts/validate-structure.mjs", content: validateStructureMjsTemplate([...AGENTS, ...params.testing ? [TEST_WRITER_DEF] : []]) },
+        { relativePath: ".claude/scripts/validate-plans.mjs", content: validatePlansMjsTemplate() },
         { relativePath: ".claude/scripts/docs-first-reminder.sh", content: docsFirstReminderShTemplate(params.reminderTrigger) },
-        { relativePath: `.claude/skills/${slug}-conventions/SKILL.md`, content: params.conventionsSkill },
-        { relativePath: `.claude/skills/${slug}-docs/SKILL.md`, content: docsSkillTemplate(projectName, slug, flowEnum3, layerEnum3) },
+        { relativePath: ".claude/scripts/agent-guard.mjs", content: agentGuardMjsTemplate([...AGENTS, ...params.testing ? [TEST_WRITER_DEF] : []]) },
+        { relativePath: `.claude/skills/${slug4}-conventions/SKILL.md`, content: params.conventionsSkill },
+        { relativePath: `.claude/skills/${slug4}-docs/SKILL.md`, content: docsSkillTemplate(projectName, slug4, flowEnum3, layerEnum3) },
         { relativePath: ".claude/agents/dev.md", content: params.devAgent },
-        { relativePath: ".claude/agents/docs-writer.md", content: docsWriterAgentTemplate(projectName, slug) },
+        { relativePath: ".claude/agents/docs-writer.md", content: docsWriterAgentTemplate(projectName, slug4, agentDef("docs-writer")) },
+        { relativePath: ".claude/agents/planner.md", content: plannerAgentTemplate(projectName, agentDef("planner")) },
+        { relativePath: ".claude/agents/advisor.md", content: advisorAgentTemplate(projectName, slug4, agentDef("advisor")) },
+        { relativePath: ".claude/agents/scout.md", content: scoutAgentTemplate(projectName, slug4, agentDef("scout")) },
         { relativePath: ".claude/agent-memory/dev/MEMORY.md", content: agentMemorySeedTemplate("dev") },
         { relativePath: ".claude/agent-memory/docs-writer/MEMORY.md", content: agentMemorySeedTemplate("docs-writer") },
+        { relativePath: ".claude/agent-memory/planner/MEMORY.md", content: agentMemorySeedTemplate("planner") },
+        { relativePath: ".claude/agent-memory/advisor/MEMORY.md", content: agentMemorySeedTemplate("advisor") },
+        { relativePath: "plans/README.md", content: plansReadmeTemplate() },
+        { relativePath: "backlog/README.md", content: backlogReadmeTemplate() },
         { relativePath: "docs/README.md", content: docsReadmeTemplate() },
         { relativePath: "docs/INDEX.md", content: docsIndexPlaceholderTemplate() },
         { relativePath: "docs/_template.md", content: docsTemplateMdTemplate(flowEnum3, layerEnum3) },
@@ -1176,7 +1963,7 @@ _(no entries yet)_
         files.push(
           { relativePath: ".claude/agents/test-writer.md", content: params.testing.testWriterAgent },
           { relativePath: ".claude/agent-memory/test-writer/MEMORY.md", content: agentMemorySeedTemplate("test-writer") },
-          { relativePath: `.claude/skills/${slug}-test-author/SKILL.md`, content: params.testing.testAuthorSkill }
+          { relativePath: `.claude/skills/${slug4}-test-author/SKILL.md`, content: params.testing.testAuthorSkill }
         );
       }
       return files;
@@ -1213,7 +2000,7 @@ var init_claude_setup2 = __esm({
       const hasVitest = cart.testing === "VITEST";
       const hasPlaywright = cart.testing === "PLAYWRIGHT";
       const hasTesting = cart.testing !== "NOT_USING";
-      const slug = projectSlug(cart);
+      const slug4 = projectSlug(cart);
       const stack = [
         "React 19, TypeScript 5.8, Vite 6",
         hasRouter ? "TanStack Router v1.144.0 (file-based routes in src/routes/)" : null,
@@ -1230,8 +2017,9 @@ var init_claude_setup2 = __esm({
         cart.linter !== "NOT_USING" ? "- `npm run lint` \u2014 lint code" : null,
         hasVitest ? "- `npm run test:run` \u2014 run unit/component tests once (`npm test` for watch)" : null,
         hasPlaywright ? "- `npm run test:e2e` \u2014 run Playwright E2E tests" : null,
-        "- `npm run docs:index` \u2014 regenerate docs/INDEX.md (run after any doc change)",
-        "- `npm run docs:lint` \u2014 validate docs frontmatter (CI-ready, exits non-zero on violation)"
+        "- `node .claude/scripts/build-docs-index.mjs` \u2014 regenerate docs/INDEX.md (run after any doc change)",
+        "- `node .claude/scripts/lint-docs-frontmatter.mjs` \u2014 validate docs frontmatter (CI-ready, exits non-zero on violation)",
+        "- `node .claude/scripts/validate-plans.mjs` \u2014 check plan/backlog consistency (table\u2194frontmatter, archived, ID gaps, two-way links)"
       ].filter(Boolean);
       const fsdArchitecture = `\`\`\`
 app        \u2192 app shell, providers, global setup
@@ -1357,18 +2145,20 @@ ${testSection}## Agent Routing
 
 | Task / trigger | Agent | Notes |
 |---|---|---|
-| Feature work or bug fix in \`src/\` | \`dev\` | MUST read relevant \`docs/features/\` spec before coding |
-| Analyzing requirements, writing/updating feature docs | \`docs-writer\` | owns \`docs/\`; rebuilds INDEX.md after every change |${testWriterRow}
+${claudeHarnessTableTemplate()}
+| Feature work or bug fix in \`src/\` | \`dev\` | MUST read relevant \`docs/features/\` spec before coding |${testWriterRow}
+
+**PARK RULE (anti-loop):** when executing a step/phase, if it fails twice and the cause isn't fixable right now (missing info, needs a user decision, environment, or out-of-scope), STOP \u2014 don't retry a third time. Set the phase \`status: blocked\`, file a \`backlog/<id>\` entry (record what was already tried so it isn't repeated), link both ways, tell the user it was parked, and move on to the next workable item. See \`backlog/README.md\`.
 
 Each agent has persistent memory at \`.claude/agent-memory/<agent>/MEMORY.md\` \u2014 agents read it on start and append new gotchas. Do NOT use the general assistant for work an agent owns \u2014 always delegate.
 
 ## Task Documentation Convention
 
-After any non-trivial fix or new pattern: copy \`docs/_template.md\`, fill the frontmatter, save as \`docs/features/<feature>/<topic>.en.md\` (or \`docs/architecture/\` for cross-cutting topics), then run \`npm run docs:index\` and commit the doc together with \`INDEX.md\`. Validate with \`npm run docs:lint\`.
+After any non-trivial fix or new pattern: copy \`docs/_template.md\`, fill the frontmatter, save as \`docs/features/<feature>/<topic>.en.md\` (or \`docs/architecture/\` for cross-cutting topics), then run \`node .claude/scripts/build-docs-index.mjs\` and commit the doc together with \`INDEX.md\`. Validate with \`node .claude/scripts/lint-docs-frontmatter.mjs\`.
 
 ## Further Reading + DOCS-FIRST RULE
 
-Skills: \`.claude/skills/${slug}-conventions\` (architecture depth), \`.claude/skills/${slug}-docs\` (how to query the knowledge base)${hasTesting ? `, \`.claude/skills/${slug}-test-author\` (test conventions)` : ""}.
+Skills: \`.claude/skills/${slug4}-conventions\` (architecture depth), \`.claude/skills/${slug4}-docs\` (how to query the knowledge base)${hasTesting ? `, \`.claude/skills/${slug4}-test-author\` (test conventions)` : ""}.
 
 **DOCS-FIRST RULE:** for any request to describe, explain, or modify a documented feature, you MUST grep \`docs/\` frontmatter and read the relevant docs BEFORE opening source files \u2014 and state what the docs already covered. Start at \`docs/INDEX.md\`.
 
@@ -1412,9 +2202,9 @@ _(Trade-offs made and alternatives rejected.)_
     };
     conventionsSkillTemplate = (cart) => {
       const isFsd = cart.layout === "FSD";
-      const slug = projectSlug(cart);
+      const slug4 = projectSlug(cart);
       return `---
-name: ${slug}-conventions
+name: ${slug4}-conventions
 description: Coding conventions and architecture rules for ${cart.projectName}. Use when writing or reviewing ANY code under src/ \u2014 components, pages, hooks${cart.stateManagement === "ZUSTAND" ? ", stores" : ""}${cart.router === "TANSTACK_ROUTER" ? ", routes" : ""}, or styling. Triggers on tasks mentioning components, pages, layout, naming, imports, or project structure.
 ---
 
@@ -1465,10 +2255,10 @@ Check the reference implementation (\`src/pages/home${isFsd ? "/" : ".tsx"}\`) f
 `;
     };
     testAuthorSkillTemplate = (cart) => {
-      const slug = projectSlug(cart);
+      const slug4 = projectSlug(cart);
       const hasVitest = cart.testing === "VITEST";
       return `---
-name: ${slug}-test-author
+name: ${slug4}-test-author
 description: Centralized test conventions for ${cart.projectName}. Use when asked to "write a test", "add a spec", "cover this with tests", or fix a failing test. All test code lives under test/ \u2014 never inside src/.
 ---
 
@@ -1494,7 +2284,7 @@ ${hasVitest ? `- Unit tests import via the \`@/\` alias and explicit vitest impo
 `;
     };
     devAgentTemplate = (cart) => {
-      const slug = projectSlug(cart);
+      const slug4 = projectSlug(cart);
       const hasTesting = cart.testing !== "NOT_USING";
       const testWriterExample = hasTesting ? " <example>user: 'Cover the login form with tests' \u2192 test-writer, NOT dev <commentary>test authoring belongs to test-writer</commentary></example>" : "";
       const delegationRule = hasTesting ? "- Never write tests (delegate to test-writer) or docs (delegate to docs-writer); flag when they are needed." : "- Never write docs (delegate to docs-writer); flag when they are needed.";
@@ -1511,7 +2301,7 @@ You are the implementation agent for ${cart.projectName}.
 
 1. Read \`.claude/agent-memory/dev/MEMORY.md\` \u2014 your accumulated gotchas.
 2. Read \`docs/INDEX.md\` and the relevant \`docs/features/<feature>/\` spec for the task.
-3. Load the \`${slug}-conventions\` skill for layer rules and patterns.
+3. Load the \`${slug4}-conventions\` skill for layer rules and patterns.
 4. Read the code under change.
 
 If no relevant feature spec exists, STOP and tell the user to run the docs-writer agent first.
@@ -1523,6 +2313,10 @@ If no relevant feature spec exists, STOP and tell the user to run the docs-write
 3. Verify (build${hasTesting ? " + run the relevant tests" : ""}); report results faithfully.
 4. Append newly discovered gotchas/patterns to \`.claude/agent-memory/dev/MEMORY.md\`.
 
+## Park rule (anti-loop)
+
+If a step fails twice and the cause isn't fixable right now (missing info, needs a user decision, environment, out-of-scope), STOP \u2014 do not retry a third time. File a \`backlog/<id>\` entry per \`backlog/README.md\` (its **Tried** section must list what already failed so it isn't repeated), set the owning phase \`status: blocked\` and link both ways, tell the user it was parked, then continue with the next workable task. Don't loop, don't silently skip.
+
 ## Hard rules
 
 - Never commit or push \u2014 a human does that.
@@ -1531,7 +2325,7 @@ ${delegationRule}
 `;
     };
     testWriterAgentTemplate = (cart) => {
-      const slug = projectSlug(cart);
+      const slug4 = projectSlug(cart);
       return `---
 name: test-writer
 description: "Test authoring agent for ${cart.projectName} \u2014 writes tests and their paired spec.md contracts, only under test/. Runs after docs-writer has produced the feature spec. <example>user: 'Cover the home page with tests' \u2192 test-writer <commentary>test authoring from an existing feature spec</commentary></example> <example>user: 'Add edge-case tests for the date validator' \u2192 test-writer <commentary>narrow test scope, reads the spec for edge cases</commentary></example> <example>user: 'Fix the validation bug the test caught' \u2192 dev, NOT test-writer <commentary>app-code changes belong to dev</commentary></example>"
@@ -1545,7 +2339,7 @@ You are the test-writing agent for ${cart.projectName}. You write ONLY under \`t
 
 1. Read \`.claude/agent-memory/test-writer/MEMORY.md\`.
 2. Read the feature spec: \`docs/features/<feature>/<feature>.spec.en.md\` \u2014 requirements and edge cases drive the test plan. If it does not exist, STOP and request docs-writer first.
-3. Load the \`${slug}-test-author\` skill and \`test/README.md\`.
+3. Load the \`${slug4}-test-author\` skill and \`test/README.md\`.
 
 ## Workflow
 
@@ -2478,10 +3272,6 @@ var init_package_json2 = __esm({
       } else if (cart.linter === "ESLINT") {
         scripts["lint"] = "eslint .";
       }
-      if (cart.ai === "CLAUDE") {
-        scripts["docs:index"] = "node .claude/scripts/build-docs-index.mjs";
-        scripts["docs:lint"] = "node .claude/scripts/lint-docs-frontmatter.mjs";
-      }
       return JSON.stringify(
         {
           name: cart.projectName,
@@ -2680,7 +3470,7 @@ var init_claude_setup3 = __esm({
     claudeMdTemplate2 = (cart) => {
       const hasZustand = cart.stateManagement === "ZUSTAND";
       const hasQuery = cart.query === "TANSTACK_QUERY";
-      const slug = projectSlug2(cart);
+      const slug4 = projectSlug2(cart);
       const stack = [
         "React 19, TypeScript 5.8, Vite 6",
         "Chrome Extension Manifest V3 (popup-only)",
@@ -2694,8 +3484,9 @@ var init_claude_setup3 = __esm({
         "- `npm run build` \u2014 type-check + production build into `dist/`",
         "- `npm run build-extension` \u2014 build + copy `manifest.json` into `dist/`; load `dist/` as an unpacked extension at chrome://extensions",
         cart.linter !== "NOT_USING" ? "- `npm run lint` \u2014 lint code" : null,
-        "- `npm run docs:index` \u2014 regenerate docs/INDEX.md (run after any doc change)",
-        "- `npm run docs:lint` \u2014 validate docs frontmatter (CI-ready, exits non-zero on violation)"
+        "- `node .claude/scripts/build-docs-index.mjs` \u2014 regenerate docs/INDEX.md (run after any doc change)",
+        "- `node .claude/scripts/lint-docs-frontmatter.mjs` \u2014 validate docs frontmatter (CI-ready, exits non-zero on violation)",
+        "- `node .claude/scripts/validate-plans.mjs` \u2014 check plan/backlog consistency (table\u2194frontmatter, archived, ID gaps, two-way links)"
       ].filter(Boolean);
       const keyPatterns = [
         `**Popup lifecycle \u2014 the popup unmounts when it closes:**
@@ -2776,18 +3567,20 @@ ${keyPatterns.join("\n\n")}
 
 | Task / trigger | Agent | Notes |
 |---|---|---|
+${claudeHarnessTableTemplate()}
 | Feature work or bug fix in \`src/\` or \`manifest.json\` | \`dev\` | MUST read relevant \`docs/features/\` spec before coding |
-| Analyzing requirements, writing/updating feature docs | \`docs-writer\` | owns \`docs/\`; rebuilds INDEX.md after every change |
+
+**PARK RULE (anti-loop):** when executing a step/phase, if it fails twice and the cause isn't fixable right now (missing info, needs a user decision, environment, or out-of-scope), STOP \u2014 don't retry a third time. Set the phase \`status: blocked\`, file a \`backlog/<id>\` entry (record what was already tried so it isn't repeated), link both ways, tell the user it was parked, and move on to the next workable item. See \`backlog/README.md\`.
 
 Each agent has persistent memory at \`.claude/agent-memory/<agent>/MEMORY.md\` \u2014 agents read it on start and append new gotchas. Do NOT use the general assistant for work an agent owns \u2014 always delegate.
 
 ## Task Documentation Convention
 
-After any non-trivial fix or new pattern: copy \`docs/_template.md\`, fill the frontmatter, save as \`docs/features/<feature>/<topic>.en.md\` (or \`docs/architecture/\` for cross-cutting topics), then run \`npm run docs:index\` and commit the doc together with \`INDEX.md\`. Validate with \`npm run docs:lint\`.
+After any non-trivial fix or new pattern: copy \`docs/_template.md\`, fill the frontmatter, save as \`docs/features/<feature>/<topic>.en.md\` (or \`docs/architecture/\` for cross-cutting topics), then run \`node .claude/scripts/build-docs-index.mjs\` and commit the doc together with \`INDEX.md\`. Validate with \`node .claude/scripts/lint-docs-frontmatter.mjs\`.
 
 ## Further Reading + DOCS-FIRST RULE
 
-Skills: \`.claude/skills/${slug}-conventions\` (architecture depth), \`.claude/skills/${slug}-docs\` (how to query the knowledge base).
+Skills: \`.claude/skills/${slug4}-conventions\` (architecture depth), \`.claude/skills/${slug4}-docs\` (how to query the knowledge base).
 
 **DOCS-FIRST RULE:** for any request to describe, explain, or modify a documented feature, you MUST grep \`docs/\` frontmatter and read the relevant docs BEFORE opening source files \u2014 and state what the docs already covered. Start at \`docs/INDEX.md\`.
 
@@ -2831,10 +3624,10 @@ _(Trade-offs made and alternatives rejected.)_
 `;
     };
     conventionsSkillTemplate2 = (cart) => {
-      const slug = projectSlug2(cart);
+      const slug4 = projectSlug2(cart);
       const hasZustand = cart.stateManagement === "ZUSTAND";
       return `---
-name: ${slug}-conventions
+name: ${slug4}-conventions
 description: Coding conventions and architecture rules for ${cart.projectName} (Chrome extension, MV3 popup). Use when writing or reviewing ANY code under src/ \u2014 components, hooks${hasZustand ? ", stores" : ""}, or styling \u2014 or when touching manifest.json. Triggers on tasks mentioning popup, manifest, components, naming, imports, or project structure.
 ---
 
@@ -2881,7 +3674,7 @@ Check \`src/App.tsx\` first, then the docs (\`docs/INDEX.md\`), then ask.
 `;
     };
     devAgentTemplate2 = (cart) => {
-      const slug = projectSlug2(cart);
+      const slug4 = projectSlug2(cart);
       return `---
 name: dev
 description: "Implementation agent for ${cart.projectName} \u2014 all feature work and bug fixes under src/ and manifest.json. <example>user: 'Add a settings toggle to the popup' \u2192 dev <commentary>feature work in src/; dev reads the feature spec first, then implements</commentary></example> <example>user: 'The popup crashes on empty data \u2014 fix it' \u2192 dev <commentary>bug fix inside a documented feature</commentary></example> <example>user: 'Write a spec for the options page' \u2192 docs-writer, NOT dev <commentary>doc authoring belongs to docs-writer</commentary></example>"
@@ -2895,7 +3688,7 @@ You are the implementation agent for ${cart.projectName}.
 
 1. Read \`.claude/agent-memory/dev/MEMORY.md\` \u2014 your accumulated gotchas.
 2. Read \`docs/INDEX.md\` and the relevant \`docs/features/<feature>/\` spec for the task.
-3. Load the \`${slug}-conventions\` skill for structure rules and patterns.
+3. Load the \`${slug4}-conventions\` skill for structure rules and patterns.
 4. Read the code under change.
 
 If no relevant feature spec exists, STOP and tell the user to run the docs-writer agent first.
@@ -2907,6 +3700,10 @@ If no relevant feature spec exists, STOP and tell the user to run the docs-write
 3. Verify (build; for manifest/extension changes run \`npm run build-extension\` and report what to check at chrome://extensions); report results faithfully.
 4. Append newly discovered gotchas/patterns to \`.claude/agent-memory/dev/MEMORY.md\`.
 
+## Park rule (anti-loop)
+
+If a step fails twice and the cause isn't fixable right now (missing info, needs a user decision, environment, out-of-scope), STOP \u2014 do not retry a third time. File a \`backlog/<id>\` entry per \`backlog/README.md\` (its **Tried** section must list what already failed so it isn't repeated), set the owning phase \`status: blocked\` and link both ways, tell the user it was parked, then continue with the next workable task. Don't loop, don't silently skip.
+
 ## Hard rules
 
 - Never commit or push \u2014 a human does that.
@@ -3125,6 +3922,484 @@ var init_chrome_extension2 = __esm({
   }
 });
 
+// src/options/harness-only/constants/index.ts
+var HARNESS_MENU_PROJECT_TYPE;
+var init_constants4 = __esm({
+  "src/options/harness-only/constants/index.ts"() {
+    "use strict";
+    HARNESS_MENU_PROJECT_TYPE = {
+      ReactVite: {
+        display: "React + Vite",
+        value: "REACT_VITE",
+        description: "React + Vite project",
+        disabled: false
+      },
+      ChromeExtension: {
+        display: "Chrome Extension",
+        value: "CHROME_EXTENSION",
+        description: "Chrome Extension project",
+        disabled: false
+      },
+      Generic: {
+        display: "Other (Generic)",
+        value: "GENERIC",
+        description: "Any other project",
+        disabled: false
+      }
+    };
+  }
+});
+
+// src/scaffold/harness-only/templates/react-vite-skeleton.ts
+var slug, claudeMdTemplate3, conventionsSkillTemplate3, devAgentTemplate3, seedDocsTemplate, getReactViteHarnessFileMap;
+var init_react_vite_skeleton = __esm({
+  "src/scaffold/harness-only/templates/react-vite-skeleton.ts"() {
+    "use strict";
+    init_claude_setup();
+    slug = (cart) => cart.projectName.toLowerCase().replace(/_/g, "-");
+    claudeMdTemplate3 = (cart) => `# ${cart.projectName}
+
+> This project uses a Claude Code harness for AI-assisted development.
+> Run \`claude /init\` to auto-generate a detailed CLAUDE.md tailored to this codebase.
+
+## Quick start
+
+\`\`\`bash
+npm run dev
+npm run build
+\`\`\`
+
+## Docs
+
+- \`docs/INDEX.md\` \u2014 knowledge base index (auto-generated)
+- \`node .claude/scripts/build-docs-index.mjs\` \u2014 regenerate index after adding a doc
+- \`node .claude/scripts/lint-docs-frontmatter.mjs\` \u2014 validate docs frontmatter
+`;
+    conventionsSkillTemplate3 = (cart) => `---
+name: ${slug(cart)}-conventions
+description: Coding conventions and architecture rules for ${cart.projectName} (React + Vite). Use when writing or reviewing ANY code in this project.
+---
+
+# ${cart.projectName} \u2014 Conventions
+
+## Stack
+
+React 19, TypeScript, Vite
+
+## Architecture
+
+This project uses a feature-slice structure. Check the source layout and run \`claude /init\` to generate detailed conventions.
+
+## General rules
+
+- TypeScript strict mode \u2014 no \`any\`, no unchecked assertions
+- Co-locate component, hook, and type in the same folder
+- Barrel exports via \`index.ts\`
+`;
+    devAgentTemplate3 = (cart) => `---
+name: dev
+description: "Implementation agent for ${cart.projectName}. Use for feature work and bug fixes."
+model: sonnet
+---
+
+You are the implementation agent for ${cart.projectName} (React + Vite project).
+
+## Onboarding
+
+1. Read \`.claude/agent-memory/dev/MEMORY.md\`.
+2. Read \`CLAUDE.md\` for project overview and commands.
+3. Load the \`${slug(cart)}-conventions\` skill.
+
+## Park rule (anti-loop)
+
+If a step fails twice and the cause isn't fixable right now (missing info, needs a user decision, environment, out-of-scope), STOP \u2014 do not retry a third time. File a \`backlog/<id>\` entry per \`backlog/README.md\` (its **Tried** section must list what already failed so it isn't repeated), set the owning phase \`status: blocked\` and link both ways, tell the user it was parked, then continue with the next workable task. Don't loop, don't silently skip.
+
+## Hard rules
+
+- Never commit or push.
+- Run lint and type-check before reporting a task done.
+- Docs-first: check \`docs/INDEX.md\` before modifying a documented feature.
+`;
+    seedDocsTemplate = (cart) => [
+      {
+        relativePath: "docs/features/home/home.spec.en.md",
+        content: `---
+title: Home \u2014 Feature Spec
+feature: home
+flow: ui
+layer: _cross
+status: draft
+lang: en
+related: []
+keywords: [home]
+updated: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
+---
+
+# Home
+
+## Context
+
+Starting feature doc for ${cart.projectName}. Replace with real content.
+
+## Solution / Pattern
+
+_To be documented._
+`
+      }
+    ];
+    getReactViteHarnessFileMap = (cart) => buildClaudeFileMap({
+      projectName: cart.projectName,
+      slug: slug(cart),
+      flowEnum: ["ui", "data", "infra", "architecture", "_meta"],
+      layerEnum: ["app", "pages", "features", "entities", "shared", "_cross"],
+      reminderTrigger: "home|landing",
+      claudeMd: claudeMdTemplate3(cart),
+      conventionsSkill: conventionsSkillTemplate3(cart),
+      devAgent: devAgentTemplate3(cart),
+      seedDocs: seedDocsTemplate(cart)
+    });
+  }
+});
+
+// src/scaffold/harness-only/templates/chrome-extension-skeleton.ts
+var slug2, claudeMdTemplate4, conventionsSkillTemplate4, devAgentTemplate4, seedDocsTemplate2, getChromeExtensionHarnessFileMap;
+var init_chrome_extension_skeleton = __esm({
+  "src/scaffold/harness-only/templates/chrome-extension-skeleton.ts"() {
+    "use strict";
+    init_claude_setup();
+    slug2 = (cart) => cart.projectName.toLowerCase().replace(/_/g, "-");
+    claudeMdTemplate4 = (cart) => `# ${cart.projectName}
+
+> This project uses a Claude Code harness for AI-assisted development.
+> Run \`claude /init\` to auto-generate a detailed CLAUDE.md tailored to this codebase.
+
+## Quick start
+
+\`\`\`bash
+npm run dev
+npm run build-extension   # loads dist/ as unpacked extension at chrome://extensions
+\`\`\`
+
+## Docs
+
+- \`docs/INDEX.md\` \u2014 knowledge base index (auto-generated)
+- \`node .claude/scripts/build-docs-index.mjs\` \u2014 regenerate index after adding a doc
+- \`node .claude/scripts/lint-docs-frontmatter.mjs\` \u2014 validate docs frontmatter
+`;
+    conventionsSkillTemplate4 = (cart) => `---
+name: ${slug2(cart)}-conventions
+description: Coding conventions and architecture rules for ${cart.projectName} (Chrome Extension). Use when writing or reviewing ANY code in this project.
+---
+
+# ${cart.projectName} \u2014 Conventions
+
+## Stack
+
+React 19, TypeScript, Vite, Chrome Extension Manifest V3
+
+## Architecture
+
+Popup-centric structure. Check the source layout and run \`claude /init\` to generate detailed conventions.
+
+## General rules
+
+- TypeScript strict mode \u2014 no \`any\`, no unchecked assertions
+- Manifest permissions: request only what's needed
+- No cross-origin requests from content scripts without explicit host permissions
+`;
+    devAgentTemplate4 = (cart) => `---
+name: dev
+description: "Implementation agent for ${cart.projectName}. Use for feature work and bug fixes."
+model: sonnet
+---
+
+You are the implementation agent for ${cart.projectName} (Chrome Extension project).
+
+## Onboarding
+
+1. Read \`.claude/agent-memory/dev/MEMORY.md\`.
+2. Read \`CLAUDE.md\` for project overview and commands.
+3. Load the \`${slug2(cart)}-conventions\` skill.
+
+## Park rule (anti-loop)
+
+If a step fails twice and the cause isn't fixable right now (missing info, needs a user decision, environment, out-of-scope), STOP \u2014 do not retry a third time. File a \`backlog/<id>\` entry per \`backlog/README.md\` (its **Tried** section must list what already failed so it isn't repeated), set the owning phase \`status: blocked\` and link both ways, tell the user it was parked, then continue with the next workable task. Don't loop, don't silently skip.
+
+## Hard rules
+
+- Never commit or push.
+- Run lint and type-check before reporting a task done.
+- Docs-first: check \`docs/INDEX.md\` before modifying a documented feature.
+`;
+    seedDocsTemplate2 = (cart) => [
+      {
+        relativePath: "docs/features/popup/popup.spec.en.md",
+        content: `---
+title: Popup \u2014 Feature Spec
+feature: popup
+flow: ui
+layer: popup
+status: draft
+lang: en
+related: []
+keywords: [popup]
+updated: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
+---
+
+# Popup
+
+## Context
+
+Starting feature doc for ${cart.projectName}. Replace with real content.
+
+## Solution / Pattern
+
+_To be documented._
+`
+      }
+    ];
+    getChromeExtensionHarnessFileMap = (cart) => buildClaudeFileMap({
+      projectName: cart.projectName,
+      slug: slug2(cart),
+      flowEnum: ["ui", "data", "extension", "infra", "_meta"],
+      layerEnum: ["popup", "components", "hooks", "lib", "utils", "_cross"],
+      reminderTrigger: "popup|manifest",
+      claudeMd: claudeMdTemplate4(cart),
+      conventionsSkill: conventionsSkillTemplate4(cart),
+      devAgent: devAgentTemplate4(cart),
+      seedDocs: seedDocsTemplate2(cart)
+    });
+  }
+});
+
+// src/scaffold/harness-only/templates/generic-skeleton.ts
+var slug3, claudeMdTemplate5, conventionsSkillTemplate5, devAgentTemplate5, seedDocsTemplate3, getGenericHarnessFileMap;
+var init_generic_skeleton = __esm({
+  "src/scaffold/harness-only/templates/generic-skeleton.ts"() {
+    "use strict";
+    init_claude_setup();
+    slug3 = (cart) => cart.projectName.toLowerCase().replace(/_/g, "-");
+    claudeMdTemplate5 = (cart) => `# ${cart.projectName}
+
+> This project uses a Claude Code harness for AI-assisted development.
+> Run \`claude /init\` to auto-generate a detailed CLAUDE.md tailored to this codebase.
+
+## Docs
+
+- \`docs/INDEX.md\` \u2014 knowledge base index (auto-generated)
+- \`node .claude/scripts/build-docs-index.mjs\` \u2014 regenerate index after adding a doc
+- \`node .claude/scripts/lint-docs-frontmatter.mjs\` \u2014 validate docs frontmatter
+`;
+    conventionsSkillTemplate5 = (cart) => `---
+name: ${slug3(cart)}-conventions
+description: Coding conventions for ${cart.projectName}. Run \`claude /init\` to replace with project-specific content.
+---
+
+# ${cart.projectName} \u2014 Conventions
+
+> Run \`claude /init\` in this project to generate detailed, codebase-specific conventions.
+`;
+    devAgentTemplate5 = (cart) => `---
+name: dev
+description: "Implementation agent for ${cart.projectName}."
+model: sonnet
+---
+
+You are the implementation agent for ${cart.projectName}.
+
+## Onboarding
+
+1. Read \`.claude/agent-memory/dev/MEMORY.md\`.
+2. Read \`CLAUDE.md\` for project overview.
+3. Load the \`${slug3(cart)}-conventions\` skill.
+
+## Park rule (anti-loop)
+
+If a step fails twice and the cause isn't fixable right now (missing info, needs a user decision, environment, out-of-scope), STOP \u2014 do not retry a third time. File a \`backlog/<id>\` entry per \`backlog/README.md\` (its **Tried** section must list what already failed so it isn't repeated), set the owning phase \`status: blocked\` and link both ways, tell the user it was parked, then continue with the next workable task. Don't loop, don't silently skip.
+
+## Hard rules
+
+- Never commit or push.
+- Docs-first: check \`docs/INDEX.md\` before modifying a documented feature.
+`;
+    seedDocsTemplate3 = (cart) => [
+      {
+        relativePath: "docs/features/home/home.spec.en.md",
+        content: `---
+title: Home \u2014 Feature Spec
+feature: home
+flow: ui
+layer: _cross
+status: draft
+lang: en
+related: []
+keywords: [home]
+updated: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
+---
+
+# Home
+
+## Context
+
+Starting feature doc for ${cart.projectName}. Replace with real content.
+
+## Solution / Pattern
+
+_To be documented._
+`
+      }
+    ];
+    getGenericHarnessFileMap = (cart) => buildClaudeFileMap({
+      projectName: cart.projectName,
+      slug: slug3(cart),
+      flowEnum: ["ui", "data", "infra", "_meta"],
+      layerEnum: ["src", "_cross"],
+      reminderTrigger: "home",
+      claudeMd: claudeMdTemplate5(cart),
+      conventionsSkill: conventionsSkillTemplate5(cart),
+      devAgent: devAgentTemplate5(cart),
+      seedDocs: seedDocsTemplate3(cart)
+    });
+  }
+});
+
+// src/scaffold/harness-only/index.ts
+var harness_only_exports = {};
+__export(harness_only_exports, {
+  scaffoldHarnessOnly: () => scaffoldHarnessOnly
+});
+import path4 from "path";
+import chalk6 from "chalk";
+import { createSpinner as createSpinner4 } from "nanospinner";
+var getFileMap, scaffoldHarnessOnly;
+var init_harness_only = __esm({
+  "src/scaffold/harness-only/index.ts"() {
+    "use strict";
+    init_constants();
+    init_utils();
+    init_errors();
+    init_react_vite_skeleton();
+    init_chrome_extension_skeleton();
+    init_generic_skeleton();
+    getFileMap = (cart) => {
+      switch (cart.projectType) {
+        case "REACT_VITE":
+          return getReactViteHarnessFileMap(cart);
+        case "CHROME_EXTENSION":
+          return getChromeExtensionHarnessFileMap(cart);
+        default:
+          return getGenericHarnessFileMap(cart);
+      }
+    };
+    scaffoldHarnessOnly = async (cart) => {
+      if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.HarnessOnly.value) return;
+      const { targetDirectory, projectName } = cart;
+      if (!await dirExists(targetDirectory)) {
+        throw new ScaffoldError(`Directory "${path4.relative(process.cwd(), targetDirectory)}" does not exist.`);
+      }
+      const spinner = createSpinner4(`Applying harness to ${chalk6.cyan(projectName)}...`).start();
+      try {
+        const fileMap = getFileMap(cart);
+        for (const { relativePath, content } of fileMap) {
+          await writeProjectFile(targetDirectory, relativePath, content);
+        }
+        spinner.success({
+          text: chalk6.green(`AI harness applied to ${chalk6.bold(projectName)} successfully!`)
+        });
+        console.log("");
+        console.log(chalk6.whiteBright("Next steps:"));
+        console.log(chalk6.cyan(`  cd ${path4.relative(process.cwd(), targetDirectory) || "."}`));
+        console.log(chalk6.cyan("  claude /init") + chalk6.gray("  \u2190 let Claude generate a detailed CLAUDE.md for your codebase"));
+        console.log("");
+      } catch (err) {
+        spinner.error({ text: chalk6.red("Harness setup failed.") });
+        if (err instanceof ScaffoldError) {
+          console.error(chalk6.red(err.message));
+        } else if (isNodeError(err)) {
+          console.error(chalk6.red(`File system error (${err.code}): ${err.message}`));
+        } else {
+          console.error(chalk6.red("An unexpected error occurred."), err);
+        }
+        process.exit(1);
+      }
+    };
+  }
+});
+
+// src/options/harness-only/index.ts
+var harness_only_exports2 = {};
+__export(harness_only_exports2, {
+  flowHarnessOnly: () => flowHarnessOnly
+});
+import { select as select3, input as input3 } from "@inquirer/prompts";
+import path5 from "path";
+import chalk7 from "chalk";
+var selectFromMenu3, menuTargetDirectory, menuProjectName3, menuProjectType, flowHarnessOnly;
+var init_harness_only2 = __esm({
+  "src/options/harness-only/index.ts"() {
+    "use strict";
+    init_constants();
+    init_constants4();
+    init_utils();
+    selectFromMenu3 = async (menuOptions, message) => {
+      const keys = Object.keys(menuOptions);
+      const choices = keys.filter((key) => !menuOptions[key].disabled).map((key) => ({
+        name: menuOptions[key].display,
+        value: menuOptions[key].value,
+        description: menuOptions[key].description
+      }));
+      const answer = await select3({ message: chalk7.whiteBright(message), choices });
+      return answer;
+    };
+    menuTargetDirectory = async (cart) => {
+      if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.HarnessOnly.value) return;
+      const raw = await input3({
+        message: chalk7.whiteBright("Target directory (existing project):"),
+        default: ".",
+        validate: async (value) => {
+          const resolved = path5.resolve(process.cwd(), value.trim());
+          if (!await dirExists(resolved)) {
+            return `Directory "${value.trim()}" does not exist`;
+          }
+          return true;
+        },
+        transformer: (value) => value.trim()
+      });
+      cart.targetDirectory = path5.resolve(process.cwd(), raw.trim());
+    };
+    menuProjectName3 = async (cart) => {
+      if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.HarnessOnly.value) return;
+      const defaultName = path5.basename(cart.targetDirectory);
+      cart.projectName = await input3({
+        message: chalk7.whiteBright("Project name:"),
+        default: defaultName,
+        validate: (value) => {
+          if (!value.trim()) return "Project name cannot be empty";
+          if (!/^[a-zA-Z0-9_-]+$/.test(value.trim()))
+            return "Only letters, numbers, hyphens, and underscores allowed";
+          return true;
+        },
+        transformer: (value) => value.trim()
+      });
+    };
+    menuProjectType = async (cart) => {
+      if (!cart || cart.type !== MENU_OPTIONS_LEVEL_1.HarnessOnly.value) return;
+      cart.projectType = await selectFromMenu3(
+        HARNESS_MENU_PROJECT_TYPE,
+        "Project type:"
+      );
+    };
+    flowHarnessOnly = async () => {
+      const cart = { type: MENU_OPTIONS_LEVEL_1.HarnessOnly.value };
+      await menuTargetDirectory(cart);
+      await menuProjectName3(cart);
+      await menuProjectType(cart);
+      const { scaffoldHarnessOnly: scaffoldHarnessOnly2 } = await Promise.resolve().then(() => (init_harness_only(), harness_only_exports));
+      await scaffoldHarnessOnly2(cart);
+    };
+  }
+});
+
 // src/commands/update.ts
 import { exec } from "child_process";
 import { promisify } from "util";
@@ -3172,8 +4447,8 @@ var runUpdate = async (currentVersion) => {
 
 // src/options/index.ts
 init_constants();
-import { select as select3, Separator as Separator3 } from "@inquirer/prompts";
-import chalk6 from "chalk";
+import { select as select4, Separator as Separator3 } from "@inquirer/prompts";
+import chalk8 from "chalk";
 var menu = async () => {
   const keys = Object.keys(MENU_OPTIONS_LEVEL_1);
   const enabledKeys = keys.filter((key) => !MENU_OPTIONS_LEVEL_1[key].disabled);
@@ -3190,8 +4465,8 @@ var menu = async () => {
       disabled: MENU_OPTIONS_LEVEL_1.Nuxt.description
     }
   ];
-  const answer = await select3({
-    message: chalk6.whiteBright("How can I help you \u{1F468}\u200D\u{1F373}"),
+  const answer = await select4({
+    message: chalk8.whiteBright("How can I help you \u{1F468}\u200D\u{1F373}"),
     choices
   });
   const cart = { type: answer };
@@ -3201,6 +4476,9 @@ var menu = async () => {
   } else if (answer === MENU_OPTIONS_LEVEL_1.ChromeExtension.value) {
     const { flowChromeExtension: flowChromeExtension2 } = await Promise.resolve().then(() => (init_chrome_extension2(), chrome_extension_exports2));
     await flowChromeExtension2(cart);
+  } else if (answer === MENU_OPTIONS_LEVEL_1.HarnessOnly.value) {
+    const { flowHarnessOnly: flowHarnessOnly2 } = await Promise.resolve().then(() => (init_harness_only2(), harness_only_exports2));
+    await flowHarnessOnly2();
   }
   return cart;
 };
@@ -3218,13 +4496,13 @@ var typeWriter = async (text, colorFunc, speed = 50) => {
 };
 
 // src/utils/check-node-version.ts
-import chalk7 from "chalk";
+import chalk9 from "chalk";
 var MIN_NODE_MAJOR = 20;
 var checkNodeVersion = () => {
   const major = parseInt(process.version.slice(1).split(".")[0], 10);
   if (major < MIN_NODE_MAJOR) {
     console.error(
-      chalk7.red(
+      chalk9.red(
         `\u2716 beaver requires Node.js v${MIN_NODE_MAJOR} or higher.
   You are running ${process.version}.
   Please upgrade Node.js: https://nodejs.org`
@@ -3242,7 +4520,7 @@ var getUserName = () => {
 };
 
 // src/index.ts
-import chalk8 from "chalk";
+import chalk10 from "chalk";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -3275,6 +4553,7 @@ Commands:
 Options:
   -v, --version     Show version
   -h, --help        Show help
+      --ai          Apply AI harness to an existing project
     `);
     process.exit(0);
   }
@@ -3282,13 +4561,25 @@ Options:
     await runUpdate(getVersion());
     process.exit(0);
   }
-  await typeWriter(`Hi! ${getUserName()} \u{1F646}`, chalk8.whiteBright, 50);
+  if (args.includes("--ai")) {
+    try {
+      const { flowHarnessOnly: flowHarnessOnly2 } = await Promise.resolve().then(() => (init_harness_only2(), harness_only_exports2));
+      await flowHarnessOnly2();
+    } catch (err) {
+      if (err instanceof Error) {
+        console.error(chalk10.red(err.message));
+      }
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+  await typeWriter(`Hi! ${getUserName()} \u{1F646}`, chalk10.whiteBright, 50);
   await sleep(500);
   try {
     await menu();
   } catch (err) {
     if (err instanceof Error) {
-      console.error(chalk8.red(err.message));
+      console.error(chalk10.red(err.message));
     }
     process.exit(1);
   }