create-harness-vibe-coding 0.1.10 → 0.2.1

package/README-CN.md

@@ -0,0 +1,94 @@
+# create-harness-vibe-coding 中文说明
+
+0-1 产品 Harness 脚手架，用于 AI 辅助工程：从想法、调研、PRD、架构、计划，到实现、验证和反馈闭环。
+
+English README: [README.md](README.md)
+
+## 一句话交给 Agent
+
+```text
+请按照 https://github.com/zingspark/create-harness-vibe-coding 的 README 为当前项目配置 create-harness-vibe-coding；编辑前先询问 Agent-link 安装前置问题；新项目走 0-1 bootstrap，老项目或老架构升级先 dry-run，保留现有文件，只合并缺失的 Harness 规范，然后遵循 Harness/SETUP.md。
+```
+
+## 两种安装方式
+
+### 1. npx 安装
+
+适合需要确定性写入、明确冲突策略、可重复 dry-run 的场景。
+
+### 2. 直接把链接丢给 agent
+
+适合老项目、老架构升级、已有复杂 `CLAUDE.md` / `AGENTS.md` / `.claude/` 的场景。agent 应该读取这个仓库 README，理解当前项目结构，执行或模拟 dry-run，然后给出最小迁移方案。
+
+如果项目里已经有 `CLAUDE.md`，agent 必须先告诉用户：`CLAUDE.md` 是根 agent 入口合同，不能静默覆盖或乱合并。正确流程是先请求用户确认是否重构/合并 `CLAUDE.md`，再在保留原项目规则的基础上补入 Harness 的 startup、memory、router、workflow、subagents 编排约束。
+
+Agent-link 安装前置问题，编辑前先问：
+
+只询问会影响写入、架构、安全或工作流的选择。开始时最多问 3 个 blocking 问题，其余采用安全默认值并记录到计划里，等真正触发时再继续追问。
+
+| 主题 | 什么时候问 | 没回答时的默认值 |
+| --- | --- | --- |
+| 根 agent 入口 | 已存在 `CLAUDE.md`、`AGENTS.md`、`.claude/` 或其他 agent 入口文件 | 保留现有文件；合并 Harness 入口合同前必须询问用户 |
+| Harness 存放位置 | `docs/` 已经用于 GitHub Pages、产品文档或生成文档 | 默认使用根目录 `Harness/`；不要把 Harness 文档写进 `docs/` |
+| README 归属 | 根 `README.md` 是公开产品页、包文档或已有大量自定义内容 | 保留现有 README，只提议追加最小 Development section |
+| README 优化 | 已有 README 过时、太单薄、缺少命令表格，或用户想要架构图/更生动的文档 | 可推荐 `readme-optimizer`；默认只追加 Development notes，结构化优化或重写必须先得到用户确认 |
+| 扩展能力 | ECC、Superpowers、自定义 rules 或栈相关 skills 可能有用 | 先推荐；只有用户同意后才安装 |
+| Skills | 技术栈已明确，测试、前端、后端、review、浏览器证据可用 optional skills 增强 | 用户同意后只安装 1-2 个最相关 skills |
+| CI/CD | 已有 CI 配置，或项目缺少测试/构建 gate | 先记录现有命令；只有用户同意后才新增或规范 CI/CD |
+| 验证深度 | 涉及浏览器可见行为、API、数据库、鉴权、支付或部署 | 必须有真实命令证据；相关场景必须有浏览器/API 证据 |
+| Memory/隐私 | 仓库包含敏感领域数据、客户数据、密钥或私有流程 | 只启用 memory index；禁止记录 secrets 或私有数据 |
+| Branch/worktree | 存在未提交改动、风险迁移或并行实现 lane | 保护当前工作区；大改前先提议 branch/worktree |
+| 包管理器/技术栈 | 存在多个包管理器、monorepo apps 或技术栈边界不清 | 写文件前先确认当前 workspace/app 范围 |
+
+## 一条命令
+
+```bash
+npx create-harness-vibe-coding@latest my-project
+```
+
+## 现有项目渐进安装
+
+先预览，不写文件：
+
+```bash
+npx create-harness-vibe-coding@latest my-app . -y --dry-run
+```
+
+再保留现有文件，只补缺失的 Harness 文件：
+
+```bash
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
+```
+
+安装后让 agent 先读 `Harness/SETUP.md`，再开始正常工作。
+
+## 核心约束
+
+- `CLAUDE.md` 只做薄入口和路由，不放项目架构、构建脚本、git 规范。
+- 项目开发命令、构建、测试、git、发布流程放根目录 `README.md`。
+- 架构说明放 `Harness/architecture.md` 或当前 feature 文档。
+- Harness 文档、状态、记忆、工作流默认放根目录 `Harness/`。
+- 如果已有 `AGENTS.md`，agent 必须先询问用户是否同意修改。
+- 长任务、多文件、多 subagents、低置信度或重复失败时使用 `/wf`、`wf-mode` 和 `Harness/WF.md`。
+
+## 常用生成物
+
+| 文件 | 用途 |
+| --- | --- |
+| `CLAUDE.md` | Claude Code 根入口，保持短小 |
+| `Harness/README.md` | Harness 路由器 |
+| `Harness/SETUP.md` | 初次安装和 bootstrap 指南 |
+| `Harness/MEMORY.md` | agents、skills、记忆文件索引 |
+| `Harness/PLAN.md` | 当前计划、heartbeat、handoff、验证证据 |
+| `Harness/WF.md` | 长链路 workflow 和恢复循环 |
+| `Harness/subagents.md` | 多 subagents 编排方法论 |
+| `.claude/skills/*` | Claude Code 可加载的 Harness skills |
+
+## 验证
+
+```bash
+npm test
+node Harness/scripts/validate-harness.mjs
+```
+
+生成项目后，`Harness/scripts/validate-harness.mjs` 用于检查 Harness 结构、注册关系和必要规范是否完整。

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.1",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin/",
     "src/",
-    "templates/"
+    "templates/",
+    "README-CN.md"
   ],
   "scripts": {
     "start": "node src/index.js",

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: