create-harness-vibe-coding 0.3.3 → 0.3.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README-CN.md +166 -49
- package/README.md +125 -331
- package/package.json +1 -1
package/README-CN.md
CHANGED
|
@@ -1,95 +1,212 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://img.shields.io/npm/v/create-harness-vibe-coding?color=blue" alt="npm">
|
|
3
|
+
<img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node">
|
|
4
|
+
<img src="https://img.shields.io/npm/l/create-harness-vibe-coding" alt="license">
|
|
5
|
+
<img src="https://img.shields.io/github/stars/zingspark/create-harness-vibe-coding?style=social" alt="stars">
|
|
6
|
+
</p>
|
|
2
7
|
|
|
3
|
-
|
|
8
|
+
<h1 align="center">create-harness-vibe-coding</h1>
|
|
9
|
+
<p align="center">
|
|
10
|
+
<b>给你的 AI Agent 一个脚手架。一条命令，告别漂移。</b>
|
|
11
|
+
</p>
|
|
4
12
|
|
|
5
|
-
##
|
|
13
|
+
## 一条命令。搞定。
|
|
6
14
|
|
|
7
15
|
```bash
|
|
8
16
|
npx create-harness-vibe-coding@latest my-project
|
|
9
17
|
```
|
|
10
18
|
|
|
11
|
-
|
|
19
|
+
## 一句话交给你的 Agent
|
|
12
20
|
|
|
13
|
-
|
|
21
|
+
已有项目？**不用读文档**。把这句话贴给它。Agent 知道该做什么。
|
|
14
22
|
|
|
15
23
|
```text
|
|
16
24
|
请按照 https://github.com/zingspark/create-harness-vibe-coding 的 README 为当前项目配置 create-harness-vibe-coding；编辑前先询问 Agent-link 安装前置问题；新项目走 0-1 bootstrap，老项目或老架构升级先 dry-run，保留现有文件，只合并缺失的 Harness 规范，然后遵循 Harness/SETUP.md。
|
|
17
25
|
```
|
|
18
26
|
|
|
19
|
-
|
|
27
|
+
就两条路：
|
|
28
|
+
- **你来**：敲上面那行 `npx`
|
|
29
|
+
- **交给 Agent**：贴上面那句话
|
|
30
|
+
|
|
31
|
+
[English README](README.md)
|
|
32
|
+
|
|
33
|
+
---
|
|
20
34
|
|
|
21
|
-
|
|
22
|
-
适合确定性写入、明确冲突策略、可重复 dry-run 的场景。
|
|
35
|
+
## 你能得到什么
|
|
23
36
|
|
|
24
|
-
|
|
25
|
-
|
|
37
|
+
| 得到 | 效果 |
|
|
38
|
+
|------|------|
|
|
39
|
+
| `CLAUDE.md` + `Harness/README.md` | Agent 从路由器开始，不是读长篇大论 |
|
|
40
|
+
| `Harness/tasks/` + `Harness/PROGRESS.md` | 跨会话追踪任务进度 |
|
|
41
|
+
| `/wf` 工作流 + 心跳 | 长任务不迷路，失败自动恢复 |
|
|
42
|
+
| `/wf update` | 从 GitHub 拉取脚手架最新改进 |
|
|
43
|
+
| `subagent-orchestrator` | 并行 Agent 不打架 |
|
|
44
|
+
| `memory-master` + `context-master` | 从失败中学习，上下文快满时压缩 |
|
|
45
|
+
| PRD + 调研模板 | 先问"做什么""为什么"，再写代码 |
|
|
46
|
+
| 11 个内置 Agent | 调研、规划、架构、测试、构建、审查、调试、验证 |
|
|
47
|
+
| 架构文档 | 知道边界在哪里 |
|
|
48
|
+
| 上下文加载协议 | 每个子 Agent 只读它需要的文档 |
|
|
49
|
+
| `.claude/` 骨架 | Agent、Skill、命令、钩子——开箱即用 |
|
|
50
|
+
|
|
51
|
+
---
|
|
26
52
|
|
|
27
|
-
##
|
|
53
|
+
## 为什么需要它
|
|
54
|
+
|
|
55
|
+
太多 AI 编程项目在代码写烂之前就死了。Agent 跳过思考直接写代码，忘记昨天的决策，上下文塞满整个仓库。
|
|
56
|
+
|
|
57
|
+
| 没有脚手架 | 有了它 |
|
|
58
|
+
|------------|--------|
|
|
59
|
+
| 想法 → 代码。赌一把。 | 想法 → 调研 → PRD → 架构 → 构建 → 验证 |
|
|
60
|
+
| Agent 读完整个仓库 | 路由器只加载需要的那份文档 |
|
|
61
|
+
| 子 Agent 收到一句模糊的"修一下" | 上下文包：角色、边界、返回格式 |
|
|
62
|
+
| 漂移只到演示时才暴露 | 验证器标记缺失项 |
|
|
63
|
+
| 长任务卡死，上下文爆炸 | `/wf` 心跳 + 恢复循环 |
|
|
64
|
+
| 脚手架腐烂 | `/wf update` 从 GitHub 拉最新版 |
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 怎么工作的
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
npx create-harness-vibe-coding@latest my-project
|
|
72
|
+
↓
|
|
73
|
+
Agent 读 Harness/SETUP.md
|
|
74
|
+
↓
|
|
75
|
+
路由器只加载任务需要的文档
|
|
76
|
+
↓
|
|
77
|
+
PRD → 调研 → 架构 → 第一个任务胶囊
|
|
78
|
+
↓
|
|
79
|
+
构建 → 测试 → 审查 → 验证 → 反馈
|
|
80
|
+
↓
|
|
81
|
+
/wf update 保持脚手架最新
|
|
82
|
+
```
|
|
28
83
|
|
|
29
84
|
```mermaid
|
|
30
85
|
graph TD
|
|
31
|
-
A[ /wf
|
|
86
|
+
A[ /wf 进入 ] --> B[ 探索: 3+ 并行 Agent ]
|
|
32
87
|
B --> C[ 二阶段计划 ]
|
|
33
|
-
C --> D[ 构建:
|
|
88
|
+
C --> D[ 构建: 测试 → 实现 ]
|
|
34
89
|
D --> E[ 双门禁审查 ]
|
|
35
90
|
E --> F{ 通过? }
|
|
36
|
-
F -->| 否 | G[
|
|
91
|
+
F -->| 否 | G[ 调试 → 修复 → 循环 ]
|
|
37
92
|
G --> E
|
|
38
|
-
F -->| 是 | H[ 收尾:
|
|
39
|
-
H --> I[ wf update
|
|
93
|
+
F -->| 是 | H[ 收尾: 记忆 + 上下文 ]
|
|
94
|
+
H --> I[ /wf update ]
|
|
40
95
|
```
|
|
41
96
|
|
|
42
|
-
|
|
97
|
+
---
|
|
43
98
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
| `Harness/README.md` | 文档路由器——按任务关键词加载最少文档 |
|
|
48
|
-
| `Harness/WF.md` | 长任务工作流：摄入 → 探索 → 计划 → 构建 → 审查 → 验证 → 恢复 |
|
|
49
|
-
| `Harness/PROGRESS.md` | 全局任务索引 |
|
|
50
|
-
| `Harness/tasks/<id>/` | 每任务胶囊：PROGRESS.md（进度+心跳）+ PLAN.md（实施+证据） |
|
|
51
|
-
| `.claude/agents/` | 11 个通用 Agent：planner, researcher, architect, implementer, reviewer, debugger, verifier, memory-master, context-master... |
|
|
52
|
-
| `.claude/skills/` | wf-mode, subagent-orchestrator, wf-update, harness-router... |
|
|
99
|
+
## 怎么用
|
|
100
|
+
|
|
101
|
+
### 新项目
|
|
53
102
|
|
|
54
|
-
|
|
103
|
+
```bash
|
|
104
|
+
npx create-harness-vibe-coding@latest my-project
|
|
105
|
+
cd my-project
|
|
106
|
+
# Agent 读 Harness/SETUP.md。搞定。
|
|
107
|
+
```
|
|
55
108
|
|
|
56
|
-
|
|
109
|
+
### 已有项目——安全合并
|
|
57
110
|
|
|
58
111
|
```bash
|
|
59
|
-
#
|
|
60
|
-
|
|
61
|
-
|
|
112
|
+
# 先预览。永远先预览。
|
|
113
|
+
npx create-harness-vibe-coding@latest my-app . -y --dry-run
|
|
114
|
+
|
|
115
|
+
# 只补缺失。绝不覆盖已有文件。
|
|
116
|
+
npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
|
|
62
117
|
```
|
|
63
118
|
|
|
64
|
-
|
|
119
|
+
| 参数 | 作用 |
|
|
120
|
+
|------|------|
|
|
121
|
+
| `-y` | 跳过所有提示 |
|
|
122
|
+
| `--dry-run` | 预览——不写任何文件 |
|
|
123
|
+
| `--on-conflict skip` | 保留你的文件，只创建新的 |
|
|
124
|
+
| `--on-conflict backup` | 备份已有 → 写入新的 |
|
|
125
|
+
| `--on-conflict overwrite` | 直接覆盖（谨慎） |
|
|
126
|
+
| `--list-options` | 列出可选工作流 |
|
|
127
|
+
| `--with <ids>` | 按 id 添加工作流 |
|
|
128
|
+
| `--preset <name>` | 添加 `web-app` 或 `fullstack` 预设 |
|
|
65
129
|
|
|
66
|
-
|
|
130
|
+
### 可选工作流
|
|
67
131
|
|
|
68
132
|
```bash
|
|
69
|
-
|
|
70
|
-
|
|
133
|
+
npx create-harness-vibe-coding@latest my-app -y --with browser-e2e
|
|
134
|
+
npx create-harness-vibe-coding@latest my-app -y --preset web-app
|
|
71
135
|
```
|
|
72
136
|
|
|
73
|
-
|
|
137
|
+
| 工作流 | 场景 |
|
|
138
|
+
|--------|------|
|
|
139
|
+
| `browser-e2e` | 截图、链路追踪、冒烟测试 |
|
|
140
|
+
| `ui-ux-review` | 响应式、无障碍、视觉润色 |
|
|
141
|
+
| `ts-react-frontend` | TypeScript + React + Vite |
|
|
142
|
+
| `python-backend` | FastAPI、pytest |
|
|
143
|
+
| `github-pr-review` | PR diff 审查 + CI 证据 |
|
|
74
144
|
|
|
75
|
-
|
|
76
|
-
# 先预览
|
|
77
|
-
npx create-harness-vibe-coding@latest my-app . -y --dry-run
|
|
145
|
+
### Agent 安装前置问题
|
|
78
146
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
147
|
+
当你的 Agent 读到上面那句"一句话"后，它会在动文件前**最多问 3 个问题**：
|
|
148
|
+
|
|
149
|
+
- 已经有 `CLAUDE.md` 或 `AGENTS.md`？→ 只合并，不替换
|
|
150
|
+
- `docs/` 已被产品文档占用？→ 把脚手架放 `Harness/` 目录
|
|
151
|
+
- 什么技术栈？→ 安装匹配的可选工作流
|
|
82
152
|
|
|
83
|
-
|
|
84
|
-
|----------|------|
|
|
85
|
-
| `fail`（默认） | 目标文件已存在则停止 |
|
|
86
|
-
| `skip` | 保留现有文件，只创建缺失 |
|
|
87
|
-
| `backup` | 备份 → 写入新文件 |
|
|
88
|
-
| `overwrite` | 直接覆盖 |
|
|
153
|
+
文件已存在就**先问再动**。默认永远**保留已有**。
|
|
89
154
|
|
|
90
|
-
|
|
155
|
+
### 脚手架完成后
|
|
156
|
+
|
|
157
|
+
```text
|
|
158
|
+
"读 Harness/SETUP.md。把这个项目引导起来。"
|
|
159
|
+
"用 /wf 处理这个长迁移。"
|
|
160
|
+
"/wf update — 拉取最新脚手架改进。"
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### 验证
|
|
91
164
|
|
|
92
165
|
```bash
|
|
93
166
|
npm test
|
|
94
167
|
node Harness/scripts/validate-harness.mjs
|
|
95
168
|
```
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## 文件结构
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
my-project/
|
|
176
|
+
├── CLAUDE.md ← Agent 入口
|
|
177
|
+
├── AGENTS.md ← Agent 注册表
|
|
178
|
+
├── .gitignore
|
|
179
|
+
├── Harness/
|
|
180
|
+
│ ├── README.md ← 文档路由器
|
|
181
|
+
│ ├── SETUP.md ← 引导指南（初始化后可删除）
|
|
182
|
+
│ ├── MEMORY.md ← 资源索引
|
|
183
|
+
│ ├── PROGRESS.md ← 任务追踪
|
|
184
|
+
│ ├── WF.md / WF-MAX.md ← 工作流模式
|
|
185
|
+
│ ├── tasks/ ← 每任务胶囊
|
|
186
|
+
│ ├── research/ ← PRD + 调研模板
|
|
187
|
+
│ ├── memory/ ← 持久自学习
|
|
188
|
+
│ └── scripts/ ← 验证器
|
|
189
|
+
├── .claude/
|
|
190
|
+
│ ├── agents/ ← 11 个通用 Agent
|
|
191
|
+
│ ├── skills/ ← Harness 加载器
|
|
192
|
+
│ ├── commands/ ← /wf、/wf update
|
|
193
|
+
│ └── rules/ ← 通用编码规则
|
|
194
|
+
└── tests/
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
`Harness/` 放所有脚手架文档。`.claude/` 留在根目录——Claude Code 在这里发现 Agent、Skill 和命令。
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## 足迹
|
|
202
|
+
|
|
203
|
+
| | |
|
|
204
|
+
|---|---|
|
|
205
|
+
| 运行时 | 无 |
|
|
206
|
+
| 依赖 | 2（`@clack/prompts`、`picocolors`） |
|
|
207
|
+
| Node | ≥ 18 |
|
|
208
|
+
| 生成代码 | 无——直到你选定技术栈 |
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
MIT © [zingspark](https://github.com/zingspark)
|
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="https://img.shields.io/npm/v/create-harness-vibe-coding?color=blue" alt="npm
|
|
2
|
+
<img src="https://img.shields.io/npm/v/create-harness-vibe-coding?color=blue" alt="npm">
|
|
3
3
|
<img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node">
|
|
4
4
|
<img src="https://img.shields.io/npm/l/create-harness-vibe-coding" alt="license">
|
|
5
5
|
<img src="https://img.shields.io/github/stars/zingspark/create-harness-vibe-coding?style=social" alt="stars">
|
|
@@ -7,410 +7,204 @@
|
|
|
7
7
|
|
|
8
8
|
<h1 align="center">create-harness-vibe-coding</h1>
|
|
9
9
|
<p align="center">
|
|
10
|
-
<b>
|
|
11
|
-
<sub>Idea -> Research -> PRD -> Architecture -> Plan -> Build -> Verify -> Feedback.</sub>
|
|
10
|
+
<b>A harness for your AI agent. One scaffold. Zero drift.</b><br>
|
|
12
11
|
</p>
|
|
13
12
|
|
|
14
|
-
## One Command
|
|
13
|
+
## One Command. Done.
|
|
15
14
|
|
|
16
15
|
```bash
|
|
17
16
|
npx create-harness-vibe-coding@latest my-project
|
|
18
17
|
```
|
|
19
18
|
|
|
20
|
-
|
|
19
|
+
## Your Agent Knows What to Do
|
|
21
20
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
| What You Get | Purpose |
|
|
25
|
-
|-------------|---------|
|
|
26
|
-
| `CLAUDE.md` + `Harness/README.md` | Thin root entry and dynamic doc router |
|
|
27
|
-
| `Harness/PROGRESS.md` + `Harness/tasks/` | Global task index and per-task progress capsules |
|
|
28
|
-
| `Harness/WF.md` + `/wf` | Long-task workflow: parallel explore, second-plan, build, review, verify, recover |
|
|
29
|
-
| `/wf update` | GitHub-based incremental scaffold update with checksum safety |
|
|
30
|
-
| `Harness/subagents.md` + `subagent-orchestrator` | Controller-led multi-agent orchestration with source-attributed methods |
|
|
31
|
-
| `memory-master` + `context-master` | Auto-triggered memory writing on repeated failures, and non-blocking context compression alerts |
|
|
32
|
-
| Research + PRD templates | Clarify idea, scope, non-goals, acceptance criteria |
|
|
33
|
-
| Research protocol | Route research agents, source search, and fallback tools |
|
|
34
|
-
| Built-in common agents | 11 agents: research, planning, architecture, testing, implementation, debugging, review, verification, memory, context |
|
|
35
|
-
| Harness architecture docs | Boundaries, ports, data flow, state machines |
|
|
36
|
-
| Dispatch protocol | Lightweight parallel-agent coordination without a scheduler |
|
|
37
|
-
| Extension contract | Keep stack-specific agents and skills compatible |
|
|
38
|
-
| Context-loading protocol | Inject only the right docs into each subagent |
|
|
39
|
-
| README optimizer skill | Optional README preservation, tables, and approved architecture diagrams |
|
|
40
|
-
| Skill-style loaders | `.claude/skills/*` route lifecycle, context, and build loops |
|
|
41
|
-
| Harness validator | Checks required files, agent/skill registrations, invariants |
|
|
42
|
-
| `.claude/` skeleton | Root runtime integration for Claude Code agents, skills, commands, and rules |
|
|
43
|
-
|
|
44
|
-
---
|
|
45
|
-
|
|
46
|
-
## Why This Exists
|
|
47
|
-
|
|
48
|
-
Most 0-1 AI coding projects fail before code quality matters:
|
|
49
|
-
|
|
50
|
-
| Without Harness | With This Scaffold |
|
|
51
|
-
|---|---|
|
|
52
|
-
| Idea jumps straight to code | Lifecycle forces research, PRD, and scope |
|
|
53
|
-
| Agent reads too much context | Docs router loads only the needed harness file |
|
|
54
|
-
| Subagents get vague prompts | Context-loading packs define role, boundaries, and return format |
|
|
55
|
-
| Process drift is invisible | Validator checks core harness readiness |
|
|
56
|
-
| Architecture drifts silently | Ports, data-flow, and state docs mark boundary changes |
|
|
57
|
-
| Tests come after implementation | Workflow requires failing test or manual check first |
|
|
58
|
-
| Long tasks stall after failures | `/wf` adds heartbeat, recovery loop, auto memory-master at 3 failures |
|
|
59
|
-
| Context bloats over long sessions | `context-master` gives non-blocking compression alerts at ~85% window |
|
|
60
|
-
| Scaffold rots after generation | `/wf update` pulls latest improvements from GitHub with checksum safety |
|
|
61
|
-
|
|
62
|
-
---
|
|
63
|
-
|
|
64
|
-
## How It Works
|
|
21
|
+
Already have a project? **Don't read the docs**. Paste this sentence. Your agent handles the rest.
|
|
65
22
|
|
|
66
23
|
```text
|
|
67
|
-
|
|
68
|
-
-> Claude reads Harness/SETUP.md
|
|
69
|
-
-> Harness router selects only needed harness docs
|
|
70
|
-
-> PRD/research/architecture are filled
|
|
71
|
-
-> First task capsule created at Harness/tasks/<id>/
|
|
72
|
-
-> First vertical slice is built, tested, reviewed, verified, and fed back
|
|
73
|
-
-> Validator catches missing project facts before release
|
|
74
|
-
-> /wf update pulls latest scaffold improvements from GitHub
|
|
24
|
+
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.
|
|
75
25
|
```
|
|
76
26
|
|
|
77
|
-
|
|
27
|
+
That's it. Two paths into the harness — you type `npx`, or your agent reads the sentence.
|
|
78
28
|
|
|
79
|
-
|
|
29
|
+
[README-CN.md](README-CN.md) (中文)
|
|
80
30
|
|
|
81
31
|
---
|
|
82
32
|
|
|
83
|
-
## What
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
│ ├── WF.md ← Long-task workflow and recovery loop
|
|
99
|
-
│ ├── lifecycle.md ← 0-1 product flow
|
|
100
|
-
│ ├── subagents.md ← Controller-led subagent orchestration
|
|
101
|
-
│ ├── context-loading.md ← Subagent context packs
|
|
102
|
-
│ ├── dispatch.md ← Lightweight parallel-agent protocol
|
|
103
|
-
│ ├── extension.md ← Stack-specific agent/skill contract
|
|
104
|
-
│ ├── architecture.md ← Layer rules, components, ADRs
|
|
105
|
-
│ ├── agent-workflow.md ← TDD loop, subagent roles, write sets
|
|
106
|
-
│ ├── data-flow.md ← Event lifecycle: normal + failure paths
|
|
107
|
-
│ ├── state-machines.md ← State enums, transition tables, guards
|
|
108
|
-
│ ├── domain/
|
|
109
|
-
│ │ └── ports.md ← Port contracts: pre/postconditions, errors
|
|
110
|
-
│ ├── features/
|
|
111
|
-
│ │ └── _template.md ← Feature doc template
|
|
112
|
-
│ ├── tasks/
|
|
113
|
-
│ │ ├── _template/ ← Task capsule template (copy for new tasks)
|
|
114
|
-
│ │ └── <task-id>/ ← Per-task PROGRESS.md + PLAN.md + artifacts
|
|
115
|
-
│ ├── research/
|
|
116
|
-
│ │ ├── README.md
|
|
117
|
-
│ │ ├── PRD.md
|
|
118
|
-
│ │ └── research-results.md
|
|
119
|
-
│ ├── memory/
|
|
120
|
-
│ │ ├── tool-usage-reflections.md
|
|
121
|
-
│ │ ├── user-corrections-preferences.md
|
|
122
|
-
│ │ └── agent-lessons-patterns.md
|
|
123
|
-
│ ├── workflows/ ← Optional workflow docs
|
|
124
|
-
│ └── scripts/
|
|
125
|
-
│ └── validate-harness.mjs
|
|
126
|
-
├── .claude/
|
|
127
|
-
│ ├── settings.json ← Base permissions
|
|
128
|
-
│ ├── agents/ ← 11 common agents + stack-specific
|
|
129
|
-
│ ├── skills/ ← Harness skills + wf-update + stack-specific
|
|
130
|
-
│ ├── commands/
|
|
131
|
-
│ │ ├── wf.md ← /wf — enter workflow mode
|
|
132
|
-
│ │ └── update.md ← /wf update — GitHub-based scaffold update
|
|
133
|
-
│ ├── hooks/ ← Configure automation after stack choice
|
|
134
|
-
│ └── rules/ecc/
|
|
135
|
-
│ └── common.md ← Universal coding rules
|
|
136
|
-
└── tests/ ← Your test suite goes here
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
`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.
|
|
33
|
+
## What You Get
|
|
34
|
+
|
|
35
|
+
| You get | So your agent |
|
|
36
|
+
|---------|---------------|
|
|
37
|
+
| `CLAUDE.md` + `Harness/README.md` | Starts with a router, not a novel |
|
|
38
|
+
| `Harness/tasks/` + `Harness/PROGRESS.md` | Tracks work across sessions |
|
|
39
|
+
| `/wf` workflow + heartbeat | Finishes long tasks without getting lost |
|
|
40
|
+
| `/wf update` | Pulls scaffold fixes from GitHub |
|
|
41
|
+
| `subagent-orchestrator` | Runs parallel agents without collision |
|
|
42
|
+
| `memory-master` + `context-master` | Learns from failures, compresses when full |
|
|
43
|
+
| PRD + Research templates | Asks "what" and "why" before coding |
|
|
44
|
+
| 11 built-in agents | Research, plan, architect, test, build, review, debug, verify |
|
|
45
|
+
| Architecture docs | Knows where boundaries live |
|
|
46
|
+
| Context-loading protocol | Loads only the docs each agent needs |
|
|
47
|
+
| `.claude/` skeleton | Agents, skills, commands, hooks — ready to go |
|
|
140
48
|
|
|
141
49
|
---
|
|
142
50
|
|
|
143
|
-
##
|
|
51
|
+
## Why This Exists
|
|
144
52
|
|
|
145
|
-
|
|
146
|
-
|----------|-----|
|
|
147
|
-
| Claude Code | Native `CLAUDE.md`, `.claude/settings.json`, agents, skills, hooks |
|
|
148
|
-
| Codex / Cursor / Gemini CLI | Works as docs-first process scaffold |
|
|
149
|
-
| ECC / Superpowers / toolboxes | Optional source for stack-specific agents, skills, and rules |
|
|
53
|
+
Most AI coding projects fail before anyone writes a line of bad code. The agent jumps straight to implementation, drifts from intent, forgets yesterday's decisions, and bloats its context with the whole repo.
|
|
150
54
|
|
|
151
|
-
|
|
55
|
+
| Without harness | With harness |
|
|
56
|
+
|-----------------|--------------|
|
|
57
|
+
| Idea → code. Hope. | Idea → Research → PRD → Architecture → Build → Verify |
|
|
58
|
+
| Agent reads everything | Router loads the one doc it needs |
|
|
59
|
+
| Subagent gets a vague "fix it" | Context pack: role, boundary, return format |
|
|
60
|
+
| Drift invisible until demo | Validator flags missing pieces |
|
|
61
|
+
| Long task stalls, context explodes | `/wf` heartbeat + recovery loop |
|
|
62
|
+
| Scaffold rots | `/wf update` pulls latest from GitHub |
|
|
152
63
|
|
|
153
|
-
|
|
64
|
+
---
|
|
154
65
|
|
|
155
|
-
|
|
66
|
+
## How It Works
|
|
156
67
|
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
|
|
68
|
+
```text
|
|
69
|
+
npx create-harness-vibe-coding@latest my-project
|
|
70
|
+
↓
|
|
71
|
+
Agent reads Harness/SETUP.md
|
|
72
|
+
↓
|
|
73
|
+
Router loads only what the task needs
|
|
74
|
+
↓
|
|
75
|
+
PRD → Research → Architecture → first task capsule
|
|
76
|
+
↓
|
|
77
|
+
Build → Test → Review → Verify → Feedback
|
|
78
|
+
↓
|
|
79
|
+
/wf update keeps the harness current
|
|
160
80
|
```
|
|
161
81
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
- **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.
|
|
174
|
-
|
|
175
|
-
Agent-link install intake, asked before editing:
|
|
176
|
-
|
|
177
|
-
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.
|
|
178
|
-
|
|
179
|
-
| Topic | Ask When | Default If Unanswered |
|
|
180
|
-
| --- | --- | --- |
|
|
181
|
-
| Root agent entry | `CLAUDE.md`, `AGENTS.md`, `.claude/`, or other agent entry files already exist | Preserve files; ask before merging the Harness entry contract |
|
|
182
|
-
| Harness location | `docs/` is already used for GitHub Pages, product docs, or generated docs | Use root `Harness/`; do not write harness docs into `docs/` |
|
|
183
|
-
| README ownership | root `README.md` is a public product page, package docs, or heavily customized | Preserve existing README and propose a minimal Development section |
|
|
184
|
-
| 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 |
|
|
185
|
-
| Extensions | ECC, Superpowers, custom rules, or stack-specific skills may be useful | Recommend first; install only after user approval |
|
|
186
|
-
| 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 |
|
|
187
|
-
| CI/CD | CI config exists or the project lacks a test/build gate | Document existing commands first; add CI/CD only after user approval |
|
|
188
|
-
| Verification depth | browser-visible, API, database, auth, payment, or deployment behavior is affected | Require real command evidence; require browser/API evidence when relevant |
|
|
189
|
-
| Memory/privacy | repo contains sensitive domain data, customer data, secrets, or private workflows | Enable memory index only; never record secrets or private data |
|
|
190
|
-
| Branch/worktree | project has uncommitted changes, risky migration, or parallel implementation lanes | Preserve current worktree; propose branch/worktree before broad edits |
|
|
191
|
-
| Package manager/stack | multiple package managers, monorepo apps, or unclear stack boundaries exist | Ask which workspace/app is in scope before writing |
|
|
192
|
-
|
|
193
|
-
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.
|
|
194
|
-
|
|
195
|
-
```bash
|
|
196
|
-
# Preview the write plan first. No files or directories are created.
|
|
197
|
-
npx create-harness-vibe-coding@latest my-app . -y --dry-run
|
|
198
|
-
|
|
199
|
-
# Preserve existing files and add only missing harness files.
|
|
200
|
-
npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
|
|
82
|
+
```mermaid
|
|
83
|
+
graph TD
|
|
84
|
+
A[ /wf Enter ] --> B[ Explore: 3+ parallel agents ]
|
|
85
|
+
B --> C[ Second Plan ]
|
|
86
|
+
C --> D[ Build: test → implement ]
|
|
87
|
+
D --> E[ Dual-Gate Review ]
|
|
88
|
+
E --> F{ Pass? }
|
|
89
|
+
F -->| No | G[ Debug → Fix → Loop ]
|
|
90
|
+
G --> E
|
|
91
|
+
F -->| Yes | H[ Closeout: memory + context ]
|
|
92
|
+
H --> I[ /wf update ]
|
|
201
93
|
```
|
|
202
94
|
|
|
203
|
-
|
|
95
|
+
---
|
|
204
96
|
|
|
205
|
-
|
|
206
|
-
|---------------|---------|------|
|
|
207
|
-
| `fail` | Default. Stop if a target file already exists. | Safest for existing projects; requires a follow-up decision. |
|
|
208
|
-
| `skip` | Keep existing files and create only missing files. | Existing root entries may need manual links to new `Harness/` docs or workflows. |
|
|
209
|
-
| `backup` | Rename the existing file to `<name>.harness-backup`, then write the scaffold file. | Review backups before deleting; repeated runs may need cleanup. |
|
|
210
|
-
| `overwrite` | Replace existing files with scaffold versions. | Destructive. Use only after reviewing `--dry-run` output or with explicit approval. |
|
|
97
|
+
## Usage
|
|
211
98
|
|
|
212
|
-
|
|
99
|
+
### New project
|
|
213
100
|
|
|
214
101
|
```bash
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
102
|
+
npx create-harness-vibe-coding@latest my-project
|
|
103
|
+
cd my-project
|
|
104
|
+
# Your agent reads Harness/SETUP.md. Done.
|
|
218
105
|
```
|
|
219
106
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
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`.
|
|
223
|
-
|
|
224
|
-
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`.
|
|
225
|
-
|
|
226
|
-
### Agent / CI/CD
|
|
227
|
-
|
|
228
|
-
Agents and automation can skip all prompts with `-y`:
|
|
107
|
+
### Existing project — safe merge
|
|
229
108
|
|
|
230
109
|
```bash
|
|
231
|
-
#
|
|
232
|
-
npx create-harness-vibe-coding@latest -y
|
|
233
|
-
|
|
234
|
-
# Named project, auto directory
|
|
235
|
-
npx create-harness-vibe-coding@latest my-app -y
|
|
236
|
-
|
|
237
|
-
# Named project, explicit directory
|
|
238
|
-
npx create-harness-vibe-coding@latest my-app ./dist/my-app -y
|
|
239
|
-
|
|
240
|
-
# CI-safe existing-project preview
|
|
110
|
+
# Preview first. Always.
|
|
241
111
|
npx create-harness-vibe-coding@latest my-app . -y --dry-run
|
|
242
112
|
|
|
243
|
-
#
|
|
113
|
+
# Add only what's missing. Never overwrite.
|
|
244
114
|
npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
|
|
245
115
|
```
|
|
246
116
|
|
|
247
|
-
| Flag |
|
|
248
|
-
|
|
249
|
-
| `-y
|
|
250
|
-
| `--dry-run` |
|
|
251
|
-
| `--on-conflict
|
|
252
|
-
| `--
|
|
253
|
-
| `--
|
|
254
|
-
| `--
|
|
255
|
-
| `--
|
|
256
|
-
|
|
|
117
|
+
| Flag | Does |
|
|
118
|
+
|------|------|
|
|
119
|
+
| `-y` | Skip prompts |
|
|
120
|
+
| `--dry-run` | Preview — no writes |
|
|
121
|
+
| `--on-conflict skip` | Keep your files, add only new ones |
|
|
122
|
+
| `--on-conflict backup` | Rename existing → write new |
|
|
123
|
+
| `--on-conflict overwrite` | Replace (destructive) |
|
|
124
|
+
| `--list-options` | Show optional workflows |
|
|
125
|
+
| `--with <ids>` | Add workflow by id |
|
|
126
|
+
| `--preset <name>` | Add `web-app` or `fullstack` preset |
|
|
257
127
|
|
|
258
|
-
|
|
259
|
-
> Agents should always pass `-y` to avoid hanging on interactive prompts.
|
|
260
|
-
> If the agent needs to discover the CLI surface first, run with `--help` and `--list-options`.
|
|
261
|
-
|
|
262
|
-
### Optional Workflows
|
|
263
|
-
|
|
264
|
-
Optional workflows are local template assets selected explicitly at generation time. They do not install package dependencies or fetch a remote marketplace.
|
|
128
|
+
### Optional workflows
|
|
265
129
|
|
|
266
130
|
```bash
|
|
267
|
-
|
|
268
|
-
npx create-harness-vibe-coding@latest --list-options
|
|
269
|
-
|
|
270
|
-
# Add individual workflows
|
|
271
|
-
npx create-harness-vibe-coding@latest my-app -y --with browser-e2e,ts-react-frontend
|
|
272
|
-
|
|
273
|
-
# Add a preset for common web app work
|
|
131
|
+
npx create-harness-vibe-coding@latest my-app -y --with browser-e2e
|
|
274
132
|
npx create-harness-vibe-coding@latest my-app -y --preset web-app
|
|
275
|
-
|
|
276
|
-
# Add a broader frontend/backend/PR-review preset
|
|
277
|
-
npx create-harness-vibe-coding@latest my-app -y --preset fullstack
|
|
278
|
-
|
|
279
|
-
# Trim a preset without restating every selected workflow
|
|
280
|
-
npx create-harness-vibe-coding@latest my-app -y --preset fullstack --without github-pr-review
|
|
281
133
|
```
|
|
282
134
|
|
|
283
|
-
|
|
135
|
+
| Workflow | For |
|
|
136
|
+
|----------|-----|
|
|
137
|
+
| `browser-e2e` | Screenshots, traces, smoke tests |
|
|
138
|
+
| `ui-ux-review` | Responsive, a11y, polish |
|
|
139
|
+
| `ts-react-frontend` | TypeScript + React + Vite |
|
|
140
|
+
| `python-backend` | FastAPI, pytest |
|
|
141
|
+
| `github-pr-review` | PR diff review + CI evidence |
|
|
284
142
|
|
|
285
|
-
|
|
286
|
-
|----------|----------|
|
|
287
|
-
| `browser-e2e` | Browser smoke tests, screenshots, traces, and UI evidence. |
|
|
288
|
-
| `ui-ux-review` | Screenshot-driven responsive, accessibility, and polish review. |
|
|
289
|
-
| `github-pr-review` | PR diff, checks, review findings, and CI evidence. |
|
|
290
|
-
| `python-backend` | Python API/backend work with unittest or pytest verification. |
|
|
291
|
-
| `ts-react-frontend` | TypeScript React work with typecheck, component tests, build, and browser smoke. |
|
|
143
|
+
### Agent-link intake
|
|
292
144
|
|
|
293
|
-
|
|
145
|
+
When your agent reads the one-sentence prompt above, it asks **at most 3 questions** before touching files:
|
|
294
146
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
| `fullstack` | `ts-react-frontend`, `python-backend`, `browser-e2e`, `github-pr-review` |
|
|
147
|
+
- Is `CLAUDE.md` or `AGENTS.md` already there? → merge, don't replace
|
|
148
|
+
- Is `docs/` used for product docs? → puts harness in `Harness/`, not `docs/`
|
|
149
|
+
- What stack? → installs matching optional workflows
|
|
299
150
|
|
|
300
|
-
|
|
151
|
+
If a file already exists, the agent asks first. The default is always **preserve**.
|
|
301
152
|
|
|
302
|
-
|
|
153
|
+
### After scaffolding
|
|
303
154
|
|
|
304
155
|
```text
|
|
305
|
-
/
|
|
306
|
-
Intake (95% confidence gate)
|
|
307
|
-
-> 3+ parallel read-only subagents (planner + architect + researcher)
|
|
308
|
-
-> Synthesis + second plan → writes to Harness/tasks/<id>/PLAN.md
|
|
309
|
-
-> test-writer → implementer → reviewers → verifier
|
|
310
|
-
-> Failed? debugger → review → verify → loop
|
|
311
|
-
-> Closeout: context-master + memory-master consolidate knowledge
|
|
312
|
-
```
|
|
313
|
-
|
|
314
|
-
| Phase | What happens | Heartbeat |
|
|
315
|
-
|-------|-------------|-----------|
|
|
316
|
-
| Intake | State goal, confidence, risks, write boundaries | Update before dispatching |
|
|
317
|
-
| Explore | 3-5 parallel read-only subagents | After each subagent return |
|
|
318
|
-
| Second Plan | Synthesize findings into `tasks/<id>/PLAN.md` | After plan written |
|
|
319
|
-
| Build | `test-writer` → `implementer` serial lane | Before/after long commands |
|
|
320
|
-
| Review | Spec review, then code-quality review | After each review gate |
|
|
321
|
-
| Verify | Run declared checks, record evidence | After each verification |
|
|
322
|
-
| Recover | `debugger` → fix → review → verify → loop | After each failure |
|
|
323
|
-
| Close | `context-master` extraction → `memory-master` consolidation → archive | Final heartbeat |
|
|
324
|
-
|
|
325
|
-
WF mode also auto-dispatches:
|
|
326
|
-
- **`memory-master`** at 3 same-class failures (records pattern before asking user)
|
|
327
|
-
- **`context-master`** at ~85% context window (non-blocking compression suggestion)
|
|
328
|
-
- **`context-master` + `memory-master`** at closeout (extract + persist session knowledge)
|
|
329
|
-
|
|
330
|
-
```bash
|
|
331
|
-
# Tell the agent to use WF mode
|
|
156
|
+
"Read Harness/SETUP.md. Bootstrap this project."
|
|
332
157
|
"Use /wf for this migration."
|
|
333
|
-
"
|
|
334
|
-
"wf mode — help me refactor the auth layer."
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
### WF Update
|
|
338
|
-
|
|
339
|
-
Check for scaffold updates from GitHub and apply them incrementally with checksum safety.
|
|
340
|
-
|
|
341
|
-
```bash
|
|
342
|
-
# Check available updates without applying
|
|
343
|
-
/wf update --check
|
|
344
|
-
|
|
345
|
-
# Full update with safe incremental apply
|
|
346
|
-
/wf update
|
|
158
|
+
"/wf update — pull latest harness improvements."
|
|
347
159
|
```
|
|
348
160
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
1. Reads `Harness/.harness-version` — gets local version + 54 file SHA-256 checksums
|
|
352
|
-
2. Fetches latest template files from `raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/`
|
|
353
|
-
3. Compares checksums file-by-file against stored values
|
|
354
|
-
4. Classifies each file into three tiers:
|
|
355
|
-
|
|
356
|
-
| Tier | Policy | Examples |
|
|
357
|
-
|------|--------|----------|
|
|
358
|
-
| **SAFE** | Overwrite if local checksum matches stored (unmodified) | `Harness/WF.md`, `.claude/agents/*.md`, all skills |
|
|
359
|
-
| **PRESERVE** | Never touch | `Harness/PROGRESS.md`, `Harness/tasks/**`, `Harness/memory/**`, root `README.md` |
|
|
360
|
-
| **MERGE** | Overwrite if unmodified; report and skip if user-modified | `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md` |
|
|
361
|
-
|
|
362
|
-
5. Reports: `updated/N, merge/N, created/N, skipped/N`
|
|
363
|
-
6. Updates `.harness-version` checksums after applying
|
|
364
|
-
|
|
365
|
-
**Auto-check on session start:** When `Harness/.harness-version` has `autoCheck: true`, the agent runs a non-blocking `update --check` (10s timeout). If an update is available, it notifies without blocking the current task. Set `autoCheck: false` to disable.
|
|
366
|
-
|
|
367
|
-
**Offline behavior:** If GitHub is unreachable, the update check exits cleanly. All other harness features work without network.
|
|
368
|
-
|
|
369
|
-
### Verification
|
|
161
|
+
### Verify
|
|
370
162
|
|
|
371
163
|
```bash
|
|
372
|
-
# Run repository tests
|
|
373
164
|
npm test
|
|
374
|
-
|
|
375
|
-
# Confirm optional workflow catalog output
|
|
376
|
-
node bin/create-harness-vibe-coding.js --list-options
|
|
377
|
-
|
|
378
|
-
# After generating a project, validate the harness from that project root
|
|
379
165
|
node Harness/scripts/validate-harness.mjs
|
|
380
166
|
```
|
|
381
167
|
|
|
382
|
-
|
|
168
|
+
---
|
|
383
169
|
|
|
384
|
-
|
|
170
|
+
## Inside
|
|
385
171
|
|
|
386
172
|
```
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
173
|
+
my-project/
|
|
174
|
+
├── CLAUDE.md ← Agent entry
|
|
175
|
+
├── AGENTS.md ← Agent registry
|
|
176
|
+
├── .gitignore
|
|
177
|
+
├── Harness/
|
|
178
|
+
│ ├── README.md ← Doc router
|
|
179
|
+
│ ├── SETUP.md ← Bootstrap guide (delete after init)
|
|
180
|
+
│ ├── MEMORY.md ← Resource index
|
|
181
|
+
│ ├── PROGRESS.md ← Task tracker
|
|
182
|
+
│ ├── WF.md / WF-MAX.md ← Workflow modes
|
|
183
|
+
│ ├── tasks/ ← Per-task capsules
|
|
184
|
+
│ ├── research/ ← PRD + research templates
|
|
185
|
+
│ ├── memory/ ← Durable self-learning
|
|
186
|
+
│ └── scripts/ ← Validator
|
|
187
|
+
├── .claude/
|
|
188
|
+
│ ├── agents/ ← 11 common agents
|
|
189
|
+
│ ├── skills/ ← Harness loaders
|
|
190
|
+
│ ├── commands/ ← /wf, /wf update
|
|
191
|
+
│ └── rules/ ← Universal coding rules
|
|
192
|
+
└── tests/
|
|
393
193
|
```
|
|
394
194
|
|
|
195
|
+
`Harness/` holds all harness docs. `.claude/` stays at root — that's where Claude Code discovers agents, skills, and commands.
|
|
196
|
+
|
|
395
197
|
---
|
|
396
198
|
|
|
397
199
|
## Footprint
|
|
398
200
|
|
|
399
|
-
|
|
|
400
|
-
|
|
401
|
-
| Runtime
|
|
201
|
+
| | |
|
|
202
|
+
|---|---|
|
|
203
|
+
| Runtime | None |
|
|
402
204
|
| Dependencies | 2 (`@clack/prompts`, `picocolors`) |
|
|
403
|
-
| Node
|
|
404
|
-
| Generated code |
|
|
205
|
+
| Node | ≥ 18 |
|
|
206
|
+
| Generated code | None until you pick a stack |
|
|
405
207
|
|
|
406
208
|
---
|
|
407
209
|
|
|
408
|
-
## Contributing
|
|
409
|
-
|
|
410
|
-
PRs welcome. The template docs live in `templates/common/` — edit them to change what gets scaffolded.
|
|
411
|
-
|
|
412
|
-
---
|
|
413
|
-
|
|
414
|
-
## License
|
|
415
|
-
|
|
416
210
|
MIT © [zingspark](https://github.com/zingspark)
|
package/package.json
CHANGED