create-harness-vibe-coding 0.1.10 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@
 <h1 align="center">create-harness-vibe-coding</h1>
 <p align="center">
   <b>0-1 product harness scaffold for AI-assisted engineering.</b><br>
-  <sub>Idea -> Research -> PRD -> Architecture -> docs/harness/PLAN.md -> Build -> Verify -> Feedback.</sub>
+  <sub>Idea -> Research -> PRD -> Architecture -> Harness/PLAN.md -> Build -> Verify -> Feedback.</sub>
 </p>
 
 ---
@@ -21,8 +21,10 @@ npx create-harness-vibe-coding@latest my-project
 
 | What You Get | Purpose |
 |-------------|---------|
-| `CLAUDE.md` + `docs/README.md` | Short entry and dynamic doc router |
-| `docs/harness/PLAN.md` | Active execution state for multi-step work |
+| `CLAUDE.md` + `Harness/README.md` | Thin root entry and dynamic doc router |
+| `Harness/PLAN.md` | Active execution state, heartbeat, and handoffs |
+| `Harness/WF.md` + `/wf` | Long-task workflow: explore, second-plan, build, review, verify, recover |
+| `Harness/subagents.md` + `subagent-orchestrator` | Controller-led multi-agent orchestration with source-attributed methods |
 | Research + PRD templates | Clarify idea, scope, non-goals, acceptance criteria |
 | Research protocol | Route research agents, source search, and fallback tools |
 | Built-in common agents | Research, planning, architecture, testing, implementation, debugging, review, verification |
@@ -30,9 +32,10 @@ npx create-harness-vibe-coding@latest my-project
 | Dispatch protocol | Lightweight parallel-agent coordination without a scheduler |
 | Extension contract | Keep stack-specific agents and skills compatible |
 | Context-loading protocol | Inject only the right docs into each subagent |
+| README optimizer skill | Optional README preservation, tables, and approved architecture diagrams |
 | Skill-style loaders | `.claude/skills/*` route lifecycle, context, and build loops |
 | Harness validator | Checks required files and unresolved project placeholders |
-| `.claude/` skeleton | Built-in common agents plus room for stack-specific assets |
+| `.claude/` skeleton | Root runtime integration for Claude Code agents, skills, commands, and rules |
 
 ---
 
@@ -48,6 +51,7 @@ Most 0-1 AI coding projects fail before code quality matters:
 | Process drift is invisible | validator checks core harness readiness |
 | Architecture drifts silently | ports, data-flow, and state docs mark boundary changes |
 | Tests come after implementation | workflow requires failing test or manual check first |
+| Long tasks stall after failures | `/wf` adds heartbeat, recovery, debugger, review, and verifier loops |
 
 ---
 
@@ -55,10 +59,10 @@ Most 0-1 AI coding projects fail before code quality matters:
 
 ```text
 npx scaffold
--> Claude reads SETUP.md
--> docs router selects only needed harness docs
+-> Claude reads Harness/SETUP.md
+-> Harness router selects only needed harness docs
 -> PRD/research/architecture/PLAN are filled
--> first vertical slice is built, tested, reviewed, and fed back
+-> first vertical slice is built, tested, reviewed, verified, and fed back
 -> validator catches missing project facts before release
 ```
 
@@ -74,41 +78,52 @@ The scaffold does not prebuild business code. It gives agents a compact process
 my-project/
 ├── CLAUDE.md              ← Short startup rules + context discipline
 ├── AGENTS.md              ← Coding agent entry
-├── MEMORY.md              ← Cross-session resource index
-├── SETUP.md               ← Temporary init guide (delete after setup)
+├── README.md              ← Project build/test/git/run notes
 ├── .gitignore
-├── docs/
+├── Harness/
 │   ├── README.md          ← Dynamic doc router
