create-harness-vibe-coding 0.1.9 → 0.2.0

package/src/index.js

@@ -2,14 +2,20 @@
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { askProjectName, askTargetDir } from './prompts.js';
-import { generate } from './generator.js';
+import { generate, getOptionalCatalog } from './generator.js';
 
 // ── CLI flags ──────────────────────────────────────────────
 const raw = process.argv.slice(2);
-const flags = new Set(raw.filter(a => a.startsWith('-')));
-const has = name => flags.has(name) || flags.has(`--${name}`);
-const showHelp = has('h') || has('help');
-const skipPrompts = has('y') || has('yes');
+const parsed = parseArgs(raw);
+const showHelp = parsed.flags.help || parsed.flags.h;
+const skipPrompts = parsed.flags.yes || parsed.flags.y;
+
+if (parsed.errors.length > 0) {
+  for (const err of parsed.errors) {
+    console.error(pc.red(`Error: ${err}`));
+  }
+  process.exit(1);
+}
 
 if (showHelp) {
   console.log('');
@@ -23,25 +29,60 @@ if (showHelp) {
   console.log('    target-dir     Directory to create the project in (default: ./<project-name>)');
   console.log('');
   console.log('  Flags:');
-  console.log('    -y, --yes      Skip all prompts, use defaults or provided args');
-  console.log('    -h, --help     Show this help');
+  console.log('    -y, --yes                    Skip all prompts, use defaults or provided args');
+  console.log('    -h, --help                   Show this help');
+  console.log('    --dry-run                    Print the planned writes without creating files');
+  console.log('    --on-conflict <policy>       fail, skip, backup, or overwrite (default: fail)');
+  console.log('    --with <id,id>               Add optional local workflow skills');
+  console.log('    --without <id,id>            Remove optional workflow skills selected by --preset or --with');
+  console.log('    --preset <name>              Add a built-in optional workflow preset');
+  console.log('    --list-options               Print optional workflow skills and presets');
+  console.log('    --json                       Output machine-readable JSON (use with --dry-run for planning)');
   console.log('');
   console.log('  Examples:');
   console.log('    npx create-harness-vibe-coding@latest');
   console.log('    npx create-harness-vibe-coding@latest -y');
   console.log('    npx create-harness-vibe-coding@latest my-project');
   console.log('    npx create-harness-vibe-coding@latest my-project ./dist/my-project -y');
+  console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --dry-run');
+  console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --on-conflict skip');
+  console.log('    npx create-harness-vibe-coding@latest web ./web -y --with ts-react-frontend,browser-e2e');
+  console.log('    npx create-harness-vibe-coding@latest web ./web -y --preset web-app');
+  console.log('    npx create-harness-vibe-coding@latest api ./api -y --preset fullstack --without github-pr-review');
   console.log('');
   process.exit(0);
 }
 
+if (parsed.flags.listOptions) {
+  printOptions();
+  process.exit(0);
+}
+
 // Positional args (non-flag)
-const positional = raw.filter(a => !a.startsWith('-'));
+const positional = parsed.positionals;
 const argName = positional[0];
 const argDir = positional[1];
+const generationOptions = {
+  dryRun: Boolean(parsed.flags.dryRun),
+  onConflict: parsed.flags.onConflict || 'fail',
+  withOptions: parsed.flags.with || [],
+  withoutOptions: parsed.flags.without || [],
+  preset: parsed.flags.preset,
+  json: Boolean(parsed.flags.json),
+};
 
 const DEFAULT_NAME = 'my-vibe-project';
 
+// --json: machine-readable output, no prompts, no decorative output
+if (generationOptions.json) {
+  const projectName = argName || DEFAULT_NAME;
+  const targetDir = argDir || `./${projectName}`;
+  const result = generate({ projectName, targetDir, ...generationOptions });
+  printJsonResult(result);
+  // printJsonResult exits with 1 on failure; we only reach here on success
+  process.exit(0);
+}
+
 console.log('');
 console.log(pc.magenta('╔══════════════════════════════════════════╗'));
 console.log(pc.magenta('║   create-harness-vibe-coding             ║'));
@@ -59,14 +100,27 @@ if (argName || skipPrompts) {
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, docs/harness/PLAN.md, docs/, scripts/, .claude/, SETUP.md, tests/')}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PLAN.md, Harness/, .claude/, tests/')}`);
+  if (generationOptions.dryRun) {
+    console.log(`  Mode        ${pc.yellow('dry-run')}`);
+  }
+  console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
+  if (generationOptions.withOptions.length > 0) {
+    console.log(`  Optional    ${pc.cyan(generationOptions.withOptions.join(','))}`);
+  }
+  if (generationOptions.withoutOptions.length > 0) {
+    console.log(`  Without     ${pc.cyan(generationOptions.withoutOptions.join(','))}`);
+  }
+  if (generationOptions.preset) {
+    console.log(`  Preset      ${pc.cyan(generationOptions.preset)}`);
+  }
   if (skipPrompts) {
     console.log(`  Mode        ${pc.dim('non-interactive (-y)')}`);
   }
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
-  const result = generate({ projectName, targetDir });
+  const result = generate({ projectName, targetDir, ...generationOptions });
   printResult(result, targetDir);
 } else {
   // Interactive mode
@@ -88,14 +142,30 @@ if (argName || skipPrompts) {
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, docs/harness/PLAN.md, docs/, scripts/, .claude/, SETUP.md, tests/')}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PLAN.md, Harness/, .claude/, tests/')}`);
+  console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
+  const preview = generate({ projectName, targetDir, ...generationOptions, dryRun: true });
+  if (!preview.success) {
+    printResult(preview, targetDir);
+  }
+
+  console.log(pc.yellow('Planned changes: no files have been written yet.'));
+  printSummary(preview.summary);
+  printPlan(preview.plan);
+  printWarnings(preview);
+  console.log('');
+
+  if (generationOptions.dryRun) {
+    process.exit(0);
+  }
+
   let proceed = true;
   try {
     proceed = await p.confirm({
-      message: 'Confirm generation?',
+      message: 'Confirm generation with this plan?',
       initialValue: true,
     });
     if (p.isCancel(proceed)) proceed = false;
@@ -109,28 +179,39 @@ if (argName || skipPrompts) {
   }
 
   console.log('');
-  const result = generate({ projectName, targetDir });
+  const result = generate({ projectName, targetDir, ...generationOptions });
   printResult(result, targetDir);
 }
 
 function printResult(result, targetDir) {
   if (result.success) {
-    console.log(pc.green(`\nProject created: ${result.created.length} files\n`));
+    if (result.dryRun) {
+      console.log(pc.yellow('\nDry run: no files or directories were written.'));
+      printSummary(result.summary);
+      printPlan(result.plan);
+      if (result.warnings.length > 0) {
+        console.log(pc.yellow('\nWarning(s):'));
+        for (const warning of result.warnings) {
+          console.log(pc.yellow(`  - ${warning}`));
+        }
+      }
+      console.log('');
+      return;
+    }
+
+    console.log(pc.green('\nGeneration complete.\n'));
+    printSummary(result.summary);
+
+    printWarnings(result);
 
     console.log(pc.bold('Next steps:'));
     console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
     console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
-    console.log(`  Tell Claude: "${pc.yellow('Read SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
+    console.log(`  Tell Claude: "${pc.yellow('Read Harness/SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
     console.log('');
-    console.log(pc.dim('  SETUP.md is temporary. Delete it after initialization.'));
+    console.log(pc.dim('  Harness/SETUP.md is temporary. Delete it after initialization.'));
     console.log('');
 
-    if (result.errors.length > 0) {
-      console.log(pc.red(`\n${result.errors.length} warning(s):`));
-      for (const err of result.errors) {
-        console.log(pc.red(`  - ${err}`));
-      }
-    }
   } else {
     console.log(pc.red('\nGeneration failed:'));
     for (const err of result.errors) {
@@ -139,3 +220,136 @@ function printResult(result, targetDir) {
     process.exit(1);
   }
 }
+
+function parseArgs(args) {
+  const flags = {
+    with: [],
+    without: [],
+  };
+  const positionals = [];
+  const errors = [];
+
+  function readValue(flagName, index) {
+    const value = args[index + 1];
+    if (!value || value.startsWith('-')) {
+      errors.push(`${flagName} requires a value`);
+      return { value: undefined, nextIndex: index };
+    }
+    return { value, nextIndex: index + 1 };
+  }
+
+  function readEqualsValue(flagName, value) {
+    if (!value || value.startsWith('-')) {
+      errors.push(`${flagName} requires a value`);
+      return undefined;
+    }
+    return value;
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '-h') {
+      flags.h = true;
+    } else if (arg === '--help') {
+      flags.help = true;
+    } else if (arg === '-y') {
+      flags.y = true;
+    } else if (arg === '--yes') {
+      flags.yes = true;
+    } else if (arg === '--dry-run') {
+      flags.dryRun = true;
+    } else if (arg === '--list-options') {
+      flags.listOptions = true;
+    } else if (arg === '--json') {
+      flags.json = true;
+    } else if (arg === '--on-conflict') {
+      const parsedValue = readValue('--on-conflict', i);
+      flags.onConflict = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--on-conflict=')) {
+      flags.onConflict = readEqualsValue('--on-conflict', arg.slice('--on-conflict='.length));
+    } else if (arg === '--with') {
+      const parsedValue = readValue('--with', i);
+      if (parsedValue.value !== undefined) flags.with.push(parsedValue.value);
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--with=')) {
+      const value = readEqualsValue('--with', arg.slice('--with='.length));
+      if (value !== undefined) flags.with.push(value);
+    } else if (arg === '--without') {
+      const parsedValue = readValue('--without', i);
+      if (parsedValue.value !== undefined) flags.without.push(parsedValue.value);
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--without=')) {
+      const value = readEqualsValue('--without', arg.slice('--without='.length));
+      if (value !== undefined) flags.without.push(value);
+    } else if (arg === '--preset') {
+      const parsedValue = readValue('--preset', i);
+      flags.preset = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--preset=')) {
+      flags.preset = readEqualsValue('--preset', arg.slice('--preset='.length));
+    } else if (arg.startsWith('-')) {
+      errors.push(`Unknown flag "${arg}"`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  return { flags, positionals, errors };
+}
+
+function printOptions() {
+  const catalog = getOptionalCatalog();
+
+  console.log('');
+  console.log(pc.bold('Optional workflow skills:'));
+  for (const skill of catalog.skills) {
+    console.log(`  ${pc.cyan(skill.id)} - ${skill.description}`);
+  }
+
+  console.log('');
+  console.log(pc.bold('Presets:'));
+  for (const [name, skills] of Object.entries(catalog.presets)) {
+    console.log(`  ${pc.cyan(name)} - ${skills.join(', ')}`);
+  }
+  console.log('');
+}
+
+function printSummary(summary) {
+  console.log(`  created     ${pc.green(summary.created)}`);
+  console.log(`  skipped     ${pc.yellow(summary.skipped)}`);
+  console.log(`  backed up   ${pc.cyan(summary.backedUp)}`);
+  console.log(`  overwritten ${pc.cyan(summary.overwritten)}`);
+  console.log(`  conflicts   ${summary.conflicts > 0 ? pc.red(summary.conflicts) : pc.dim(summary.conflicts)}`);
+  console.log(`  directories ${pc.dim(summary.mkdir)}`);
+  console.log('');
+}
+
+function printPlan(plan) {
+  for (const [label, files] of Object.entries(plan)) {
+    if (!files.length) continue;
+    console.log(`  ${label}:`);
+    for (const file of files) {
+      console.log(`    - ${file}`);
+    }
+  }
+}
+
+function printWarnings(result) {
+  if (!result.warnings.length) return;
+
+  console.log(pc.yellow('\nWarning(s):'));
+  for (const warning of result.warnings) {
+    console.log(pc.yellow(`  - ${warning}`));
+  }
+}
+
+function printJsonResult(result) {
+  // Remove `created` array from output — it is already in the plan, avoid duplication
+  const { created, ...rest } = result;
+  console.log(JSON.stringify(rest, null, 2));
+  if (!result.success) {
+    process.exit(1);
+  }
+}

package/templates/common/.claude/agents/architect.md

@@ -12,10 +12,10 @@ You are an architecture review agent for this project harness.
 
 Load first:
 
-- `docs/harness/architecture.md`
-- `docs/domain/ports.md`
-- `docs/harness/data-flow.md` when runtime flow may change
-- `docs/harness/state-machines.md` when state may change
+- `Harness/architecture.md`
+- `Harness/domain/ports.md`
+- `Harness/data-flow.md` when runtime flow may change
+- `Harness/state-machines.md` when state may change
 - current PRD or feature doc
 
 Rules:

package/templates/common/.claude/agents/debugger.md

@@ -14,7 +14,7 @@ Load first:
 
 - failing command and error output
 - related files
-- `docs/harness/PLAN.md`
+- `Harness/PLAN.md`
 - current feature doc when present
 
 Inputs you must receive:

package/templates/common/.claude/agents/docs-researcher.md

@@ -12,10 +12,10 @@ You are a documentation verification agent for this project harness.
 
 Load first:
 
-- `docs/research/README.md`
-- `docs/harness/architecture.md` when boundaries may change
-- `docs/domain/ports.md` when APIs cross layers
-- `docs/harness/PLAN.md`
+- `Harness/research/README.md`
+- `Harness/architecture.md` when boundaries may change
+- `Harness/domain/ports.md` when APIs cross layers
+- `Harness/PLAN.md`
 
 Inputs you must receive:
 

package/templates/common/.claude/agents/implementer.md

@@ -12,7 +12,7 @@ You are an implementation agent for this project harness.
 
 Load first:
 
-- current task from `docs/harness/PLAN.md`
+- current task from `Harness/PLAN.md`
 - current feature doc when present
 - failing test or manual check
 - relevant architecture/ports docs if boundaries are touched

package/templates/common/.claude/agents/planner.md

@@ -12,9 +12,9 @@ You are a planning agent for this project harness.
 
 Load first:
 
-- `docs/harness/PLAN.md`
-- `docs/harness/lifecycle.md`
-- `docs/harness/dispatch.md`
+- `Harness/PLAN.md`
+- `Harness/lifecycle.md`
+- `Harness/dispatch.md`
 - current PRD or feature doc if present
 
 Rules:

package/templates/common/.claude/agents/researcher.md

@@ -12,9 +12,9 @@ You are a bounded research agent for this project harness.
 
 Load first:
 
-- `docs/research/README.md`
-- `docs/research/research-results.md`
-- `docs/harness/PLAN.md`
+- `Harness/research/README.md`
+- `Harness/research/research-results.md`
+- `Harness/PLAN.md`
 
 Inputs you must receive:
 
@@ -39,4 +39,4 @@ Return:
 - sources with links, source type, checked date
 - adopted / rejected / watch decisions
 - risks and unknowns
-- patch-ready update for `docs/research/research-results.md`
+- patch-ready update for `Harness/research/research-results.md`

package/templates/common/.claude/agents/reviewer.md

@@ -14,7 +14,7 @@ Load first:
 
 - diff or changed file list
 - current PRD or feature doc
-- `docs/harness/agent-workflow.md`
+- `Harness/agent-workflow.md`
 - architecture/ports/data-flow/state docs when affected
 
 Rules:

package/templates/common/.claude/agents/test-writer.md

@@ -13,8 +13,8 @@ You are a test-first agent for this project harness.
 Load first:
 
 - current PRD or feature doc
-- `docs/harness/PLAN.md`
-- `docs/harness/agent-workflow.md`
+- `Harness/PLAN.md`
+- `Harness/agent-workflow.md`
 
 Inputs you must receive:
 

package/templates/common/.claude/agents/verifier.md

@@ -12,7 +12,7 @@ You are a verification agent for this project harness.
 
 Load first:
 
-- `docs/harness/PLAN.md`
+- `Harness/PLAN.md`
 - current feature doc when present
 - verification commands and acceptance criteria
 

package/templates/common/.claude/commands/wf.md

@@ -0,0 +1,18 @@
+# /wf
+
+Enter `wf-mode`.
+
+Read `Harness/WF.md`, then run the full long-task loop:
+
+```text
+intake
+-> exploration
+-> second plan
+-> test
+-> implement
+-> review
+-> verify
+-> debugger recovery loop when needed
+```
+
+Keep `Harness/PLAN.md#Heartbeat` current.

package/templates/common/.claude/rules/ecc/common.md

@@ -7,9 +7,11 @@ alwaysApply: true
 
 ## Context
 
-- Start with `CLAUDE.md`, `MEMORY.md`, and `docs/README.md`.
-- Do not bulk-read `docs/`. Load by router trigger.
-- Keep `docs/harness/PLAN.md` current when work has multiple steps, files, or agents.
+- Start with `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
+- Do not bulk-read `Harness/`. Load by router trigger.
+- Keep `Harness/PLAN.md` current when work has multiple steps, files, or agents.
+- project files are the only durable communication channel. chat/subagent transcript state is non-authoritative.
+- Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
 ## Verification
 
@@ -20,14 +22,22 @@ alwaysApply: true
 
 ## Subagents
 
-- Use `docs/harness/context-loading.md` before spawning.
-- Use `docs/harness/dispatch.md` before parallel or multi-agent work.
-- Use `docs/harness/extension.md` before adding stack-specific agents, skills, rules, or hooks.
+- Use `Harness/subagents.md` before orchestrating multiple agents.
+- Use `Harness/context-loading.md` before spawning.
+- Use `Harness/dispatch.md` before parallel or multi-agent work.
+- Use `Harness/extension.md` before adding stack-specific agents, skills, rules, or hooks.
 - Every subagent needs role, task, read boundary, write boundary, and return format.
 - Writing agents must run serially unless write sets are disjoint.
 - If the runtime cannot spawn subagents, emulate the same role pack in a separate bounded pass.
 - Main agent owns integration and final verification.
 
+## Memory
+
+- Record a lightweight reflection in `Harness/memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times.
+- Record repeated user corrections or durable preferences in `Harness/memory/user-corrections-preferences.md` when the user corrects the same assumption/pattern 2+ times.
+- Record reusable review/debug lessons in `Harness/memory/agent-lessons-patterns.md`.
+- Keep memory entries concise and never include secrets.
+
 ## Security
 
 - No secrets in source code.

package/templates/common/.claude/skills/harness-build-loop/SKILL.md

@@ -7,9 +7,10 @@ description: Use for implementation, review, debugging, verification, and closin
 
 Load:
 
-- `docs/harness/agent-workflow.md`
-- `docs/harness/dispatch.md` when more than one agent is useful
-- `docs/harness/PLAN.md`
+- `Harness/agent-workflow.md`
+- `Harness/subagents.md` when more than one agent, reviewer, or recovery pass is useful
+- `Harness/dispatch.md` when more than one agent is useful
+- `Harness/PLAN.md`
 - current feature doc if present
 
 Follow:

package/templates/common/.claude/skills/harness-context/SKILL.md

@@ -7,9 +7,10 @@ description: Use before spawning subagents, splitting work, or when context is g
 
 Load:
 
-- `docs/harness/context-loading.md`
-- `docs/harness/dispatch.md` when more than one agent is useful
-- `docs/harness/PLAN.md`
+- `Harness/subagents.md`
+- `Harness/context-loading.md`
+- `Harness/dispatch.md` when more than one agent is useful
+- `Harness/PLAN.md`
 - current feature doc if present
 
 For each subagent or bounded pass, provide:

package/templates/common/.claude/skills/harness-lifecycle/SKILL.md

@@ -7,9 +7,9 @@ description: Use for raw ideas, vague product requests, 0-1 planning, PRD work,
 
 Load:
 
-- `docs/harness/lifecycle.md`
-- `docs/research/PRD.md`
-- `docs/harness/PLAN.md`
+- `Harness/lifecycle.md`
+- `Harness/research/PRD.md`
+- `Harness/PLAN.md`
 
 Output:
 

package/templates/common/.claude/skills/harness-research/SKILL.md

@@ -7,9 +7,9 @@ description: Use for market, product, stack, dependency, API, pricing, legal, se
 
 Load:
 
-- `docs/research/README.md`
-- `docs/research/research-results.md`
-- `docs/harness/PLAN.md`
+- `Harness/research/README.md`
+- `Harness/research/research-results.md`
+- `Harness/PLAN.md`
 
 Define:
 
@@ -26,4 +26,4 @@ Return:
 - sources with links and source type
 - adopted / rejected / watch decisions
 - risks and unknowns
-- patch-ready `docs/research/research-results.md` update
+- patch-ready `Harness/research/research-results.md` update

package/templates/common/.claude/skills/harness-router/SKILL.md

@@ -5,10 +5,12 @@ description: Use at the start of any task, or when unsure which harness document
 
 # Harness Router
 
-1. Read `docs/README.md`.
+1. Read `Harness/README.md`.
 2. Identify the current situation from "Load By Task".
-3. Load only the listed primary doc(s).
-4. If the task grows, update `docs/harness/PLAN.md` and use `harness-context`.
-5. If multiple agents are useful, use `docs/harness/dispatch.md`.
+3. Apply routing priority before loading extra files:
+   - `/wf`, long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work routes to `wf-mode` first.
+   - Bounded subagent-only coordination routes to `subagent-orchestrator`.
+4. Load only the listed primary doc(s). Let `wf-mode` decide when to load subagent docs.
+5. If the task grows, update `Harness/PLAN.md` and use `harness-context`.
 
-Do not bulk-read `docs/`.
+Do not bulk-read `Harness/`.

package/templates/common/.claude/skills/readme-optimizer/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: readme-optimizer
+description: Use when a project README already exists and the user asks to preserve, merge, modernize, optimize, or clarify repository documentation during harness install or documentation work.
+---
+
+# README Optimizer
+
+Improve `README.md` without breaking project-owned public docs.
+
+## Load
+
+- root `README.md`
+- package files and scripts (`package.json`, `pyproject.toml`, `go.mod`, etc.)
+- CI files when present
+- `Harness/PLAN.md`
+- `Harness/architecture.md` only when an architecture summary or diagram is requested
+
+## Mode
+
+Ask the user which mode they approve when the existing README is meaningful:
+
+| Mode | Use when | Allowed edit |
+| --- | --- | --- |
+| Preserve + append | default for existing projects | Add only a compact Development, Test, Build, Git, or Harness section |
+| Structure pass | README is stale, hard to scan, or missing operational docs | Reorganize with headings, tables, command blocks, and links while preserving facts |
+| Full rewrite | user explicitly wants a polished public README | Rewrite after approval; keep claims source-backed |
+
+If unanswered, use Preserve + append.
+
+## Rules
+
+- Preserve existing product, package, API, and public-facing content unless the user approves a rewrite.
+- Do not invent features, benchmarks, roadmap, support policy, badges, install commands, or CI status.
+- Use tables for command matrices, environment variables, endpoints, and deployment notes when facts are known.
+- Use Mermaid or ASCII architecture diagrams only when the structure is observed or approved; label uncertain diagrams as proposed.
+- Keep detailed architecture in `Harness/architecture.md`; README may link to it or show a short overview.
+- Keep agent rules in `CLAUDE.md`/`AGENTS.md`, not README.
+- Record the chosen mode and any skipped README improvements in `Harness/PLAN.md`.
+
+## Output
+
+Before broad edits, return:
+
+1. chosen mode
+2. sections to preserve
+3. sections to add or reorganize
+4. facts still unknown
+5. verification command or manual review step