create-harness-vibe-coding 0.1.8 → 0.1.10

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             ║'));
@@ -60,13 +101,26 @@ if (argName || skipPrompts) {
   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/')}`);
+  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
@@ -89,6 +143,7 @@ if (argName || skipPrompts) {
   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(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
@@ -109,13 +164,35 @@ 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);
+
+    if (result.warnings.length > 0) {
+      console.log(pc.yellow('\nWarning(s):'));
+      for (const warning of result.warnings) {
+        console.log(pc.yellow(`  - ${warning}`));
+      }
+    }
 
     console.log(pc.bold('Next steps:'));
     console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
@@ -125,12 +202,6 @@ function printResult(result, targetDir) {
     console.log(pc.dim('  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 +210,127 @@ 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 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/rules/ecc/common.md

@@ -10,6 +10,8 @@ alwaysApply: true
 - 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.
+- 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 `docs/harness/PLAN.md`, the current feature doc, `MEMORY.md`, or `memory/*` as appropriate.
 
 ## Verification
 
@@ -28,6 +30,13 @@ alwaysApply: true
 - 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 `memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times.
+- Record repeated user corrections or durable preferences in `memory/user-corrections-preferences.md` when the user corrects the same assumption/pattern 2+ times.
+- Record reusable review/debug lessons in `memory/agent-lessons-patterns.md`.
+- Keep memory entries concise and never include secrets.
+
 ## Security
 
 - No secrets in source code.

package/templates/common/CLAUDE.md

@@ -86,6 +86,8 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 ## 6. Memory & Self-Learning
 
-- **User memory**: triggers "remember", "never", "next time", "always", "I prefer" — persist newest-first under `MEMORY.md#User Mem`. Don't record ordinary chat. Ambiguous? Ask.
-- **Tool memory**: auto-record under `MEMORY.md#Tool Usage Standards` when a tool/pattern fails 3+ times or a better alternative is found. Update old entries, don't duplicate. Never record secrets.
-- Format details live in `MEMORY.md`, not here.
+- `MEMORY.md` is the index. Detailed durable memory lives in `memory/`.
+- **Tool reflection trigger**: record a lightweight reflection when the same tool/use pattern fails 3+ times, or when a better command pattern/environment fix is found. Write it newest-first in `memory/tool-usage-reflections.md`.
+- **User correction trigger**: record a lightweight preference/correction when the user asks to remember it, or when the user corrects the same assumption/pattern 2+ times. Write it newest-first in `memory/user-corrections-preferences.md`.
+- **Agent lesson trigger**: record reusable lessons from review/debug loops in `memory/agent-lessons-patterns.md` when they would prevent recurrence.
+- Update old entries instead of duplicating them. Never record secrets, credentials, tokens, or private data. If a memory is ambiguous, ask before writing.

package/templates/common/MEMORY.md

@@ -1,6 +1,7 @@
-# MEMORY.md — {{projectName}} Project Resource Index
+# MEMORY.md - {{projectName}} Project Resource Index
 
 > The project fact source is reached via `CLAUDE.md -> docs/README.md`. This file persists cross-session context: resource index, user preferences, tool usage standards.
+> Detailed memory lives in `memory/`. Keep entries short, newest first, and free of secrets.
 
 ## Agents (Sub-agents)
 
@@ -46,13 +47,16 @@ Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
 - [Agent workflow](docs/harness/agent-workflow.md)
 - [Harness validator](scripts/validate-harness.mjs)
 
-## User Mem
+## Memory Folder
 
-> User preferences, habits, corrections. Written by CLAUDE.md §5.1 triggers, newest first.
-> No entries yet — awaiting first "remember…" instruction.
+- [Tool usage/reflections](memory/tool-usage-reflections.md) - repeated tool failures, better command patterns, environment-specific fixes.
+- [User corrections/preferences](memory/user-corrections-preferences.md) - repeated user corrections, durable preferences, common-sense course corrections.
+- [Agent lessons/patterns](memory/agent-lessons-patterns.md) - reusable lessons from review, debugging, validation, and handoff loops.
 
-## Tool Usage Standards
+Write to the memory folder when the guidance should survive chat context loss:
 
-> Claude Code self-learning: high-frequency tool/MCP/skill pitfalls, alternatives, common error fix templates.
-> Written by CLAUDE.md §5.2 triggers.
-> No entries yet — awaiting first auto-discovery.
+- Use `memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times, a better command pattern is found, or an environment-specific fix should be reused.
+- Use `memory/user-corrections-preferences.md` when the user explicitly asks to remember a preference, or the user corrects the same assumption/pattern 2+ times.
+- Use `memory/agent-lessons-patterns.md` when a review/debug loop yields a reusable lesson or regression guard.
+- Use `MEMORY.md` for the resource index and routing pointers, not long-form lessons.
+- Never record secrets, credentials, tokens, or private data. If a memory is ambiguous, ask before writing.

package/templates/common/SETUP.md

@@ -10,6 +10,7 @@ This scaffold is a 0-1 product harness:
 - dynamic docs router
 - PRD, research protocol, architecture, ports, data-flow, state templates
 - active `docs/harness/PLAN.md`
+- `MEMORY.md` plus a `memory/` folder for durable self-learning, user corrections, and tool reflections
 - built-in common agents
 - subagent context-loading protocol
 - skill-style dynamic loaders in `.claude/skills/`
@@ -32,7 +33,7 @@ First clarify the idea, then create PRD, research, architecture, docs/harness/PL
 
 Claude must follow this order:
 
-1. Read `CLAUDE.md`, `MEMORY.md`, `docs/README.md`, and `docs/harness/lifecycle.md`.
+1. Read `CLAUDE.md`, `MEMORY.md`, `docs/README.md`, and `docs/harness/lifecycle.md`. Load `memory/*` only when the router or memory trigger applies.
 2. Ask up to 3 blocking product questions. If not blocked, record assumptions in `docs/harness/PLAN.md`.
 3. Fill `docs/research/PRD.md` with MVP, non-goals, and acceptance criteria.
 4. Read `docs/research/README.md`, then fill `docs/research/research-results.md` with adopted/rejected research choices.
@@ -42,7 +43,86 @@ Claude must follow this order:
 8. Fill `docs/harness/data-flow.md` or `docs/harness/state-machines.md` only when the slice changes runtime flow, failure behavior, or state.
 9. Implement only after a failing test or manual verification step is defined.
 10. Run `node scripts/validate-harness.mjs --strict`.
-11. Record final verification and next feedback step in `docs/harness/PLAN.md`.
+11. Record final verification and next feedback step in `docs/harness/PLAN.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `memory/` file.
+
+## Existing Project Bootstrap Sequence
+
+When adding this harness to a project that already has source code, docs, CI, or tool configuration, treat the existing project as the source of truth before filling harness docs.
+
+1. Scan existing project facts first: `README.md`, package files (`package.json`, `pyproject.toml`, `go.mod`, etc.), test commands, app entry points, CI files, existing docs, and current run/build scripts.
+2. Record discovered facts and open questions in `docs/harness/PLAN.md` before changing harness docs.
+3. Fill `docs/research/PRD.md`, `docs/research/research-results.md`, `docs/harness/architecture.md`, and `docs/domain/ports.md` from observed project facts plus explicit user input.
+4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.gitignore`, settings, hooks, package files, CI, docs routers, or workflow docs unless the user explicitly approves that exact overwrite.
+5. When a harness file conflicts with an existing file, preserve the existing file and register any missing harness guidance manually using `docs/harness/extension.md`.
+6. Run `node scripts/validate-harness.mjs` after registration, then run `node scripts/validate-harness.mjs --strict` only after project-fact placeholders have been resolved or intentionally recorded as open.
+
+### Agent Conflict Resolution Protocol
+
+When `--on-conflict skip` leaves existing files untouched, the agent resolves each conflict with user supervision.
+
+**Workflow:**
+
+1. Run the harness tool in planning mode to get the conflict list:
+   ```
+   npx create-harness-vibe-coding@latest . . -y --dry-run --json
+   ```
+   Parse the JSON output. Files in `plan.skip[]` need attention. Files in `plan.create[]` are handled automatically.
+
+2. For each skipped file, locate the harness template counterpart:
+   - From npm: `node_modules/create-harness-vibe-coding/templates/common/<path>`
+   - From GitHub: `https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/<path>`
+
+3. For each skipped file:
+   - Read the existing project file.
+   - Read the harness template counterpart.
+   - Compare sections and headings. Identify structural sections, registration entries, and required text patterns that exist in the template but are missing from the existing file.
+   - Present each gap to the user as a choice:
+     - **[Merge]** — Edit the existing file to add only the missing sections. Preserve all existing content, ordering, and formatting.
+     - **[Overwrite]** — Replace with the template version. Optionally backup the original first (`--on-conflict backup`).
+     - **[Keep]** — Leave the existing file as-is. Skip this file.
+
+4. For Merge: use Edit (not Write) to add missing content. Only insert sections, headings, and text that are structurally required. Do not reorder or modify existing content. Do not remove custom project-specific registrations.
+
+5. After all merges, run `node scripts/validate-harness.mjs`. Fix any remaining validation errors, then run `node scripts/validate-harness.mjs --strict` only after project-fact placeholders are resolved.
+
+**File-specific gap checklists:**
+
+The harness validator checks for specific structural invariants. When comparing existing files against templates, verify these are present. Most other template content can vary; only the items below are required.
+
+| File | Required check |
+|------|----------------|
+| `CLAUDE.md` | `## 1. Startup` with `If SETUP.md exists` line; `## 6. Memory & Self-Learning` section; the tool reflection trigger text (`same tool/use pattern fails 3+ times`); the user correction trigger text (`user corrects the same assumption/pattern 2+ times`); `Never bulk-read docs/` in Startup |
+| `MEMORY.md` | All 9 common agents registered under `## Agents`; all 5 harness skills registered under `## Skills`; all 3 `memory/` files registered under `## Memory Folder`; `memory/` folder usage guidance; `Project Resource Index` in title |
+| `.claude/rules/ecc/common.md` | `## Context` section with the durable communication invariant (`project files are the only durable communication channel`); `## Memory` section with three reflection file entries; `## Security` section |
+| `docs/README.md` | `## Keyword Routing` heading; `## Load By Task` table with at minimum the rows: "Adding harness to existing project", "Need implementation plan", "Need durable memory or reflection"; `## Doc Map` with `memory/` entries; the durable communication invariant text; `docs/README.md is the primary router` |
+| `docs/harness/extension.md` | `## Non-Invasive Extension Rules` section with the "Preserve existing" rule; `## Agent Contract` section; `## Registration` section |
+| `docs/harness/dispatch.md` | The durable communication invariant; common agent entries for all 9 agents; `## Handoff Format` heading |
+| `docs/harness/context-loading.md` | The durable communication invariant; `docs/README.md is the primary router`; all 10 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier) |
+| `docs/harness/PLAN.md` | `## Current Goal`, `## Phase`, `## Success Criteria`, `## Loaded Context`, `## Tasks`, `## Parallel Dispatch`, `## Verification` headings |
+| `SETUP.md` | Only meaningful for fresh projects. If the project has its own onboarding docs, skip this file entirely (it is temporary). If kept, ensure the "Existing Project Bootstrap Sequence" is present. |
+| `docs/workflows/browser-e2e.md` (if installed as optional) | `data-testid`, `accessible labels/roles`, and `inputs, buttons, filters, rows, empty/error/loading states` requirement |
+| `docs/workflows/ts-react-frontend.md` (if installed as optional) | Same UI selector contract as above |
+| `docs/features/_template.md` | `## 1.5 UI Automation Hooks` with `data-testid` table |
+
+**Files that do NOT need manual merge (auto-created by harness):**
+
+- `memory/tool-usage-reflections.md`, `memory/user-corrections-preferences.md`, `memory/agent-lessons-patterns.md` — these are new empty files
+- `.claude/agents/*.md` — all 9 common agents
+- `.claude/skills/harness-*/SKILL.md` — all 5 harness skills  
+- `.claude/rules/ecc/common.md` — universal rules (unless the project has custom rules in this file)
+- `.claude/settings.json` — harness settings
+- `docs/harness/lifecycle.md`, `docs/harness/agent-workflow.md`, `docs/harness/architecture.md`, `docs/harness/data-flow.md`, `docs/harness/state-machines.md` — harness runtime docs
+- `docs/research/*.md` — research protocol and templates
+- `docs/domain/ports.md` — port contract template
+- `AGENTS.md` — agent registry
+- `scripts/validate-harness.mjs` and `tests/.gitkeep` — tooling
+
+Optional workflow examples:
+
+```bash
+npx create-harness-vibe-coding@latest my-app ./my-app -y --with browser-e2e,ts-react-frontend
+npx create-harness-vibe-coding@latest my-app ./my-app -y --preset web-app
+```
 
 ### Template Fill Guide
 
@@ -82,6 +162,11 @@ Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeh
 - `## Parallel Dispatch`: only when spawning subagents — fill agent roles, read/write boundaries.
 - `## Verification`: record test results, review findings, docs sync checklist.
 
+**`memory/`** — Durable self-evolution notes:
+- `memory/tool-usage-reflections.md`: repeated tool failures, better command patterns, environment-specific fixes.
+- `memory/user-corrections-preferences.md`: repeated user corrections, durable preferences, common-sense course corrections.
+- `memory/agent-lessons-patterns.md`: reusable lessons from review, debugging, validation, and handoff loops.
+
 **`docs/harness/data-flow.md`** — Runtime event paths (only when first slice has async/multi-step flow):
 - `{{EVENT_1}}`: the first event type with producer, consumers, payload fields, delivery semantics.
 - Happy Path: fill the Mermaid sequence diagram with actual ports and actions.

package/templates/common/docs/README.md

@@ -16,6 +16,8 @@ For the full phase contract, load [harness/lifecycle.md](harness/lifecycle.md).
 
 - This file is a router, not a full spec.
 - If the task does not clearly match a row below, search by keywords before loading more docs.
+- 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](harness/PLAN.md), the current feature doc, `MEMORY.md`, or `memory/*` as appropriate.
 - Core rules live in `CLAUDE.md` and `.claude/rules/ecc/common.md`.
 - Phase rules live in [harness/lifecycle.md](harness/lifecycle.md).
 - Build, review, test, and subagent rules live in [harness/agent-workflow.md](harness/agent-workflow.md).
@@ -50,9 +52,12 @@ Load the matching row only. Add adjacent docs only when the loaded doc directly
 | Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
 | Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md) | one-page PRD with verifiable acceptance criteria |
 | Need architecture or boundaries | architecture, boundary, layer, domain, port, adapter, dependency | [harness/architecture.md](harness/architecture.md), [domain/ports.md](domain/ports.md) | layer map, ports, constraints |
+| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [harness/extension.md](harness/extension.md), [harness/PLAN.md](harness/PLAN.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
 | Need implementation plan | plan, task, write set, verify, milestone, progress | [harness/PLAN.md](harness/PLAN.md), [harness/agent-workflow.md](harness/agent-workflow.md) | tasks, write set, verification commands |
 | Need parallel agents | parallel, dispatch, handoff, write set, dependency, status | [harness/dispatch.md](harness/dispatch.md), [harness/context-loading.md](harness/context-loading.md), [harness/PLAN.md](harness/PLAN.md) | dispatch table, agent roles, read/write sets |
 | Adding stack-specific agents/skills | extension, agent, skill, rule, hook, stack-specific, compatibility | [harness/extension.md](harness/extension.md), [harness/dispatch.md](harness/dispatch.md) | compatible agents, skills, rules, hooks |
+| Optional workflow installed | workflow, optional, browser-e2e, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `docs/workflows/*.md`, [harness/extension.md](harness/extension.md) | workflow-specific evidence, commands, fallback path |
+| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection | `MEMORY.md`, `memory/tool-usage-reflections.md`, `memory/user-corrections-preferences.md`, `memory/agent-lessons-patterns.md` | concise newest-first memory entry or no-op rationale |
 | Need subagents | subagent, role pack, context, inject, return format | [harness/context-loading.md](harness/context-loading.md) | role-specific context pack |
 | Need feature work | feature, implementation, TDD, test, review, closeout | [features/_template.md](features/_template.md), [harness/agent-workflow.md](harness/agent-workflow.md) | feature doc, tests, implementation loop |
 | Flow or failure behavior changes | data flow, event, failure, retry, recovery, caller behavior | [harness/data-flow.md](harness/data-flow.md) | happy path, failure path, caller behavior |
@@ -95,6 +100,9 @@ docs/features/_template.md      feature work packet
 docs/research/README.md         research protocol
 docs/research/PRD.md            product scope
 docs/research/research-results.md research results
+memory/tool-usage-reflections.md repeated tool failures and better command patterns
+memory/user-corrections-preferences.md durable user corrections and preferences
+memory/agent-lessons-patterns.md reusable review/debug lessons
 scripts/validate-harness.mjs    lightweight harness gate
 .claude/agents/*                built-in common agents
 .claude/skills/*                skill-style dynamic loaders

package/templates/common/docs/features/_template.md

@@ -1,9 +1,12 @@
 # {{FEATURE_NAME}}
 
-> **When to use**: During the PRD phase, every new feature identified in `research/PRD.md` must have its own features document created from this template. One feature = one doc = one implementation unit. Do not code a PRD scope item without a corresponding features doc.
+> **When to use**: Every PRD scope item in `research/PRD.md` Section 2 must have a feature doc — either a new one from this template, or an iteration on an existing one. Do not code a PRD scope item without a corresponding features doc.
+>
+> **New vs iterate**: If the scope item has ≥85% overlap with an existing feature doc, iterate the existing doc (bump `Version`, add a `## Changelog` entry). If overlap is below 85%, create a new file from this template. When in doubt, ask the user.
 
 > **Status**: Draft / In Progress / Blocked / Done
 > **Created**: {{YYYY-MM-DD}}
+> **Version**: 1
 > **Owner**: {{OWNER_OR_AGENT}}
 > **Related Docs**: {{PRD_OR_ARCH_DOC_LINKS}}
 
@@ -31,6 +34,16 @@
 - [ ] {{ACCEPTANCE_CRITERION_2}}
 - [ ] {{ACCEPTANCE_CRITERION_3}}
 
+### 1.5 UI Automation Hooks
+
+For TS/React or browser workflows, define required stable accessible labels/roles and stable test hooks such as `data-testid` before implementation. These selectors must cover critical UI controls and states so CDP, Playwright, and manual verification can target inputs, buttons, filters, rows, empty/error/loading states, dialogs, navigation, and submitted/saved/error feedback without brittle DOM paths.
+
+| Element / State | Accessible Role / Label | `data-testid` | Verification Target |
+| --- | --- | --- | --- |
+| {{INPUT_OR_CONTROL}} | {{ROLE_OR_LABEL}} | {{DATA_TESTID}} | {{PLAYWRIGHT_OR_MANUAL_CHECK}} |
+| {{EMPTY_ERROR_LOADING_OR_ROW_STATE}} | {{ROLE_OR_LABEL}} | {{DATA_TESTID}} | {{PLAYWRIGHT_OR_MANUAL_CHECK}} |
+| Not UI-facing | N/A | N/A | N/A |
+
 ---
 
 ## 2. Design
@@ -142,3 +155,13 @@ Estimate the context budget for this feature. If the main agent would need to re
 
 Remaining risks:
 - {{RISK_OR_NONE}}
+
+---
+
+## 5. Changelog
+
+> Only populate when iterating an existing feature doc (Version ≥ 2).
+
+| Version | Date | What Changed | Reason |
+| --- | --- | --- | --- |
+| 1 | {{YYYY-MM-DD}} | Initial version | — |

package/templates/common/docs/harness/agent-workflow.md

@@ -12,15 +12,11 @@ If context grows, load [context-loading.md](context-loading.md) and split the wo
 
 ## Feature Packet
 
-Create `docs/features/{{FEATURE_SLUG}}.md` from [../features/_template.md](../features/_template.md) when work changes behavior, touches multiple files, crosses layers, or needs more than one short session.
+Every PRD scope item (`research/PRD.md` Section 2) must have its own feature doc at `docs/features/<name>.md` created from `docs/features/_template.md`. One feature = one doc = one implementation unit. Do not code without a feature doc.
 
-The packet must contain:
+Small scope is not an exception — a short feature doc is better than none. If the work is truly too small for a full feature doc (single-file fix, no behavior change), it is not a PRD scope item.
 
-- requirements and non-goals
-- acceptance criteria
-- allowed write set and forbidden scope
-- task list with verification commands
-- test results and residual risks
+**New vs iterate**: if a PRD scope item has ≥85% overlap with an existing feature doc, open the existing doc, bump `Version`, and add a `## Changelog` entry. Only create a new file when the scope is substantially different. When unsure, ask.
 
 ## Standard Build Loop
 

package/templates/common/docs/harness/context-loading.md

@@ -8,6 +8,8 @@ Use when context is growing, subagents are needed, or an agent is unsure which h
 
 If this file and `docs/README.md` disagree, follow `docs/README.md`, record the assumption in `docs/harness/PLAN.md`, and update this file later.
 
+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 `docs/harness/PLAN.md`, the current feature doc, `MEMORY.md`, or `memory/*` as appropriate.
+
 ## Main Context
 
 Always keep:
@@ -30,6 +32,7 @@ Load other docs only by trigger.
 | layer, dependency, module boundary | `docs/harness/architecture.md`, `docs/domain/ports.md` |
 | task split, owner, write set | `docs/harness/PLAN.md`, `docs/harness/agent-workflow.md` |
 | parallel agents, dispatch, worktree decision | `docs/harness/dispatch.md`, `docs/harness/PLAN.md` |
+| memory, repeated tool failure, repeated user correction, reusable lesson | `MEMORY.md`, the relevant `memory/*.md` file |
 | event, retry, failure path | `docs/harness/data-flow.md` |
 | status, transition, resume | `docs/harness/state-machines.md` |
 | subagent spawn | this file plus the role pack below |

package/templates/common/docs/harness/dispatch.md

@@ -7,6 +7,8 @@ Use when work needs parallel reading, independent review, cross-layer analysis,
 ## Principles
 
 - Main agent owns the final decision, integration, and verification.
+- 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 `docs/harness/PLAN.md`, the current feature doc, `MEMORY.md`, or `memory/*` as appropriate.
 - Prefer three or fewer active agents.
 - Read-only agents may run in parallel.
 - Writing agents run serially unless write sets are disjoint.
@@ -76,6 +78,7 @@ PLAN patch:
 ```
 
 Use `Files changed: none` for read-only agents. Use `PLAN patch: none` when no state update is needed.
+If a handoff matters after context loss, write it to `docs/harness/PLAN.md`, the current feature doc, or `memory/*`; do not rely on chat transcript state.
 
 ## Statuses