-│   ├── harness/
-│   │   ├── PLAN.md               ← Active execution plan and handoffs
-│   │   ├── lifecycle.md          ← 0-1 product flow
-│   │   ├── context-loading.md    ← Subagent context packs
-│   │   ├── dispatch.md           ← Lightweight parallel-agent protocol
-│   │   ├── extension.md          ← Stack-specific agent/skill contract
-│   │   ├── architecture.md       ← Layer rules, components, ADRs
-│   │   ├── agent-workflow.md     ← TDD loop, subagent roles, write sets
-│   │   ├── data-flow.md          ← Event lifecycle: normal + failure paths
-│   │   └── state-machines.md     ← State enums, transition tables, guards
+│   ├── SETUP.md           ← Temporary init guide (delete after setup)
+│   ├── MEMORY.md          ← Cross-session resource index
+│   ├── PLAN.md            ← Active execution plan, handoffs, heartbeat
+│   ├── WF.md              ← Long-task workflow and recovery loop
+│   ├── lifecycle.md       ← 0-1 product flow
+│   ├── subagents.md       ← Controller-led subagent orchestration
+│   ├── context-loading.md ← Subagent context packs
+│   ├── dispatch.md        ← Lightweight parallel-agent protocol
+│   ├── extension.md       ← Stack-specific agent/skill contract
+│   ├── architecture.md    ← Layer rules, components, ADRs
+│   ├── agent-workflow.md  ← TDD loop, subagent roles, write sets
+│   ├── data-flow.md       ← Event lifecycle: normal + failure paths
+│   ├── state-machines.md  ← State enums, transition tables, guards
 │   ├── domain/
-│   │   └── ports.md              ← Port contracts: pre/postconditions, errors
+│   │   └── ports.md       ← Port contracts: pre/postconditions, errors
 │   ├── features/
-│   │   └── _template.md          ← Kiro-lite feature doc template
-│   └── research/
-│       ├── README.md             ← Research-agent protocol and tool fallbacks
-│       ├── PRD.md                ← MVP scope & acceptance template
-│       └── research-results.md   ← Tech research results and decisions
-├── scripts/
-│   └── validate-harness.mjs      ← Lightweight harness readiness check
+│   │   └── _template.md   ← Kiro-lite feature doc template
+│   ├── research/
+│   │   ├── README.md
+│   │   ├── PRD.md
+│   │   └── research-results.md
+│   ├── memory/
+│   │   ├── tool-usage-reflections.md
+│   │   ├── user-corrections-preferences.md
+│   │   └── agent-lessons-patterns.md
+│   ├── workflows/         ← Optional workflow docs
+│   └── scripts/
+│       └── validate-harness.mjs
 ├── .claude/
 │   ├── settings.json     ← Base permissions
 │   ├── agents/           ← Built-in common agents + stack-specific agents later
 │   ├── skills/           ← Harness loaders + stack-specific skills
+│   ├── commands/
+│   │   └── wf.md          ← Slash-command bridge into wf-mode
 │   ├── hooks/            ← Configure automation after stack choice
 │   └── rules/ecc/
 │       └── common.md     ← Universal coding rules
 └── tests/                ← Your test suite goes here
 ```
 
+`Harness/` is the default home for harness-owned docs, state, memory, workflows, and validation. The root `.claude/` directory remains at the project root because Claude Code discovers agents, skills, commands, settings, hooks, and rules there.
+
 ---
 
 ## Ecosystem Compatibility
@@ -134,6 +149,35 @@ npx create-harness-vibe-coding@latest
 
 The scaffold is designed to be added to an existing repository without silently replacing project files.
 
+Chinese README: [README-CN.md](README-CN.md)
+
+One-sentence agent prompt: `Follow the README at https://github.com/zingspark/create-harness-vibe-coding to configure this project with create-harness-vibe-coding; before editing, ask the Agent-link install intake questions; for a new project run the 0-1 bootstrap, and for an existing project or legacy architecture run a dry-run first, preserve existing files, merge only missing Harness guidance, then follow Harness/SETUP.md.`
+
+There are two installation paths:
+
+- **npx install**: deterministic scaffold writes with explicit conflict policy. Use this when you want predictable files and a clear dry-run plan.
+- **Agent-link install**: paste the one-sentence prompt above into Claude Code, Codex, Cursor, Gemini CLI, or another coding agent. This path is more flexible: the agent should read this README, inspect the existing project, run or emulate a dry-run, and propose a minimal migration plan before editing.
+
+Agent-link install intake, asked before editing:
+
+Ask only questions that affect writes, architecture, security, or workflow. Ask at most three blocking questions up front, record safe defaults for the rest, and ask follow-ups only when that choice becomes active.
+
+| Topic | Ask When | Default If Unanswered |
+| --- | --- | --- |
+| Root agent entry | `CLAUDE.md`, `AGENTS.md`, `.claude/`, or other agent entry files already exist | Preserve files; ask before merging the Harness entry contract |
+| Harness location | `docs/` is already used for GitHub Pages, product docs, or generated docs | Use root `Harness/`; do not write harness docs into `docs/` |
+| README ownership | root `README.md` is a public product page, package docs, or heavily customized | Preserve existing README and propose a minimal Development section |
+| README optimization | existing README is stale, sparse, missing command tables, or the user asks for diagrams/polished docs | Offer `readme-optimizer`; default to append-only Development notes until the user approves a structure pass or full rewrite |
+| Extensions | ECC, Superpowers, custom rules, or stack-specific skills may be useful | Recommend first; install only after user approval |
+| Skills | stack is known and optional skills could improve testing, frontend, backend, review, or browser evidence | Install 1-2 relevant skills only after user approval |
+| CI/CD | CI config exists or the project lacks a test/build gate | Document existing commands first; add CI/CD only after user approval |
+| Verification depth | browser-visible, API, database, auth, payment, or deployment behavior is affected | Require real command evidence; require browser/API evidence when relevant |
+| Memory/privacy | repo contains sensitive domain data, customer data, secrets, or private workflows | Enable memory index only; never record secrets or private data |
+| Branch/worktree | project has uncommitted changes, risky migration, or parallel implementation lanes | Preserve current worktree; propose branch/worktree before broad edits |
+| Package manager/stack | multiple package managers, monorepo apps, or unclear stack boundaries exist | Ask which workspace/app is in scope before writing |
+
+If `CLAUDE.md` already exists, the agent must tell the user it is the root agent entry contract and ask for confirmation before refactoring, merging, backing up, or replacing it. The correct outcome is a user-approved merge that preserves project-specific rules while adding the Harness startup, memory, router, workflow, and subagent orchestration contract.
+
 ```bash
 # Preview the write plan first. No files or directories are created.
 npx create-harness-vibe-coding@latest my-app . -y --dry-run
@@ -142,12 +186,12 @@ npx create-harness-vibe-coding@latest my-app . -y --dry-run
 npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
 ```
 
