# cow-harness

**Repository Path**: jeepb/cow-harness

## Basic Information

- **Project Name**: cow-harness
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-06
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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 时才跳过。

## 目录边界

```text
目标业务项目/
├── 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 加入每个业务项目：

```bash
git submodule add git@github.com:WxqKb/cow-harness.git cow-harness
git submodule update --init --recursive
```

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

## 单项目接入

把下面这段话交给 AI：

```text
请先读取 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 固定业务子项目的仓库来源、目录位置和当前协作版本；各子项目仍保有自己的分支策略、提交历史和项目规范。

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

```text
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：

```bash
git submodule add <mobile-repo-url> apps/mobile
git submodule add <backend-repo-url> services/backend
git submodule add <web-repo-url> apps/web
git submodule add git@github.com:WxqKb/cow-harness.git cow-harness
git submodule update --init --recursive
```

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

```bash
git submodule update --init --recursive
git submodule status --recursive
```

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

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

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

```bash
cd apps/mobile
git submodule add git@github.com: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：

```text
请先读取 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 接入和项目资产：

```text
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`

## 源码结构

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