create-harness-vibe-coding 0.7.2 → 0.8.1

package/README-CN.md

@@ -1,212 +1,160 @@
-<p align="center">
-  <img src="https://img.shields.io/npm/v/create-harness-vibe-coding?color=blue" alt="npm">
-  <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>
+# create-harness-vibe-coding
 
-<h1 align="center">create-harness-vibe-coding</h1>
-<p align="center">
-  <b>给你的 AI Agent 一个脚手架。一条命令，告别漂移。</b>
-</p>
+给 AI coding agent 用的 0-1 产品脚手架。核心目标：让 agent 先读路由、先确认事实、再写代码。
 
-## 一条命令。搞定。
+English README: [README.md](README.md)
+
+## 一条命令
 
 ```bash
 npx create-harness-vibe-coding@latest my-project
 ```
 
-## 一句话交给你的 Agent
+## 一句话交给 Agent
 
-已有项目？**不用读文档**。把这句话贴给它。Agent 知道该做什么。
+已有项目时，不要让 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。
+请完整阅读并严格遵循 https://github.com/zingspark/create-harness-vibe-coding，为当前项目配置 create-harness-vibe-coding。
 ```
 
-就两条路：
-- **你来**：敲上面那行 `npx`
-- **交给 Agent**：贴上面那句话
+复杂规则不塞进这句话里。README 和生成后的 `Harness/SETUP.md` 才是安装、升级、合并和可选能力选择的准则。
 
-[English README](README.md)
+## 你会得到什么
 
----
+| 文件/能力 | 作用 |
+|---|---|
+| `CLAUDE.md` + `AGENTS.md` | 根目录 agent 入口 |
+| `Harness/README.md` | Harness 路由器 |
+| `Harness/tasks/` + `Harness/PROGRESS.md` | 跨会话任务状态 |
+| `.claude/skills/` | Claude Code workflow skill 入口 |
+| `.agents/skills/` | Codex repo skill 入口 |
+| `.codex/` | Codex hooks/config |
+| `/wf` / `$wf` | 长任务 workflow |
+| `/wf-max` / `$wf-max` | 最大并行 workflow |
+| `/wf-review` / `$wf-review` | 交叉审查 workflow |
+| `Harness/scripts/validate-harness.mjs` | 结构校验 |
 
-## 你能得到什么
+`Harness/` 承载所有 Harness 文档。不要把 Harness 文件放进 `docs/`。
 
-| 得到 | 效果 |
-|------|------|
-| `CLAUDE.md` + `Harness/README.md` | Agent 从路由器开始，不是读长篇大论 |
-| `Harness/tasks/` + `Harness/PROGRESS.md` | 跨会话追踪任务进度 |
-| `/wf` 工作流 + 心跳 | 长任务不迷路，失败自动恢复 |
-| `/wf update` | 从 GitHub 拉取脚手架最新改进 |
-| `subagent-orchestrator` | 并行 Agent 不打架 |
-| `memory-master` + `context-master` | 从失败中学习，上下文快满时压缩 |
-| PRD + 调研模板 | 先问"做什么""为什么"，再写代码 |
-| 11 个内置 Agent | 调研、规划、架构、测试、构建、审查、调试、验证 |
-| 架构文档 | 知道边界在哪里 |
-| 上下文加载协议 | 每个子 Agent 只读它需要的文档 |
-| `.claude/` 骨架 | Agent、Skill、命令、钩子——开箱即用 |
+Claude Code 和 Codex 共用同一套核心 Harness 文档，但发现入口不同：
 
----
+- Claude Code：`.claude/skills/<name>/SKILL.md`，通常用 `/wf` 调用。
+- Codex：`.agents/skills/<name>/SKILL.md`，通常用 `$wf` 或 `/skills` 调用。
+- `.codex/` 只放 Codex 配置和 hooks；不要再使用根目录 `commands/*.toml` 伪装 Codex slash command。
 
-## 为什么需要它
+## 安装或升级路径
 
-太多 AI 编程项目在代码写烂之前就死了。Agent 跳过思考直接写代码，忘记昨天的决策，上下文塞满整个仓库。
+写文件前，agent 必须先判断当前项目属于哪一种：
 
-| 没有脚手架 | 有了它 |
-|------------|--------|
-| 想法 → 代码。赌一把。 | 想法 → 调研 → PRD → 架构 → 构建 → 验证 |
-| Agent 读完整个仓库 | 路由器只加载需要的那份文档 |
-| 子 Agent 收到一句模糊的"修一下" | 上下文包：角色、边界、返回格式 |
-| 漂移只到演示时才暴露 | 验证器标记缺失项 |
-| 长任务卡死，上下文爆炸 | `/wf` 心跳 + 恢复循环 |
-| 脚手架腐烂 | `/wf update` 从 GitHub 拉最新版 |
+| 项目状态 | 必须怎么做 |
+|---|---|
+| 空项目或新项目 | 运行脚手架，然后遵循 `Harness/SETUP.md` 做 0-1 bootstrap |
+| 已有项目，没有 `Harness/` | 先扫描项目事实，先 `--dry-run`，保留现有文件，只合并缺失的 Harness 指南 |
+| 老项目或老架构迁移 | 现有代码和文档是事实来源，先 dry-run，再用 `Harness/SETUP.md` 从事实中补 PRD、研究、架构和任务计划 |
+| 已经有 `Harness/` | 不要把 `npx` 当更新器；先问用户是运行 `/wf-update` / `$wf-update` / `node Harness/scripts/wf-update-check.mjs`，保持不动，还是批准后移除重装 |
 
----
+根目录扫描必须包括：顶层文件、`CLAUDE.md`、`AGENTS.md`、`.claude/`、`.agents/`、`.codex/`、`Harness/`、package 文件、CI 文件、应用入口、测试/构建命令、已有文档、已经安装的 skills/plugins/rules。推荐可选能力前，必须先排除已经安装的能力，避免重复推荐。
 
-## 怎么工作的
+## 已有项目安全合并
 
-```text
-npx create-harness-vibe-coding@latest my-project
-    ↓
-Agent 读 Harness/SETUP.md
-    ↓
-路由器只加载任务需要的文档
-    ↓
-PRD → 调研 → 架构 → 第一个任务胶囊
-    ↓
-构建 → 测试 → 审查 → 验证 → 反馈
-    ↓
-/wf update 保持脚手架最新
-```
+```bash
+# 先预览，不写文件
+npx create-harness-vibe-coding@latest my-app . -y --dry-run
 
-```mermaid
-graph TD
-    A[ /wf 进入 ] --> B[ 探索: 3+ 并行 Agent ]
-    B --> C[ 二阶段计划 ]
-    C --> D[ 构建: 测试 → 实现 ]
-    D --> E[ 双门禁审查 ]
-    E --> F{ 通过? }
-    F -->| 否 | G[ 调试 → 修复 → 循环 ]
-    G --> E
-    F -->| 是 | H[ 收尾: 记忆 + 上下文 ]
-    H --> I[ /wf update ]
+# 只补缺失文件，不覆盖已有文件
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
 ```
 
----
-
-## 怎么用
-
-### 新项目
+`npx` 是安装和安全补缺入口，不是已安装 Harness 的同步更新器。项目里已经有 `Harness/` 后，Claude Code 用 `/wf-update`，Codex 用 `$wf-update`，或者直接运行：
 
 ```bash
-npx create-harness-vibe-coding@latest my-project
-cd my-project
-# Agent 读 Harness/SETUP.md。搞定。
+node Harness/scripts/wf-update-check.mjs
 ```
 
-### 已有项目——安全合并
-
-```bash
-# 先预览。永远先预览。
-npx create-harness-vibe-coding@latest my-app . -y --dry-run
+原因很直接：`CLAUDE.md`、`AGENTS.md`、`.claude/`、`.agents/`、`.codex/` 和用户改过的 Harness 文档都需要 agent 带着上下文做合并决策。
 
-# 只补缺失。绝不覆盖已有文件。
-npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
-```
-
-| 参数 | 作用 |
-|------|------|
-| `-y` | 跳过所有提示 |
-| `--dry-run` | 预览——不写任何文件 |
-| `--on-conflict skip` | 保留你的文件，只创建新的 |
-| `--on-conflict backup` | 备份已有 → 写入新的 |
-| `--on-conflict overwrite` | 直接覆盖（谨慎） |
-| `--list-options` | 列出可选工作流 |
-| `--with <ids>` | 按 id 添加工作流 |
-| `--preset <name>` | 添加 `web-app` 或 `fullstack` 预设 |
-
-### 可选工作流
+## 可选能力
 
 ```bash
 npx create-harness-vibe-coding@latest my-app -y --with browser-e2e
 npx create-harness-vibe-coding@latest my-app -y --preset web-app
+npx create-harness-vibe-coding@latest my-app -y --recommend superpowers,codegraph
 ```
 
-| 工作流 | 场景 |
-|--------|------|
-| `browser-e2e` | 截图、链路追踪、冒烟测试 |
-| `ui-ux-review` | 响应式、无障碍、视觉润色 |
-| `ts-react-frontend` | TypeScript + React + Vite |
-| `python-backend` | FastAPI、pytest |
-| `github-pr-review` | PR diff 审查 + CI 证据 |
+| 参数 | 作用 |
+|---|---|
+| `--with <ids>` | 安装本地 workflow |
+| `--preset <name>` | 安装预设，如 `web-app`、`fullstack` |
+| `--without <ids>` | 从预设中排除 workflow |
+| `--recommend <ids>` | 记录外部能力建议，不自动安装 |
+| `--list-options` | 查看本地 workflow 和外部建议 |
 
-### Agent 安装前置问题
+本地 workflow：`browser-e2e`、`ui-ux-review`、`ts-react-frontend`、`python-backend`、`github-pr-review`。
 
-当你的 Agent 读到上面那句"一句话"后，它会在动文件前**最多问 3 个问题**：
+外部建议只写入 `Harness/SETUP.md`，不会自动安装第三方技能：
 
-- 已经有 `CLAUDE.md` 或 `AGENTS.md`？→ 只合并，不替换
-- `docs/` 已被产品文档占用？→ 把脚手架放 `Harness/` 目录
-- 什么技术栈？→ 安装匹配的可选工作流
+| 建议 | 用途 | 链接 |
+|---|---|---|
+| `superpowers` | 社区 skill registry 和 agent workflow | <https://github.com/obra/Superpowers> |
+| `caveman` | 简洁低 token 的 agent 行为和记忆压缩 | <https://github.com/JuliusBrussee/caveman> |
+| `agent-research` | 文献、产品、依赖和生态研究类 agent skills | <https://github.com/lingzhi227/agent-research-skills> |
+| `codegraph` | 代码图谱或仓库地图工具 | <https://github.com/colbymchenry/codegraph> |
 
-文件已存在就**先问再动**。默认永远**保留已有**。
+这些只是给用户 agent 自行评估的 GitHub 链接。脚手架不维护第三方安装步骤，只在确认项目尚未安装同类能力后记录用户选择。
 
-### 脚手架完成后
+不加 `-y` 时，CLI 会提供 checkbox/multiselect 选择。
 
-```text
-"读 Harness/SETUP.md。把这个项目引导起来。"
-"用 /wf 处理这个长迁移。"
-"/wf update — 拉取最新脚手架改进。"
-```
+## Agent-link 安装前置问题
+
+Agent 必须先扫描根目录，再最多问 3 个阻塞问题。扫描要覆盖：
+
+- `CLAUDE.md`、`AGENTS.md`
+- `.claude/`、`.agents/`、`.codex/`
+- `Harness/`
+- `README.md`
+- package 文件、CI 文件、已有文档目录、应用入口、测试/构建命令
+- 已安装的 skills/plugins/rules
+
+只在影响写入时提问：
+
+- 已有 `CLAUDE.md` 或 `AGENTS.md`：合并缺失 Harness 指南、保持不动，还是跳过？
+- 已有 `Harness/`：走 `/wf-update` / `$wf-update`、dry-run 补缺、保持不动，还是批准后移除重装？
+- 排除已安装能力后，还要启用哪些本地 workflow，或只记录哪些外部 GitHub 推荐链接？
+
+默认策略：保留已有文件，只补缺失内容。
 
-### 验证
+## 验证
 
 ```bash
 npm test
 node Harness/scripts/validate-harness.mjs
 ```
 
----
+## 项目结构
 
-## 文件结构
-
-```
+```text
 my-project/
-├── CLAUDE.md                  ← Agent 入口
-├── AGENTS.md                  ← Agent 注册表
-├── .gitignore
+├── CLAUDE.md
+├── AGENTS.md
 ├── Harness/
-│   ├── README.md              ← 文档路由器
-│   ├── SETUP.md               ← 引导指南（初始化后可删除）
-│   ├── MEMORY.md              ← 资源索引
-│   ├── PROGRESS.md            ← 任务追踪
-│   ├── WF.md / WF-MAX.md      ← 工作流模式
-│   ├── tasks/                 ← 每任务胶囊
-│   ├── research/              ← PRD + 调研模板
-│   ├── memory/                ← 持久自学习
-│   └── scripts/               ← 验证器
+│   ├── README.md
+│   ├── SETUP.md
+│   ├── MEMORY.md
+│   ├── PROGRESS.md
+│   ├── WF.md
+│   ├── tasks/
+│   ├── research/
+│   ├── workflows/
+│   └── scripts/
 ├── .claude/
-│   ├── agents/               ← 11 个通用 Agent
-│   ├── skills/               ← Harness 加载器
-│   ├── commands/             ← /wf、/wf update
-│   └── rules/                ← 通用编码规则
+│   ├── agents/
+│   ├── skills/
+│   └── rules/
+├── .agents/
+│   └── skills/
+├── .codex/
 └── tests/
 ```
 
-`Harness/` 放所有脚手架文档。`.claude/` 留在根目录——Claude Code 在这里发现 Agent、Skill 和命令。
-
----
-
-## 足迹
-
-| | |
-|---|---|
-| 运行时 | 无 |
-| 依赖 | 2（`@clack/prompts`、`picocolors`） |
-| Node | ≥ 18 |
-| 生成代码 | 无——直到你选定技术栈 |
-
----
-
-MIT © [zingspark](https://github.com/zingspark)
+MIT - [zingspark](https://github.com/zingspark)