-By default, conflicts fail before writing. This protects existing `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.gitignore`, docs, and scripts from accidental replacement.
+By default, conflicts fail before writing. This protects existing `CLAUDE.md`, `AGENTS.md`, `README.md`, `.claude/`, `.gitignore`, project docs, and scripts from accidental replacement.
 
 | Conflict mode | Meaning | Risk |
 |---------------|---------|------|
 | `fail` | Default. Stop if a target file already exists. | Safest for existing projects; requires a follow-up decision. |
-| `skip` | Keep existing files and create only missing files. | Existing docs may need manual links to new harness docs or workflows. |
+| `skip` | Keep existing files and create only missing files. | Existing root entries may need manual links to new `Harness/` docs or workflows. |
 | `backup` | Rename the existing file to `<name>.harness-backup`, then write the scaffold file. | Review backups before deleting; repeated runs may need cleanup. |
 | `overwrite` | Replace existing files with scaffold versions. | Destructive. Use only after reviewing `--dry-run` output or with explicit approval. |
 
@@ -156,9 +200,15 @@ Recommended bootstrap for agents:
 ```bash
 node bin/create-harness-vibe-coding.js my-app . -y --dry-run
 node bin/create-harness-vibe-coding.js my-app . -y --on-conflict skip
-node scripts/validate-harness.mjs
+node Harness/scripts/validate-harness.mjs
 ```
 
+After files are installed, agents must follow `Harness/SETUP.md` before normal project work. `CLAUDE.md` only points to the required Harness routers; setup details belong in `Harness/SETUP.md`.
+
+If `AGENTS.md` already exists, the agent must ask for user consent before merging or replacing it. `AGENTS.md` is part of the root agent entry contract, just like `CLAUDE.md`.
+
+Development commands, build scripts, git conventions, and release process belong in root `README.md`. Code architecture belongs in `Harness/architecture.md` or feature docs, not in `CLAUDE.md`.
+
 ### Agent / CI/CD
 
 Agents and automation can skip all prompts with `-y`:
@@ -243,7 +293,7 @@ npm test
 node bin/create-harness-vibe-coding.js --list-options
 
 # After generating a project, validate the harness from that project root
-node scripts/validate-harness.mjs
+node Harness/scripts/validate-harness.mjs
 ```
 
 The harness validator checks scaffold consistency. It is not a full React, Playwright, Chrome DevTools Protocol, or browser matrix test suite.
@@ -251,9 +301,10 @@ The harness validator checks scaffold consistency. It is not a full React, Playw
 ### After scaffolding, tell Claude:
 
 ```
