Harness

cow-harness/ 是可迁移的 Agent Harness：它提供任务路由、过程产物、验证门禁、入口模板、工具适配和初始化 runbook，让 AI 先理解项目，再进入设计、编码和验证。

它既可用于单项目，也可用于由前端、后端、客户端、测试或工具组成的全栈多项目组合。Harness 是通用依赖；每个业务项目独立保留自己的画像和领域规则，组合根目录只保留模块路由信息。

核心能力

• superpowers 提供需求理解、计划、调试、TDD 与验证方法。
• oh-my-codex / omx 提供运行时编排。
• skills/domain-init/ 以 Git submodule 固定领域初始化 skill；init 会要求 Agent 实际读取并按其 Phase 1–4 工作流执行，而不是只输出安装说明。
• 用户指定 skill 时，默认按“默认 route + 用户指定 skill”合并执行；只有用户明确排除默认 route 时才跳过。

目录边界

目标业务项目/
├── cow-harness/                 # Git submodule：通用 Harness 源码
│   └── skills/domain-init/      # Git submodule：领域初始化 skill
├── .ai-harness/                 # 当前项目的持久化画像
│   ├── project.profile.md
│   ├── context-map.md
│   ├── verification.md
│   └── domain-init-report.md
├── .ai-runtime-artifacts/       # 当前项目的需求、计划、评审与验证记录
└── .agents/                     # 当前项目的 Codex rules、skills、agents

• cow-harness/、模板和检查脚本属于 Harness 源码，不承载业务项目生成内容。
• .ai-harness/、.ai-runtime-artifacts/ 和平台目录资产属于当前业务项目，应随该项目提交。
• domain-init 生成的 rules、skills 和 agents 写入当前项目选择的平台目录；不会写进 Harness 子模块。

初始化前准备

推荐把 Harness 作为 submodule 加入每个业务项目：

git submodule add [email protected]:WxqKb/cow-harness.git cow-harness
git submodule update --init --recursive

--recursive 会同时初始化 cow-harness/skills/domain-init。已有项目只需在添加或更新 Harness 后运行同一条 git submodule update --init --recursive。

单项目接入

把下面这段话交给 AI：

请先读取 cow-harness/README.md、cow-harness/init/bootstrap.prompt.md 和 cow-harness/skills/domain-init/SKILL.md。
这是一个新项目刚接入 Agent Harness，请按 Harness 初始化流程处理：
1. 从 cow-harness/entrypoints/ 投影根目录 AI 入口文件。
2. 从 cow-harness/adapters/ 投影工具适配目录。
3. 创建 .ai-harness/ 和 .ai-runtime-artifacts/ 及其子目录。
4. 如需安装或检查 AI runtime，请先说明会修改哪些本机环境，然后由你执行 cow-harness/scripts/install-ai-skills.sh。
5. 按 domain-init 的 Phase 1–4 识别领域、确认范围、采样代码、展示草案并在用户 review 后写入。
6. 生成或更新 .ai-harness/project.profile.md、.ai-harness/context-map.md、.ai-harness/verification.md 和 .ai-harness/domain-init-report.md。
7. 运行 cow-harness/scripts/harness-check.sh，并汇总领域、生成文件、推断项、需要人工确认的项和验证结果。

全栈多项目接入

全栈不是在根目录生成一份覆盖所有端的规则，而是把 APP、后端、网页端等独立项目组合起来，再让 AI 分别读懂它们。我们用 Git submodule 固定业务子项目的仓库来源、目录位置和当前协作版本；各子项目仍保有自己的分支策略、提交历史和项目规范。

一个完整的组合根仓库通常长这样：

product-composition/
├── cow-harness/              # 根目录的全栈入口与任务路由（Git submodule）
├── .ai-harness/
│   └── workspace-map.md      # 只保存业务模块路由事实
├── apps/mobile/              # APP 子项目（Git submodule）
├── services/backend/         # 后端子项目（Git submodule）
└── apps/web/                 # 网页端子项目（Git submodule）

1. 先建立或同步组合根仓库

如果组合根仓库还没有业务子项目，先把每个业务仓库和根目录 Harness 加入为 submodule：

git submodule add  apps/mobile
git submodule add  services/backend
git submodule add  apps/web
git submodule add [email protected]:WxqKb/cow-harness.git cow-harness
git submodule update --init --recursive

