create-harness-vibe-coding 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,169 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/create-harness-vibe-coding?color=blue" alt="npm version">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node">
+  <img src="https://img.shields.io/npm/l/create-harness-vibe-coding" alt="license">
+  <img src="https://img.shields.io/github/stars/zingspark/create-harness-vibe-coding?style=social" alt="stars">
+</p>
+
+<h1 align="center">⚡ create-harness-vibe-coding</h1>
+<p align="center">
+  <b>4 seconds from zero to a production-grade agentic harness.</b><br>
+  <sub>CLAUDE.md → docs/ → .claude/ → tests/ — ECC-ready, Superpowers-compatible.</sub>
+</p>
+
+---
+
+## 🎯 One Command
+
+```bash
+npx create-harness-vibe-coding@latest my-project
+```
+
+| What You Get | Count |
+|-------------|-------|
+| Architecture docs (layers, data flow, state machines, port contracts) | 9 docs |
+| Agent definitions (code-reviewer, risk-auditor, etc.) | ECC-ready skeleton |
+| Workflow skills (TDD, backtest, data pipeline) | ECC-ready skeleton |
+| Coding rules (universal + language-specific) | common.md included |
+| Settings & hooks (permissions, automation) | pre-configured |
+| **Total files provisioned** | **17 docs + configs** |
+
+---
+
+## 🚀 Why This Exists
+
+Every Claude Code project has the same cold-start problem:
+
+| Without Harness | With `create-harness-vibe-coding` |
+|---|---|
+| ❌ Agents skip docs, hallucinate behavior | ✅ CLAUDE.md routes agents to exact docs by role |
+| ❌ No TDD enforcement — agents ship untested code | ✅ agent-workflow.md enforces RED-GREEN-REFACTOR |
+| ❌ Architecture boundaries blur over time | ✅ domain/ports.md locks layer contracts |
+| ❌ State machines live in someone's head | ✅ state-machines.md documents every transition |
+| ❌ Cross-session memory lost | ✅ MEMORY.md + self-learning system |
+| ❌ 2+ hours to set up project structure | ✅ **4 seconds** |
+
+---
+
+## 🧠 How It Works
+
+```mermaid
+graph LR
+    A[npx scaffold] --> B[CLAUDE.md + docs/ + .claude/]
+    B --> C[Start Claude Code]
+    C --> D[Claude reads SETUP.md]
+    D --> E[Pulls agents/skills/rules from ECC]
+    E --> F[Project ready — TDD loop active]
+```
+
+### What happens after `npx`:
+
+1. **CLAUDE.md** — Agent reads this first. Role-based routing table sends each agent to the right docs.
+2. **docs/architecture.md** — Clean architecture layers. Harness runs the shell; domain defines the business.
+3. **docs/agent-workflow.md** — TDD loop, subagent roles, write set rules, conflict resolution.
+4. **docs/data-flow.md** — Every event's normal path + failure branches — the #1 doc AI fabricates without.
+5. **docs/state-machines.md** — Every stateful component. Transition table. Illegal transitions explicitly denied.
+6. **.claude/settings.json** — Permissions pre-configured (allow git/npm/pytest, deny rm/sudo/curl). Hooks ready.
+7. **SETUP.md** — Temporary guide. Claude reads it, pulls agents/skills/rules from [ECC](https://github.com/affaan-m/ECC). User deletes it after.
+
+---
+
+## 📦 What's Inside
+
+```
+my-project/
+├── CLAUDE.md              ← Role-based doc navigation + memory/self-learning
+├── AGENTS.md              ← Coding agent entry
+├── MEMORY.md              ← Cross-session resource index
+├── SETUP.md               ← Temporary init guide (delete after setup)
+├── .gitignore
+├── docs/
+│   ├── README.md          ← Project doc entry point
+│   ├── harness/
+│   │   ├── 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
+│   ├── features/
+│   │   └── _template.md          ← Kiro-lite feature doc template
+│   └── research/
+│       ├── PRD.md                ← MVP scope & acceptance template
+│       └── scaffolds.md          ← Tech research & decision record
+├── .claude/
+│   ├── settings.json     ← Permissions + hooks
+│   ├── agents/           ← Pull from ECC
+│   ├── skills/           ← Pull from ECC
+│   ├── hooks/            ← Configure as needed
+│   └── rules/ecc/
+│       └── common.md     ← Universal coding rules (always active)
+└── tests/                ← Your test suite goes here
+```
+
+---
+
+## 🌐 Ecosystem Compatibility
+
+| Platform | Status |
+|----------|--------|
+| [ECC](https://github.com/affaan-m/ECC) (206K+ ★) | ✅ Agents, skills, rules auto-pull |
+| [Superpowers](https://github.com/obra/superpowers) (185K+ ★) | ✅ `/plugin install superpowers` |
+| [awesome-claude-code-config](https://github.com/Mizoreww/awesome-claude-code-config) | ✅ Rules & self-learning configs |
+| [claude-toolbox](https://github.com/serpro69/claude-toolbox) | ✅ Multi-language skills |
+| Claude Code | ✅ Native settings.json + hooks |
+| Codex / Cursor / Gemini CLI | ✅ Compatible (docs-only pattern) |
+
+---
+
+## 🔧 Usage
+
+```bash
+# Interactive mode
+npx create-harness-vibe-coding@latest
+
+# Non-interactive (CI/CD)
+npx create-harness-vibe-coding@latest my-app ./dist/my-app
+
+# Always get the latest version
+npx create-harness-vibe-coding@latest my-project
+```
+
+### After scaffolding, tell Claude:
+
+```
+"Read SETUP.md. This is a Python quant project. Pull agents, skills, and rules from ECC."
+"Read SETUP.md. This is a React TypeScript app. I need TDD workflow and code review."
+"Read SETUP.md. This is a Go microservice. Set up matching agents and testing skills."
+```
+
+---
+
+## 📊 Performance
+
+| Metric | Value |
+|--------|-------|
+| Cold install + scaffold | < 4s |
+| Package size | 19.9 kB |
+| Unpacked | 49.4 kB |
+| Dependencies | 2 (@clack/prompts, picocolors) |
+| Node requirement | ≥ 18 |
+| Zero runtime deps after scaffold | ✅ |
+
+---
+
+## 👥 Contributing
+
+PRs welcome. The template docs live in `templates/common/` — edit them to change what gets scaffolded.
+
+---
+
+## 📄 License
+
+MIT © [zingspark](https://github.com/zingspark)
+
+---
+
+<p align="center">
+  <sub>Built for the vibe-coding era. Scaffold fast, build faster.</sub>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Scaffold a vibe-coding agentic harness — CLAUDE.md, docs/, .claude skeleton ready for ECC agents/skills/rules",
   "type": "module",
   "bin": {
@@ -23,8 +23,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/LiWeny16/q-profit.git",
-    "directory": "create-harness-vibe-coding"
+    "url": "https://github.com/zingspark/create-harness-vibe-coding.git"
   },
   "keywords": [
     "claude-code",

package/src/generator.js

@@ -8,7 +8,6 @@ const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates', 'common');
 
 /**
  * Copy a directory recursively, replacing {{vars}} in file contents.
- * Skips dirs named '.gitkeep-placeholder'.
  */
 function copyDir(src, dest, vars) {
   fs.mkdirSync(dest, { recursive: true });
@@ -64,7 +63,7 @@ export function generate({ projectName, targetDir }) {
   if (fs.existsSync(resolvedDir)) {
     const existing = fs.readdirSync(resolvedDir).filter(f => f !== '.git');
     if (existing.length > 0) {
-      console.log(pc.yellow(`⚠ 目录 "${targetDir}" 已存在且非空，文件可能被覆盖`));
+      console.log(pc.yellow(`⚠ Directory "${targetDir}" already exists and is not empty. Files may be overwritten.`));
     }
   }
 
@@ -72,14 +71,14 @@ export function generate({ projectName, targetDir }) {
 
   try {
     // 1. Copy all template files
-    console.log(pc.cyan('📋 复制模板文件...'));
+    console.log(pc.cyan('📋 Copying templates...'));
     copyDir(TEMPLATES_DIR, resolvedDir, vars);
 
     // List all created files from templates
     created.push(...walkFiles(TEMPLATES_DIR).map(f => f.replace(/\\/g, '/')));
 
     // 2. Create empty directories
-    console.log(pc.cyan('📁 创建占位目录...'));
+    console.log(pc.cyan('📁 Creating placeholder directories...'));
     const emptyDirs = [
       '.claude/agents',
       '.claude/skills',

package/src/index.js

@@ -24,9 +24,9 @@ if (argName) {
   targetDir = argDir || `./${projectName}`;
 
   console.log(pc.dim('────────────────────────────────────────────'));
-  console.log(`  项目名称  ${pc.green(projectName)}`);
-  console.log(`  目标目录  ${pc.green(targetDir)}`);
-  console.log(`  将创建    ${pc.cyan('CLAUDE.md, docs/, .claude/, SETUP.md, tests/')}`);
+  console.log(`  Project     ${pc.green(projectName)}`);
+  console.log(`  Directory   ${pc.green(targetDir)}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, docs/, .claude/, SETUP.md, tests/')}`);
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
@@ -37,30 +37,29 @@ if (argName) {
   try {
     projectName = await askProjectName();
   } catch {
-    // Fallback for non-TTY
     projectName = 'my-vibe-project';
-    console.log(pc.dim(`  项目名称: ${projectName} (默认)`));
+    console.log(pc.dim(`  Project: ${projectName} (default)`));
   }
 
   try {
     targetDir = await askTargetDir(projectName);
   } catch {
     targetDir = `./${projectName}`;
-    console.log(pc.dim(`  目标目录: ${targetDir} (默认)`));
+    console.log(pc.dim(`  Directory: ${targetDir} (default)`));
   }
 
   console.log('');
   console.log(pc.dim('────────────────────────────────────────────'));
-  console.log(`  项目名称  ${pc.green(projectName)}`);
-  console.log(`  目标目录  ${pc.green(targetDir)}`);
-  console.log(`  将创建    ${pc.cyan('CLAUDE.md, docs/, .claude/, SETUP.md, tests/')}`);
+  console.log(`  Project     ${pc.green(projectName)}`);
+  console.log(`  Directory   ${pc.green(targetDir)}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, docs/, .claude/, SETUP.md, tests/')}`);
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
   let proceed = true;
   try {
     proceed = await p.confirm({
-      message: '确认生成?',
+      message: 'Confirm generation?',
       initialValue: true,
     });
     if (p.isCancel(proceed)) proceed = false;
@@ -69,7 +68,7 @@ if (argName) {
   }
 
   if (!proceed) {
-    p.cancel('已取消');
+    p.cancel('Cancelled');
     process.exit(0);
   }
 
@@ -80,24 +79,24 @@ if (argName) {
 
 function printResult(result, targetDir) {
   if (result.success) {
-    console.log(pc.green(`\n✅ 项目已创建! 共 ${result.created.length} 个文件\n`));
+    console.log(pc.green(`\n✅ Project created! ${result.created.length} files\n`));
 
-    console.log(pc.bold('下一步:'));
+    console.log(pc.bold('Next steps:'));
     console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
-    console.log(`  ${pc.cyan('claude')}                          # 启动 Claude Code`);
-    console.log(`  告诉 Claude: "${pc.yellow('阅读 SETUP.md 并帮我初始化项目')}"`);
+    console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
+    console.log(`  Tell Claude: "${pc.yellow('Read SETUP.md and initialize this project')}"`);
     console.log('');
-    console.log(pc.dim('  SETUP.md 是临时文件，初始化完成后可删除'));
+    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} 个警告:`));
+      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('\n❌ 生成失败:'));
+    console.log(pc.red('\n❌ Generation failed:'));
     for (const err of result.errors) {
       console.log(pc.red(`  - ${err}`));
     }

package/src/prompts.js

@@ -3,18 +3,18 @@ import pc from 'picocolors';
 
 export async function askProjectName() {
   const name = await p.text({
-    message: '项目名称?',
+    message: 'Project name?',
     placeholder: 'my-vibe-project',
     defaultValue: 'my-vibe-project',
     validate(value) {
-      if (!value.trim()) return '项目名不能为空';
-      if (!/^[a-zA-Z0-9_-]+$/.test(value)) return '只允许字母、数字、连字符和下划线';
+      if (!value.trim()) return 'Project name is required';
+      if (!/^[a-zA-Z0-9_-]+$/.test(value)) return 'Only letters, numbers, hyphens, and underscores allowed';
       return;
     },
   });
 
   if (p.isCancel(name)) {
-    p.cancel('已取消');
+    p.cancel('Cancelled');
     process.exit(0);
   }
 
@@ -23,17 +23,17 @@ export async function askProjectName() {
 
 export async function askTargetDir(projectName) {
   const dir = await p.text({
-    message: '目标目录?',
+    message: 'Target directory?',
     placeholder: `./${projectName}`,
     defaultValue: `./${projectName}`,
     validate(value) {
-      if (!value.trim()) return '目录不能为空';
+      if (!value.trim()) return 'Directory is required';
       return;
     },
   });
 
   if (p.isCancel(dir)) {
-    p.cancel('已取消');
+    p.cancel('Cancelled');
     process.exit(0);
   }
 

package/templates/common/CLAUDE.md

@@ -1,22 +1,23 @@
 # CLAUDE.md
 
-## 📖 文档导航（每次任务前必读）
+## 📖 Doc Navigation (read before every task)
 
-`@docs/README.md` 是项目事实源入口。收到任务后，按角色走：
+`@docs/README.md` is the project fact source. Route by role:
 
-| 你的角色 | 必读文档 |
-|---------|---------|
-| 写代码 / 实现功能 | `docs/harness/agent-workflow.md` → `docs/features/_template.md` |
-| 设计架构 / 新增模块 | `docs/harness/architecture.md` → `docs/domain/ports.md` |
-| 审查代码 | `docs/harness/state-machines.md` → tests |
-| 修 bug / 排查问题 | `docs/harness/data-flow.md` → `docs/harness/state-machines.md` |
-| 不熟悉项目 | `docs/research/PRD.md` → `docs/harness/architecture.md` |
+| Your Role | Required Reading |
+|-----------|-----------------|
+| Writing code / implementing | `docs/harness/agent-workflow.md` → `docs/features/_template.md` |
+| Designing architecture / new modules | `docs/harness/architecture.md` → `docs/domain/ports.md` |
+| Reviewing code | `docs/harness/state-machines.md` → tests |
+| Fixing bugs / debugging | `docs/harness/data-flow.md` → `docs/harness/state-machines.md` |
+| New to the project | `docs/research/PRD.md` → `docs/harness/architecture.md` |
 
-**硬规则**：
-- 碰跨层边界之前，必须读过 `docs/domain/ports.md`
-- 新增失败路径之前，必须读过 `docs/harness/data-flow.md`
-- 修改有状态组件之前，必须读过 `docs/harness/state-machines.md`
-- 不确定该不该开 feature doc？读 `docs/harness/agent-workflow.md` §1
+**Hard rules**:
+- Before touching cross-layer boundaries, read `docs/domain/ports.md`
+- Before adding failure paths, read `docs/harness/data-flow.md`
+- Before modifying stateful components, read `docs/harness/state-machines.md`
+- Unsure whether to open a feature doc? Read `docs/harness/agent-workflow.md` §1
+- **Every new session must read `@MEMORY.md`** for accumulated context
 
 ---
 
@@ -86,52 +87,53 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 ---
 
-## 5. 记忆与自学习
+## 5. Memory & Self-Learning
 
-遇到用户表达"记住 / 偏好 / 习惯 / 纠正"意图时，**持久化到 `MEMORY.md`**，让后续会话能复用。
+When a user expresses "remember / preference / habit / correction" intent, **persist to `MEMORY.md`** for reuse across sessions.
+**Important**: Every new session must read `@MEMORY.md`.
 
-### 5.1 触发词
+### 5.1 Trigger Words
 
-当用户消息包含以下关键词或意图时，必须写入 `MEMORY.md`：
+When the user's message contains these keywords or intent, write to `MEMORY.md`:
 
-| 触发词/句式 | 含义 | 写入栏目 |
+| Trigger Phrase | Meaning | Write To |
 |---|---|---|
-| "记住…"、"记下…"、"帮我记住…" | 用户想持久化一条事实/偏好 | User Mem |
-| "以后不要…"、"下次别…"、"别再…" | 用户纠正某个行为，以后避免 | User Mem |
-| "下次记得…"、"以后都…"、"以后遇到…就…" | 用户指定未来的默认行为 | User Mem |
-| "我喜欢…"、"我习惯…"、"我偏好…" | 用户表达工作习惯或偏好 | User Mem |
+| "remember…", "note…", "save…" | User wants to persist a fact/preference | User Mem |
+| "don't ever…", "never…", "stop doing…" | User corrects a behavior — avoid in future | User Mem |
+| "next time…", "always…", "from now on…" | User specifies a future default behavior | User Mem |
+| "I prefer…", "I like…", "my workflow…" | User expresses a work habit or preference | User Mem |
 
-如果消息是否触发记忆有歧义，先问用户确认再写入。不要为每次对话自动记录。
+If unclear whether a message triggers memory, ask the user before writing. Don't auto-record every conversation.
 
-### 5.2 MEMORY.md 写入格式
+### 5.2 MEMORY.md Write Format
 
-在 `MEMORY.md` 的 `## User Mem` 栏目下，按日期倒序追加。每条格式：
+Append to `## User Mem` in `MEMORY.md`, newest first:
 
 ```markdown
-### YYYY-MM-DD — <简短标题>
-- **触发词**：<用户原话>
-- **行为**：<以后应该怎么做 / 避免做什么>
-- **原因**：<用户说明的原因，如果有>
+### YYYY-MM-DD — <short title>
+- **Trigger**: <user's exact words>
+- **Behavior**: <what to do / what to avoid going forward>
+- **Why**: <user's reason, if provided>
 ```
 
-### 5.3 自学习：工具调用规范
+### 5.3 Self-Learning: Tool Usage Standards
 
-Claude Code 发现以下模式时，在不涉及用户隐私的前提下，自动追加到 `MEMORY.md` 的 `## 工具调用规范` 栏目：
+When Claude Code discovers the following patterns (without involving user privacy), auto-append to `## Tool Usage Standards` in `MEMORY.md`:
 
-| 发现模式 | 记录内容 |
+| Pattern Discovered | Record |
 |---|---|
-| 某工具/MCP/skill 连续 3 次以上被高频调用但每次都失败或有更优替代 | 记录：场景 → 失败原因 → 推荐替代方案 |
-| 某类代码错误反复出现在同一文件/模块（如 lint 报错、类型错误、导入错误） | 记录：错误类型 → 触发条件 → 修复模板 |
-| 某个 skill/MCP 的调用方式与最佳实践不符导致低效 | 记录：正确用法 → 避免的用法 |
+| A tool/MCP/skill fails 3+ times when called frequently, or has a better alternative | Record: scenario → failure cause → recommended alternative |
+| A code error repeats in the same file/module (lint errors, type errors, import errors) | Record: error type → trigger condition → fix template |
+| A skill/MCP is called in a way that deviates from best practices, causing inefficiency | Record: correct usage → usage to avoid |
 
-格式：
+Format:
 
 ```markdown
-### <工具名/skill名> — <问题简述>
-- **场景**：<什么情况下触发>
-- **问题**：<具体现象>
-- **方案**：<推荐做法>
-- **日期**：<首次记录日期>
+### <tool/skill name> — <brief issue>
+- **Scenario**: <when it triggers>
+- **Problem**: <specific symptom>
+- **Solution**: <recommended approach>
+- **Date**: <first recorded date>
 ```
 
-如果同一问题已存在记录，更新其内容而非新增一条。如果新发现与旧记录矛盾，替换旧记录并标注日期。
+If the same issue already exists, update it rather than creating a duplicate. If a new finding contradicts an old record, replace the old one and note the date.

package/templates/common/MEMORY.md

@@ -1,35 +1,35 @@
-# MEMORY.md — {{projectName}} 项目资源索引
+# MEMORY.md — {{projectName}} Project Resource Index
 
-> 当前项目事实源从 `CLAUDE.md -> docs/README.md` 进入。此文件用于跨会话持久化：资源索引、用户偏好、工具调用规范。
+> 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.
 
-## Agents（子代理）
+## Agents (Sub-agents)
 
-> 待 Claude Code 从 [ECC](https://github.com/affaan-m/ECC) 初始化。
-> 初始化命令：在 Claude Code 中描述你的项目类型和语言，Claude 会自动拉取匹配的 agents。
+> Pending initialization by Claude Code from [ECC](https://github.com/affaan-m/ECC).
+> Init command: describe your project type and language to Claude — it will pull matching agents.
 
-## Skills（工作流）
+## Skills (Workflows)
 
-> 待 Claude Code 从 [ECC](https://github.com/affaan-m/ECC) 或 [awesome-claude-code-config](https://github.com/Mizoreww/awesome-claude-code-config) 初始化。
+> Pending initialization by Claude Code from [ECC](https://github.com/affaan-m/ECC) or [awesome-claude-code-config](https://github.com/Mizoreww/awesome-claude-code-config).
 
-## Rules（代码规则）
+## Rules (Code Rules)
 
-放在 `.claude/rules/ecc/` 下，由 CC 引擎自动加载：
+Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
 
-- [common.md](.claude/rules/ecc/common.md) — 通用编码规则（alwaysApply: true）
-- 语言专属规则待 Claude Code 初始化（如 python.md、typescript.md 等）
+- [common.md](.claude/rules/ecc/common.md) — Universal coding rules (alwaysApply: true)
+- Language-specific rules pending Claude Code initialization (e.g. python.md, typescript.md, etc.)
 
-## Harness（运行时）
+## Harness (Runtime)
 
-- [架构文档](docs/harness/architecture.md)
-- [Agent 工作流](docs/harness/agent-workflow.md)
+- [Architecture docs](docs/harness/architecture.md)
+- [Agent workflow](docs/harness/agent-workflow.md)
 
 ## User Mem
 
-> 用户偏好、习惯、纠正指令。由 CLAUDE.md §5 触发写入，日期倒序。
-> 当前无记录 — 等待用户首次"记住…"指令。
+> User preferences, habits, corrections. Written by CLAUDE.md §5 triggers, newest first.
+> No entries yet — awaiting first "remember…" instruction.
 
-## 工具调用规范
+## Tool Usage Standards
 
-> Claude Code 自学习记录：高频工具/MCP/skill 的坑、替代方案、常见错误修复模板。
-> 由 CLAUDE.md §5.3 触发写入。
-> 当前无记录 — 等待首次自动发现。
+> Claude Code self-learning: high-frequency tool/MCP/skill pitfalls, alternatives, common error fix templates.
+> Written by CLAUDE.md §5.3 triggers.
+> No entries yet — awaiting first auto-discovery.

package/templates/common/SETUP.md

@@ -1,67 +1,67 @@
-# SETUP.md — 项目初始化指南
+# SETUP.md — Project Initialization Guide
 
-> ⚠️ **临时文件** — 本文件在初始化完成后应删除：`rm SETUP.md`
+> ⚠️ **Temporary file** — Delete after initialization: `rm SETUP.md`
 
 ---
 
-## 你现在拥有了什么
+## What You Just Created
 
-`npx create-harness-vibe-coding` 为你搭建了一个 **vibe-coding agentic harness** 骨架：
+`npx create-harness-vibe-coding` scaffolded a **vibe-coding agentic harness** skeleton:
 
 ```
 {{projectName}}/
-  CLAUDE.md              ← Agent 行为规范 + 记忆自学习系统
-  AGENTS.md              ← Coding agent 入口
-  MEMORY.md              ← 跨会话资源索引
-  docs/                  ← 架构文档（分层规则、工作流、端口合同）
+  CLAUDE.md              ← Agent behavior guidelines + memory/self-learning system
+  AGENTS.md              ← Coding agent entry point
+  MEMORY.md              ← Cross-session resource index
+  docs/                  ← Architecture docs (layer rules, workflows, port contracts)
   .claude/
-    settings.json        ← 权限 + Hooks 配置
-    agents/              ← 空 — 待拉取 ECC agents
-    skills/              ← 空 — 待拉取 ECC skills
-    hooks/               ← 空 — 待配置自动化钩子
+    settings.json        ← Permissions + Hooks config
+    agents/              ← Empty — pull ECC agents here
+    skills/              ← Empty — pull ECC skills here
+    hooks/               ← Empty — configure automation hooks here
     rules/ecc/
-      common.md          ← 通用编码规则（始终生效）
-  tests/                 ← 待初始化
-  .gitignore             ← 基础 Git 忽略规则
+      common.md          ← Universal coding rules (always active)
+  tests/                 ← Pending initialization
+  .gitignore             ← Basic Git ignore rules
 ```
 
 ---
 
-## 下一步：用 Claude Code 初始化项目内容
+## Next Steps: Initialize with Claude Code
 
-### Step 1 — 启动 Claude Code
+### Step 1 — Start Claude Code
 
 ```bash
 claude
 ```
 
-### Step 2 — 描述你的项目
+### Step 2 — Describe Your Project
 
-告诉 Claude 你的项目类型、语言和技术栈。Claude 会：
+Tell Claude your project type, language, and tech stack. Claude will:
 
-1. 从 [ECC](https://github.com/affaan-m/ECC) 拉取匹配的 **agents**（如 code-reviewer、planner、security-reviewer）
-2. 从 ECC 拉取匹配的 **skills**（如 tdd-workflow、django-patterns、react-patterns）
-3. 从 ECC 拉取对应语言的 **rules**（如 python.md、typescript.md）
-4. 根据项目需要配置 **hooks**（如 PostToolUse 自动 lint、PreToolUse 安全门禁）
+1. Pull matching **agents** from [ECC](https://github.com/affaan-m/ECC) (e.g. code-reviewer, planner, security-reviewer)
+2. Pull matching **skills** from ECC (e.g. tdd-workflow, django-patterns, react-patterns)
+3. Pull language-specific **rules** from ECC (e.g. python.md, typescript.md)
+4. Configure **hooks** as needed (e.g. PostToolUse auto-lint, PreToolUse security gate)
 
-**对话示例**：
+**Example prompts**:
 
 ```
-你: 这是一个 Python 量化交易项目，帮我从 ECC 初始化 agents、skills 和 rules
-你: 这是一个 React + TypeScript 前端项目，需要 TDD workflow
-你: 这是一个 Go 微服务项目，帮我配置对应的代码审查和测试 skills
+You: This is a Python quant trading project. Initialize agents, skills, and rules from ECC.
+You: This is a React + TypeScript frontend project. I need the TDD workflow.
+You: This is a Go microservice project. Set up code review and testing skills.
 ```
 
-### Step 3 — 可选：安装 Superpowers 强化工程纪律
+### Step 3 — Optional: Install Superpowers
 
 ```bash
-# 在 Claude Code 中运行
+# Inside Claude Code
 /plugin install superpowers@claude-plugins-official
 ```
 
-Superpowers 提供：brainstorming → writing-plans → TDD → code-review 的完整闭环。
+Superpowers provides: brainstorming → writing-plans → TDD → code-review loop.
 
-### Step 4 — 初始化完成后
+### Step 4 — Clean Up
 
 ```bash
 rm SETUP.md
@@ -69,23 +69,23 @@ rm SETUP.md
 
 ---
 
-## 参考资源
+## Reference Resources
 
-| 资源 | 地址 | 用途 |
-|------|------|------|
-| ECC | https://github.com/affaan-m/ECC | Agents / Skills / Rules 主仓库 |
-| awesome-claude-code-config | https://github.com/Mizoreww/awesome-claude-code-config | 多语言规则 + 自学习配置 |
-| Superpowers | https://github.com/obra/superpowers | 工程纪律插件 |
-| claude-toolbox | https://github.com/serpro69/claude-toolbox | 多语言技能工具包 |
+| Resource | URL | Purpose |
+|----------|-----|---------|
+| ECC | https://github.com/affaan-m/ECC | Main agents/skills/rules repo |
+| awesome-claude-code-config | https://github.com/Mizoreww/awesome-claude-code-config | Multi-language rules + self-learning config |
+| Superpowers | https://github.com/obra/superpowers | Engineering discipline plugin |
+| claude-toolbox | https://github.com/serpro69/claude-toolbox | Multi-language skills toolkit |
 
 ---
 
-## 自定义
+## Customization
 
-- **CLAUDE.md** — 可按项目需求修改行为规范
-- **.claude/settings.json** — 按需调整权限和 hooks
-- **.claude/rules/ecc/** — 语言规则由 Claude Code 自动添加
+- **CLAUDE.md** — Edit behavior guidelines per project needs
+- **.claude/settings.json** — Adjust permissions and hooks as needed
+- **.claude/rules/ecc/** — Language rules auto-added by Claude Code
 
 ---
 
-> 本项目由 `create-harness-vibe-coding` 生成。保留 MIT 许可。
+> Generated by `create-harness-vibe-coding`. MIT License.

package/templates/common/docs/README.md

@@ -1,112 +1,112 @@
-# {{projectName}} — 文档入口
+# {{projectName}} — Docs Entry Point
 
-> **定位**：给人和 coding agent 共用的项目地图。`AGENTS.md` 负责让 agent 先读 `CLAUDE.md`，再从这里进入项目事实源。
+> **Purpose**: A shared project map for humans and coding agents. `AGENTS.md` tells agents to read `CLAUDE.md` first, then enter the project fact source from here.
 >
-> **原则**：短入口 + 分主题文档。不要把所有规则塞进 `CLAUDE.md` 或 `AGENTS.md`。
+> **Principle**: Short entry + topic-specific docs. Don't cram everything into `CLAUDE.md` or `AGENTS.md`.
 
 ---
 
-## 0-1 项目必经流程
+## 0-1 Required Project Flow
 
-从零开始做一个项目时，必须按下面顺序产出文档。前一阶段没有最低可用结论，不进入后一阶段。
+When starting from scratch, produce docs in this order. Don't move to the next phase without a minimum viable conclusion from the previous one.
 
-| 顺序 | 产物 | 必须回答的问题 | 完成标准 |
+| Order | Artifact | Must Answer | Completion Standard |
 | --- | --- | --- | --- |
-| 1 | [research/scaffolds.md](research/scaffolds.md) | 别人怎么做？有哪些候选模板、框架、约束？为什么采用/不采用？ | 至少 3 个参考物；每个写清 Purpose / Strength / Weakness / Decision |
-| 2 | [research/PRD.md](research/PRD.md) | 这个 MVP 到底解决什么？明确不做什么？怎么验收？ | 一页内；包含 MVP、Non-goals、可验证验收标准 |
-| 3 | [harness/architecture.md](harness/architecture.md) | 系统分几层？组件边界是什么？harness 能做什么、不能做什么？ | 分层依赖、核心组件、不可违反约束、关键决策都写清 |
-| 4 | [domain/ports.md](domain/ports.md) | 层与层之间用什么合同通信？错误和幂等语义是什么？ | 每个端口有前置条件、后置条件、错误语义、已知实现 |
-| 5 | [harness/data-flow.md](harness/data-flow.md) | 正常路径和失败路径怎么跑？调用方看到什么？ | 至少 1 条核心流程；每个失败点都有系统行为和恢复方式 |
-| 6 | [harness/state-machines.md](harness/state-machines.md) | 哪些组件有状态？哪些转移合法/非法？ | 每个有状态组件有状态枚举、转移表、非法转移说明 |
-| 7 | [harness/agent-workflow.md](harness/agent-workflow.md) | agent 怎么分工、TDD、验证和闭环？ | Feature doc 模板、subagent 分工、write set、完成标准写清 |
-| 8 | tests + implementation | 设计是否被代码证明？ | 最小垂直切片可运行；测试覆盖核心成功/失败路径 |
-
-**硬门槛**：
-- 如果相关文档仍然只剩 `{{...}}` 占位符，不要声称架构已定稿。
-- **最小可开始编码的文档集**：`research/PRD.md` + `harness/architecture.md` + 至少 1 个已填好的端口合同。达到这个门槛后可以开始最小垂直切片，但必须在 feature doc 或测试里记录尚未补齐的 `data-flow.md` / `state-machines.md` 风险。
-- 如果新增或修改架构边界，必须同步更新对应文档和测试。
-- 如果实现需要超过一个短会话，先按 [features/_template.md](features/_template.md) 开 feature doc；feature doc 必须包含目的、边界、任务、验证、决策记录。
-
-## 每份文档的完成标准
-
-| 文档 | 最低完成标准 | 可以暂缺 |
+| 1 | [research/scaffolds.md](research/scaffolds.md) | What do others do? Which templates, frameworks, constraints? Why adopt/reject? | At least 3 references; each with Purpose / Strength / Weakness / Decision |
+| 2 | [research/PRD.md](research/PRD.md) | What does this MVP solve? What is explicitly NOT in scope? How to verify? | One page; MVP, Non-goals, verifiable acceptance criteria |
+| 3 | [harness/architecture.md](harness/architecture.md) | How many layers? Component boundaries? What can/can't harness do? | Layer dependencies, core components, non-negotiable constraints, key decisions |
+| 4 | [domain/ports.md](domain/ports.md) | What contracts between layers? Error and idempotency semantics? | Each port: preconditions, postconditions, error semantics, known implementations |
+| 5 | [harness/data-flow.md](harness/data-flow.md) | Normal path and failure paths? What does the caller see? | At least 1 core flow; each failure point has system behavior and recovery |
+| 6 | [harness/state-machines.md](harness/state-machines.md) | Which components have state? Which transitions are legal/illegal? | Each stateful component: state enum, transition table, illegal transitions |
+| 7 | [harness/agent-workflow.md](harness/agent-workflow.md) | How do agents divide work, TDD, verify, and close? | Feature doc template, subagent roles, write set, completion criteria |
+| 8 | tests + implementation | Is the design proven by code? | Minimal vertical slice runs; tests cover core success/failure paths |
+
+**Hard gates**:
+- If a doc still has `{{...}}` placeholders, don't claim the architecture is finalized.
+- **Minimum docs to start coding**: `research/PRD.md` + `harness/architecture.md` + at least 1 filled port contract. Once there, start a minimal vertical slice, but record risks from missing `data-flow.md` / `state-machines.md` in the feature doc or tests.
+- If architecture boundaries change, sync docs and tests.
+- If implementation spans more than one short session, open a feature doc from [features/_template.md](features/_template.md) first.
+
+## Doc Completion Standards
+
+| Doc | Minimum Standard | Can Defer |
 | --- | --- | --- |
-| `research/scaffolds.md` | 至少 3 个参考物；每个有 Purpose / Strength / Weakness / Decision；有最终决策 | 被放弃方案可后补 |
-| `research/PRD.md` | Why、MVP、Non-goals、决策优先级、验收标准都不是占位符 | 非功能性指标可先写 MVP 级目标 |
-| `harness/architecture.md` | 分层依赖、核心组件、至少 1 条 ADR、不可违反约束 | Runner 变体可在只有一种 runner 时写"暂无" |
-| `domain/ports.md` | 至少 1 个端口有前置条件、后置条件、错误语义、幂等性、已知实现 | 后续端口可随 feature 增量补 |
-| `harness/data-flow.md` | 至少 1 条核心流程有正常路径 + 失败路径 | 次要流程可后补 |
-| `harness/state-machines.md` | 已有有状态组件都有状态枚举和转移表 | 无状态组件不用写 |
-| `harness/agent-workflow.md` | 开 feature doc、write set、验证、关闭标准明确 | subagent 角色可按需要扩展 |
-| `features/*.md` | Requirements / Design / Tasks / Verification 四段闭环 | 小修可走快车道并说明原因 |
+| `research/scaffolds.md` | At least 3 references; each with Purpose / Strength / Weakness / Decision; final decision recorded | Rejected options can be backfilled |
+| `research/PRD.md` | Why, MVP, Non-goals, decision priorities, acceptance criteria are not placeholders | Non-functional targets can start as MVP-level goals |
+| `harness/architecture.md` | Layer dependencies, core components, at least 1 ADR, non-negotiable constraints | Runner variants can say "none yet" when only one runner exists |
+| `domain/ports.md` | At least 1 port with preconditions, postconditions, error semantics, idempotency, known impls | Additional ports can be added incrementally with features |
+| `harness/data-flow.md` | At least 1 core flow with normal + failure paths | Secondary flows can come later |
+| `harness/state-machines.md` | Every stateful component has state enum and transition table | Stateless components don't need entries |
+| `harness/agent-workflow.md` | Feature doc, write set, verification, closure criteria are clear | Subagent roles can expand as needed |
+| `features/*.md` | Requirements / Design / Tasks / Verification closed loop | Minor fixes can take the fast lane with a reason |
 
 ---
 
-## Harness 边界
+## Harness Boundary
 
-当前模板采用 `interfaces -> harness -> application -> domain` 加 `infrastructure` 适配器的分层思路。这里的 `domain` 是任意业务域：数据分析、文档处理、代码修复、运营自动化等都可以挂在同一个 harness 底座上。
+The current template uses `interfaces -> harness -> application -> domain` with `infrastructure` adapters. The `domain` is any business domain: data analysis, document processing, code repair, ops automation — all can hang off the same harness.
 
-| 层 | 负责 | 不负责 |
+| Layer | Responsible For | NOT Responsible For |
 | --- | --- | --- |
-| `interfaces/` | CLI / API / UI 入口 | 业务规则、数据源细节 |
-| `harness/` | 运行外壳、调度、安全门、审计、可观测性、失败控制 | 领域业务规则、领域决策、适配器实现细节 |
-| `application/` | 用例编排，把领域端口组合成业务行为 | 具体外部服务实现 |
-| `domain/` | 业务对象、业务不变量、端口协议 | 导入 harness / infrastructure / interfaces |
-| `infrastructure/` | 文件系统、数据库、外部 API、模型服务等端口实现 | 定义业务合同 |
+| `interfaces/` | CLI / API / UI entry points | Business rules, data source details |
+| `harness/` | Runtime shell, scheduling, safety gates, audit, observability, failure control | Domain business rules, domain decisions, adapter implementation details |
+| `application/` | Use-case orchestration, composing domain ports into business actions | Specific external service implementations |
+| `domain/` | Business objects, business invariants, port protocols | Importing harness / infrastructure / interfaces |
+| `infrastructure/` | Filesystem, database, external API, model service port implementations | Defining business contracts |
 
-判断一段代码该不该在 `harness/`：如果它是在"运行期间保护、记录、调度、恢复系统"，放 harness；如果它是在"决定某个业务动作是否应该发生、代表什么领域含义"，放 application/domain。
+How to decide: if it "protects, records, schedules, recovers the system during runtime" → harness. If it "decides whether a business action should happen and what it means" → application/domain.
 
 ---
 
-## 文档地图
+## Doc Map
 
 ```text
 docs/
-├── README.md                       ← 你在这里
+├── README.md                       ← You are here
 ├── features/
-│   └── _template.md                ← 单功能实现文档模板（Kiro-lite）
+│   └── _template.md                ← Single-feature implementation doc template (Kiro-lite)
 ├── harness/
-│   ├── agent-workflow.md           ← agent 分工、TDD、闭环、write set 规则
-│   ├── architecture.md             ← 组件全景、分层规则、关键设计决策
-│   ├── data-flow.md                ← 端到端事件流转：正常路径 + 异常路径
-│   └── state-machines.md           ← 有状态组件的状态转移图和转移表
+│   ├── agent-workflow.md           ← Agent roles, TDD, closure, write set rules
+│   ├── architecture.md             ← Component map, layer rules, key design decisions
+│   ├── data-flow.md                ← End-to-end event flow: normal + error paths
+│   └── state-machines.md           ← Stateful component transition diagrams and tables
 ├── domain/
-│   └── ports.md                    ← 跨层接口契约：前置/后置、错误语义
+│   └── ports.md                    ← Cross-layer interface contracts: pre/post, error semantics
 └── research/
-    ├── PRD.md                      ← 一页 MVP 边界和验收标准模板
-    └── scaffolds.md                ← 调研结论、参考模板、技术选型理由
+    ├── PRD.md                      ← One-page MVP scope and acceptance template
+    └── scaffolds.md                ← Research conclusions, reference templates, tech rationale
 ```
 
 ---
 
-## 阅读顺序
+## Reading Order
 
-| 角色 | 先读 | 然后读 |
+| Role | Read First | Then |
 | --- | --- | --- |
-| 新加入开发者 | [research/PRD.md](research/PRD.md) | [harness/architecture.md](harness/architecture.md) |
-| 实现者 | [harness/agent-workflow.md](harness/agent-workflow.md) | [features/_template.md](features/_template.md) |
-| 审查者 | [harness/state-machines.md](harness/state-machines.md) | tests |
-| 架构维护者 | [research/scaffolds.md](research/scaffolds.md) | [harness/architecture.md](harness/architecture.md) |
+| New developer | [research/PRD.md](research/PRD.md) | [harness/architecture.md](harness/architecture.md) |
+| Implementer | [harness/agent-workflow.md](harness/agent-workflow.md) | [features/_template.md](features/_template.md) |
+| Reviewer | [harness/state-machines.md](harness/state-machines.md) | tests |
+| Architecture maintainer | [research/scaffolds.md](research/scaffolds.md) | [harness/architecture.md](harness/architecture.md) |
 
 ---
 
-## 维护规则
+## Maintenance Rules
 
-- 代码变更影响架构：更新 `harness/architecture.md`。
-- 新增跨层接口：更新 `domain/ports.md`。
-- 新增流程或失败路径：更新 `harness/data-flow.md`。
-- 新增有状态组件：更新 `harness/state-machines.md`。
-- 新增外部依赖、模板、框架选择：更新 `research/scaffolds.md`。
-- 新增非平凡功能：复制 `features/_template.md` 创建 feature doc，并按 `harness/agent-workflow.md` 闭环。
-- 文档规则反复被 agent 忽略：不要继续加长入口文件，把规则变成测试、lint 或更具体的模板。
+- Code change affects architecture → update `harness/architecture.md`.
+- New cross-layer interface → update `domain/ports.md`.
+- New flow or failure path → update `harness/data-flow.md`.
+- New stateful component → update `harness/state-machines.md`.
+- New external dependency, template, or framework choice → update `research/scaffolds.md`.
+- Non-trivial feature → copy `features/_template.md`, follow `harness/agent-workflow.md`.
+- Docs rules repeatedly ignored by agents → don't lengthen entry files; turn rules into tests, lint, or more specific templates.
 
 ---
 
-## 外部参考
+## External References
 
-- OpenAI, Harness Engineering: 短 `AGENTS.md` 作为目录，`docs/` 作为事实源；架构边界用测试/lint 机械化验证。
-- Anthropic, Claude Code Best Practices: `CLAUDE.md` 保持短且可维护，可用 `@docs/...` 引入项目文档。
-- OpenAI, PLANS.md / ExecPlans: 复杂任务使用自包含、可验证、可恢复的执行计划。
-- GitHub Spec Kit / Kiro Specs: 借用 requirements -> design -> tasks -> verification 的结构。
-- Anthropic, Building Effective Agents: agent loop 要基于环境反馈、明确停止条件和人工检查点。
-- arc42 / C4 / ADR / ARCHITECTURE.md: 分别提供架构章节、静态结构视图、决策记录和轻量代码地图。
+- OpenAI, Harness Engineering: short `AGENTS.md` as directory, `docs/` as fact source; architecture boundaries enforced by tests/lint.
+- Anthropic, Claude Code Best Practices: `CLAUDE.md` kept short and maintainable; use `@docs/...` to pull in project docs.
+- OpenAI, PLANS.md / ExecPlans: complex tasks use self-contained, verifiable, recoverable execution plans.
+- GitHub Spec Kit / Kiro Specs: borrow requirements -> design -> tasks -> verification structure.
+- Anthropic, Building Effective Agents: agent loops need environment feedback, clear stop conditions, and human checkpoints.
+- arc42 / C4 / ADR / ARCHITECTURE.md: provide architecture chapters, static structure views, decision records, and lightweight code maps respectively.