-"Read SETUP.md. Bootstrap this project from idea to first vertical slice."
-"Read SETUP.md. This is a React TypeScript SaaS idea. Clarify PRD first, then plan the first slice."
-"Read SETUP.md. This is a Python data product. Research the stack, define the MVP, then create docs/harness/PLAN.md."
+"Read Harness/SETUP.md. Bootstrap this project from idea to first vertical slice."
+"Read Harness/SETUP.md. This is a React TypeScript SaaS idea. Clarify PRD first, then plan the first slice."
+"Read Harness/SETUP.md. This is a Python data product. Research the stack, define the MVP, then create Harness/PLAN.md."
+"Use /wf for this long migration. Explore first, make a second plan, then implement, review, verify, and recover with heartbeat updates."
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {

package/src/generator.js

@@ -12,6 +12,20 @@ const EMPTY_DIRS = [
   'tests',
 ];
 
+function harnessDest(file) {
+  if (file === 'SETUP.md') return 'Harness/SETUP.md';
+  if (file === 'MEMORY.md') return 'Harness/MEMORY.md';
+  if (file === 'scripts/validate-harness.mjs') return 'Harness/scripts/validate-harness.mjs';
+  if (file.startsWith('memory/')) return `Harness/${file}`;
+  if (file === 'docs/README.md') return 'Harness/README.md';
+  if (file.startsWith('docs/harness/')) return file.replace(/^docs\/harness\//, 'Harness/');
+  if (file.startsWith('docs/research/')) return file.replace(/^docs\/research\//, 'Harness/research/');
+  if (file.startsWith('docs/domain/')) return file.replace(/^docs\/domain\//, 'Harness/domain/');
+  if (file.startsWith('docs/features/')) return file.replace(/^docs\/features\//, 'Harness/features/');
+  if (file.startsWith('docs/workflows/')) return file.replace(/^docs\/workflows\//, 'Harness/workflows/');
+  return file;
+}
+
 /**
  * Replace {{vars}} in file contents.
  */
@@ -109,7 +123,7 @@ function createCoreFileSpecs() {
     .map(file => normalizePath(file))
     .sort()
     .map(file => ({
-      dest: file,
+      dest: harnessDest(file),
       src: path.join(TEMPLATES_DIR, ...file.split('/')),
       type: 'common',
     }));
@@ -126,7 +140,7 @@ function createOptionalFileSpecs(selectedSkills) {
       const absRoot = path.join(OPTIONAL_DIR, ...fileRoot.split('/'));
       for (const file of walkFiles(absRoot).map(normalizePath).sort()) {
         specs.push({
-          dest: file,
+          dest: harnessDest(file),
           src: path.join(absRoot, ...file.split('/')),
           type: 'optional',
           skillId: skill.id,
@@ -138,6 +152,21 @@ function createOptionalFileSpecs(selectedSkills) {
   return specs;
 }
 
+function duplicateDests(fileSpecs) {
+  const seen = new Set();
+  const duplicates = new Set();
+
+  for (const spec of fileSpecs) {
+    if (seen.has(spec.dest)) {
+      duplicates.add(spec.dest);
+    } else {
+      seen.add(spec.dest);
+    }
+  }
+
+  return [...duplicates].sort();
+}
+
 function createPlan(resolvedDir, fileSpecs) {
   const plan = {
     create: [],
@@ -166,7 +195,11 @@ function createPlan(resolvedDir, fileSpecs) {
     const absDir = dir === '.'
       ? resolvedDir
       : path.join(resolvedDir, ...dir.split('/'));
-    if (!fs.existsSync(absDir)) {
+    if (fs.existsSync(absDir)) {
+      if (!fs.statSync(absDir).isDirectory()) {
+        plan.conflict.push(dir === '.' ? './' : `${dir}/`);
+      }
+    } else {
       plan.mkdir.push(dir === '.' ? './' : `${dir}/`);
     }
   }
@@ -232,9 +265,9 @@ function nextBackupPath(destPath) {
 function registerOptionalContent(file, content, selectedSkills) {
   if (!selectedSkills.length) return content;
 
-  if (file === 'MEMORY.md') {
+  if (file === 'Harness/MEMORY.md') {
     const lines = selectedSkills.map(skill => (
-      `- [${skill.id}](.claude/skills/${skill.id}/SKILL.md) - ${skill.description} Workflow: docs/workflows/${skill.id}.md`
+      `- [${skill.id}](../.claude/skills/${skill.id}/SKILL.md) - ${skill.description} Workflow: [workflows/${skill.id}.md](workflows/${skill.id}.md)`
     ));
     return content.replace(
       'Stack-specific skills can be added after the product shape is known.',
@@ -242,7 +275,7 @@ function registerOptionalContent(file, content, selectedSkills) {
     );
   }
 
-  if (file === 'docs/README.md') {
+  if (file === 'Harness/README.md') {
     const lines = selectedSkills.map(skill => (
       `- [${skill.title}](workflows/${skill.id}.md) - ${skill.description}`
     ));
@@ -253,14 +286,25 @@ function registerOptionalContent(file, content, selectedSkills) {
 }
 
 function registrationWarnings(plan, selectedSkills) {
-  if (!selectedSkills.length) return [];
-
   const warnings = [];
-  if (plan.skip.includes('MEMORY.md')) {
-    warnings.push('MEMORY.md was skipped; manually register selected optional skills under #Skills.');
+
+  if (selectedSkills.length) {
+    if (plan.skip.includes('Harness/MEMORY.md')) {
+      warnings.push('Harness/MEMORY.md was skipped; manually register selected optional skills under #Skills.');
+    }
+    if (plan.skip.includes('Harness/README.md')) {
+      warnings.push('Harness/README.md was skipped; manually register selected optional workflow paths.');
+    }
   }
-  if (plan.skip.includes('docs/README.md')) {
-    warnings.push('docs/README.md was skipped; manually register selected optional workflow paths.');
+
+  if (plan.skip.includes('README.md')) {
+    warnings.push('README.md was skipped; keep project run, build, test, and git conventions there, not in CLAUDE.md.');
+  }
+  if (plan.skip.includes('CLAUDE.md') || plan.conflict.includes('CLAUDE.md')) {
+    warnings.push('CLAUDE.md already exists; ask the user to confirm refactoring or merging it with the Harness root-entry contract before editing.');
+  }
+  if (plan.skip.includes('AGENTS.md')) {
+    warnings.push('AGENTS.md was skipped; ask for user consent before merging or replacing the project agent entry contract.');
   }
 
   return warnings;
@@ -290,6 +334,7 @@ export function generate({
   ];
   const specsByDest = new Map(fileSpecs.map(spec => [spec.dest, spec]));
   const plan = createPlan(resolvedDir, fileSpecs);
+  const duplicateDestinations = duplicateDests(fileSpecs);
 
   if (!VALID_CONFLICT_POLICIES.has(onConflict)) {
     errors.push(`Unknown conflict policy "${onConflict}". Use fail, skip, backup, or overwrite.`);
@@ -315,6 +360,18 @@ export function generate({
     };
   }
 
+  if (duplicateDestinations.length > 0) {
+    errors.push(`Generation stopped because duplicate template destination(s) were found: ${duplicateDestinations.join(', ')}`);
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      summary: createSummary(plan, { noWrites: true }),
+      warnings,
+    };
+  }
+
   addFileActions(plan, fileSpecs, resolvedDir, onConflict);
   warnings.push(...registrationWarnings(plan, optional.selectedSkills));
 
@@ -332,6 +389,9 @@ export function generate({
 
   if (plan.conflict.length > 0) {
     errors.push(`Generation stopped because ${plan.conflict.length} file conflict(s) were found: ${plan.conflict.join(', ')}`);
+    if (plan.conflict.includes('CLAUDE.md')) {
+      errors.push('CLAUDE.md already exists. It is the root agent entry contract; ask the user to confirm refactoring or merging it with the Harness entry contract before editing, backing up, or overwriting.');
+    }
     return {
       success: false,
       created,

package/src/index.js

@@ -100,7 +100,7 @@ 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')}`);
   }
@@ -142,15 +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;
@@ -187,19 +202,14 @@ function printResult(result, targetDir) {
     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}`));
-      }
-    }
+    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('');
 
   } else {
@@ -326,6 +336,15 @@ function printPlan(plan) {
   }
 }
 
+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;

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,11 +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 `docs/harness/PLAN.md`, the current feature doc, `MEMORY.md`, or `memory/*` as appropriate.
+- 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
 
@@ -22,9 +22,10 @@ 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.
@@ -32,9 +33,9 @@ alwaysApply: true
 
 ## 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`.
+- 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