如果组合仓库已经维护完成，只需同步它锁定的版本：

git submodule update --init --recursive
git submodule status --recursive

git submodule status --recursive 是接入前的第一道检查。它让 AI 和人都看到当前组合实际有哪些子项目、每个项目锁定在哪个提交，以及嵌套的 Harness 是否已初始化。

2. 在每个业务子项目接入 Harness

根目录的 cow-harness/ 负责全栈任务入口和子项目路由；真正的项目画像、领域规则和日常过程产物，则属于各自的业务子项目。因此，每个需要由 AI 长期维护的业务子项目都要独立接入 Harness：

cd apps/mobile
git submodule add [email protected]:WxqKb/cow-harness.git cow-harness
git submodule update --init --recursive

对 services/backend、apps/web 等需要初始化的业务项目重复同样的操作，并在各自的 Git 仓库中提交 .gitmodules 和 cow-harness/ 引用。不要把业务子项目的规则或过程产物写进组合根仓库，也不要把 cow-harness 或第三方依赖误当成需要初始化的业务模块。

--recursive 不能省：cow-harness 内还嵌套了 skills/domain-init。少了它，Harness 只有外层流程，没有真正负责读取项目、提炼规则的 skill。

3. 启动全栈初始化

回到组合根仓库，把下面这段话交给 AI：

请先读取 cow-harness/README.md、cow-harness/init/fullstack-bootstrap.prompt.md
和 cow-harness/skills/domain-init/SKILL.md。

这是一个由多个业务子项目组成的全栈项目。请先运行
git submodule status --recursive，区分业务子项目、Harness 和第三方依赖；
展示候选业务子项目并等待我选择。只初始化我确认的子项目，
不要在组合根目录生成混合的领域规则，也不要自动改写未选择的子项目。

初始化会先创建或更新组合根目录的 .ai-harness/workspace-map.md，记录已确认的业务子项目路径、领域和初始化状态。随后它才会逐个进入选中的子项目，执行领域识别、代码采样、规则草案和人工确认。

4. 确认产物与提交边界

组合根目录只提交子模块版本引用和 workspace-map.md；每个已选子项目独立提交自己的 Harness 接入和项目资产：

services/backend/
├── cow-harness/
├── .ai-harness/
│   ├── project.profile.md
│   ├── context-map.md
│   ├── verification.md
│   └── domain-init-report.md
├── .agents/                   # 或当前项目选择的平台目录
└── .ai-runtime-artifacts/

.ai-harness/ 是项目画像，.agents/ 是项目实际加载的 rules、skills 和 agents，.ai-runtime-artifacts/ 保存计划、验证和决策记录。它们都应跟随所属业务子项目的 Git 历史演进；workspace-map.md 只负责把日常任务路由到正确的子项目，不替代任何子项目的领域规则。

全栈日常任务入口

从组合根目录收到一个日常任务时，先读取 cow-harness/init/fullstack-task-routing.prompt.md。它按 .ai-harness/workspace-map.md 定位业务子项目：唯一匹配时说明选择依据并进入该项目；目标不明确时列出候选项目，让用户选择。确定目标前，不读取或写入任何子项目的任务产物。

进入已选子项目后，再按下方读取顺序加载该项目自己的 .ai-harness/ 和 cow-harness/core/。计划、验证记录、平台资产和 Git 提交始终归这个子项目所有。

任务读取顺序

1. AGENTS.md
2. cow-harness/core/harness.md
3. .ai-harness/project.profile.md
4. .ai-harness/context-map.md
5. cow-harness/core/routing.md
6. cow-harness/core/artifacts.md
7. .ai-harness/verification.md
8. cow-harness/core/verification.md
9. cow-harness/core/runbooks.md
10. 与任务相关的项目级 skills，例如 cow-harness/skills/domain-init/SKILL.md

源码结构

cow-harness/
├── core/                      # 通用 Harness 规则
├── init/                      # 单项目与全栈多项目初始化 prompts、模板
├── entrypoints/               # 根目录 AI 入口文件模板
├── adapters/                  # Claude、Codex、Cursor 适配说明与模板
├── skills/domain-init/        # 固定版本的上游领域初始化 skill
├── scripts/                   # 安装、handoff 与完整性检查脚本
├── artifact-templates/        # 过程产物模板
└── tests/                     # Harness 自身回归测试