Cross-tool AI coding workflow plugin for Cursor and related agents.
在出现分阶段推进、带证据的门禁、或需在单一协调者下做失败恢复（retry→replan→rollback）时使用；亦适用于已存在/将写入的 .ai/tasks/*/task.yaml、符合命名规范的 feat|bug|… 前缀 task_id、或用户要求继续/对齐任务快照。加载后须再 Read workflow-protocol 与/或 task-protocol 再行动。
<SUBAGENT-STOP>
若你作为子代理仅被委派执行某个具体步骤，且主会话已指定由 coordinator 持有 `task_id` 与阶段状态：除非主会话明确要求你「同时承担编排」，否则不要套用本技能的完整生命周期；只完成委派步骤，并把可复核证据回传给 coordinator。
</SUBAGENT-STOP>
<EXTREMELY-IMPORTANT>
下列情形**任一**成立，即视为本技能适用；不确定时按「适用」处理（多读协议的成本低于误判跳过）：
- 需要阶段、门禁、可复核证据，或固定顺序的恢复策略。
- 仓库中已有或即将写入 `.ai/tasks/**/task.yaml`，或对话中反复出现符合本文「task_id 命名规范」的 `task_id`。
适用则**必须**按本文与所引用协议的约束执行编排；不得用「任务小」「先改再说」等理由绕过校验与证据。
</EXTREMELY-IMPORTANT>
## 1. 与其他技能的协作顺序
与 **using-superpowers** 及多技能并存时的总原则一致：
1. **用户显式约束**（含 `AGENTS.md`、当场豁免）——最高。
2. **流程类 superpowers 技能**（如 brainstorming、systematic-debugging）——决定「先想清楚 / 先怎么查」时，**先于**本技能的具体阶段执行；在其产出满足入口后，再回到本技能的 workflow / 快照推进。
3. **本技能 + `workflow-protocol.md` +（涉及 `task.yaml` 时）`task-protocol.md`**——覆盖与「分阶段 + 门禁 + 快照」相关的默认即兴编排。
4. **模型默认行为**——最低。
在 **Cursor** 中：通过 **Read** 加载本文件与协议全文；加载后发现不适用可退出本框架，但若仍存在编排/快照需求，应重新评估是否适用。
## 2. 适用范围（触发器）
命中 **任一** 即启用本技能：
| 类别 | 触发条件 |
|------|----------|
| 流程 | 分阶段推进；门禁判定；失败恢复须按 `retry → replan → rollback` **顺序**执行，不得跳步。 |
| 工件 | 存在或将创建 `.ai/tasks/<task_id>/` 下的 `task.yaml`；或用户要求继续、恢复、对齐任务快照。 |
| 标识 | 对话中出现符合第 5 节正则的 `task_id`。 |
## 3. 刚性规则（用户未显式豁免时不可协商）
- 不得跳过对 workflow 的 **schema 校验** 即进入执行态。
- 门禁须附 **可复核证据**（命令输出、路径、日志片段等）；口头断言不算过门。
- 编排职责归 **coordinator**；子代理不得各自推进阶段并分叉状态。
- 「先执行、后补校验」视为违规。
## 4. 加载与阅读顺序（每次任务或协议有更新时重读）
按序执行，**不得颠倒**：
1. **Read** 本文件（`SKILL.md`）。
2. 若涉及阶段 / 门禁 / 恢复：**Read** `skills/call-reason-cavalier/workflow-protocol.md`。
3. 若涉及 `task.yaml` / `task_id` / 落盘与恢复：**Read** `skills/call-reason-cavalier/task-protocol.md`。
4. 执行 **`commands/task.md`** 所述流程前须已 Read 本文件；`task.yaml` 须由 `scripts/new-task.py` 生成；`workflow.yaml` 须为 `workflows/dev.workflow.yaml` 的完整副本；禁止手写流水号与 `uid`。
## 5. task_id 命名规范（全仓库唯一权威）
以下规则为全仓库对 `task_id` 的**唯一**展开说明；`task-protocol.md`、`commands/task.md` 等仅引用本节，不再重复细则。
- **形式**：`{type}-{YYMMDD}{NNN}-{name}`
- **`type`**：`feat|bug|refactor|test|doc|chore`；须与 `task.yaml` 中 `type` 一致，且为 `task_id` 首段。
- **`YYMMDD`**：UTC 日历日六位数字。
- **`NNN`**：当日三位流水号，自 `001` 递增；**仅允许**由 `scripts/new-task.py` 在扫描已有 `.ai/tasks/<task_id>/` 后分配（禁止手填）。
- **`name`**：kebab-case，仅 `a-z`、`0-9`、`-`；未传 `--slug` 时由 `--title` 转写（UTF-8 → 小写 ASCII kebab），或 `--slug` 显式指定。
- **校验正则**（与 `new-task.py` 落盘一致）：
`^(feat|bug|refactor|test|doc|chore)-\d{9}-[a-z0-9]+(?:-[a-z0-9]+)*$`
- **示例**：`feat-260420001-add-trading-domain-code`、`bug-260415001-checkout-timeout`
- **`uid`**：与 `task_id` 独立；须为 ULID，**仅允许**由 `new-task.py` 生成。
## 6. 新建任务目录与 task.yaml（stdlib only）
在仓库根目录执行：
```bash
python skills/call-reason-cavalier/scripts/new-task.py --type feat --title "你的任务标题" [--slug optional-kebab-slug] [--workflow dev]
```
- 落盘为原子写（临时文件再替换）。常用：`--repo-root`、`--host-app`、`--dry-run`。
- 脚本**只生成 `task.yaml`**；完整任务存储还须将 `workflows/dev.workflow.yaml` 复制为同目录 `workflow.yaml`（见 `commands/task.md`）。
## 7. 协议分工
| 对象 | 协议 | 职责 |
|------|------|------|
| `workflow.yaml` | `workflow-protocol.md` | 阶段、步骤、门禁、schema；模板见 `workflows/dev.workflow.yaml` |
| `task.yaml` | `task-protocol.md` | 任务快照、`workflow`/`stages` 与 coordinator 绑定、读写与恢复 |
## 8. 编排主链（须遵守的顺序）
**选定 workflow → Schema 校验 → 执行当前 Stage/Step → 记录证据 → 过门禁 → 迁移或按恢复序处理 → 输出 `complete` 或 `blocked`。**
```mermaid
flowchart TD
R[收到请求] --> Q{是否可能涉及阶段/门禁/恢复或 task 快照?}
Q -->|否| N[常规处理]
Q -->|是或不确定| L[Read 本技能 + 所需协议]
L --> T[绑定 task_id，选定 workflow]
T --> V{Schema 通过?}
V -->|否| B[blocked：修正配置或说明无法执行]
V -->|是| S[执行当前 Stage/Step]
S --> E[写入可复核证据]
E --> G{门禁满足?}
G -->|否| F[retry → replan → rollback]
F --> S
G -->|是| M{还有下一阶段?}
M -->|是| S
M -->|否| C[complete 或 blocked]
```
## 9. 危险信号（自我合理化时须停下）
| 想法 | 事实 |
|------|------|
| 先改代码，workflow 稍后补 | 未通过校验不得进入执行态 |
| 小任务不用门禁 | 由协议与任务性质决定，不由体量感觉决定 |
| 证据口头即可 | 门禁要可复核证据 |
| 子代理各自推进 | 产出须回流统一 `task_id` 与阶段状态 |
| 跳过 retry 直接 rollback | 恢复顺序固定 |
| 我记得协议 | 以当前 Read 到的版本为准 |
## 10. 最小检查清单
1. 有或将写任务快照：**Read** `task.yaml` + `task-protocol.md`，确认 `workflow`、`stages`、`task_id` 一致。
2. 对 workflow 做 schema 校验（禁止跳过）。
3. 执行当前阶段并记录证据；门禁不过则按 **retry → replan → rollback** 处理。
4. 会话结束语为 **`complete`** 或 **`blocked`**（含原因与已有证据）。多步可与 `TodoWrite` 对齐。
## 11. 技能类型说明
本技能对 **校验、门禁证据、恢复顺序、快照一致性** 为 **刚性**；对具体技术实现细节为 **柔性**（由项目内命令与仓库约定填充）。Harnessing (驾驭化) audits an external application repository for Reason Cavalier Harness adoption readiness using stdlib Python scripts under skills/harnessing/scripts (.ai runtime dirs, Harness-oriented AGENTS.md, persistent docs/), proposes fixes, and can idempotently create blocking `.ai` dirs in one command via `harness_check.py --ensure-blocking-dirs` without user confirmation; other scaffolding and content passes still require explicit user confirmation. Use when an external project wires in or runs against this harness, onboards to Harness engineering, or asks for readiness checks and optional bootstrap.
# Harnessing（驾驭化）
> **驾驭化**：把外部工程纳入 Harness 可治理、可续跑、可证据化的落盘与文档约束；本技能在仓库内路径为 `skills/harnessing/`，技能代号为 **`harnessing`**（原 `harness` 目录已迁移至此）。
## 定位（必读）
- **Reason Cavalier 本仓库**是供**外部业务工程**引用的 Harness 能力与约定来源；被检查的通常是**外部项目根目录**，不是「给本仓库装插件」。
- 本技能回答：外部工程是否具备**按 Harness 运转的最小落盘结构**与**代理可读规范**；缺什么、怎么补、是否值得优化。
- **推荐流程**：`harness_check.py` 检测 → 向用户展示结论 → **阻塞项 `.ai` 三件套**（`.ai/`、`.ai/tasks/`、`.ai/workflows/`）可用**一条命令**幂等补齐（见下节 `--ensure-blocking-dirs`，**无需**用户再次确认）→ 其余写盘（`AGENTS.md` / `docs` / `.ai/memory` / `--content-round1` 等）仍须在用户明确同意后再执行 `harness_init.py`（可先 dry-run）→ 最后再跑 `harness_check.py` 复查。
## 0. 自动化脚本（本插件仓库）
路径（相对本仓库根）：`skills/harnessing/scripts/`。无第三方依赖，需 **Python 3**。
| 脚本 | 作用 |
|------|------|
| `harness_check.py` | 检测目录与 `AGENTS.md` / `docs` 入口及内容锚点；可加 `--ensure-blocking-dirs` **单次幂等**创建阻塞项 `.ai` 目录树 |
| `harness_init.py` | 创建目录树、骨架 `AGENTS.md`、`docs/index.md`；可选一轮内容补全（除「仅阻塞 `.ai`」窄豁免外，默认需用户确认后再 `--apply`） |
| `harness_spec.py` | 规则常量（被上述脚本引用，勿单独对用户强调） |
**检测（只读）**（将 `<ROOT>` 换为外部工程根目录的绝对路径）：
```bash
python skills/harnessing/scripts/harness_check.py <ROOT>
python skills/harnessing/scripts/harness_check.py <ROOT> --json <ROOT>/.ai/harness-check.json
```
**一条命令补齐阻塞项 `.ai` 目录树**（创建 `.ai/`、`.ai/tasks/`、`.ai/workflows/` 及 `.gitkeep`，**不含** `.ai/memory`、`AGENTS.md`、`docs/`；幂等、可重复执行）：
```bash
python skills/harnessing/scripts/harness_check.py <ROOT> --ensure-blocking-dirs
```
- 退出码：`0` 无阻塞；`1` 存在阻塞项；`2` 仅有建议/警告（无阻塞）。
- 代理应在执行后**读取终端输出或 `--json`**，再向用户给出结论表。
- **`--json` 路径父目录不存在时会自动创建**（便于写到 `<ROOT>/.ai/harness-check.json`）。
**初始化与一轮内容补全（写盘）**：默认不加 `--apply` 时为 **dry-run**，仅打印将执行的动作。
```bash
python skills/harnessing/scripts/harness_init.py <ROOT>
python skills/harnessing/scripts/harness_init.py <ROOT> --apply --scope all --content-round1
```
- 与 `--ensure-blocking-dirs` **等价写盘范围**的替代写法（同样**无需**为「仅目录」额外索要用户确认）：`python skills/harnessing/scripts/harness_init.py <ROOT> --apply --scope ai-only`（仅 `BLOCKING_DIRS`，不含 `.ai/memory`）。
- `--scope`：`all`（默认，含 `.ai` 阻塞项 + `.ai/memory` 建议项 + `docs/` + 缺省则写 `AGENTS.md` 骨架）、`ai-only`、`agents`、`docs`。
- `--content-round1`：在**不覆盖**既有正文的前提下，对偏弱的 `AGENTS.md` **追加**带标记段落；若缺 `docs/index.md` 则补最小入口。
- `--force-agents`：**慎用**，在 `--scope agents` 或 `all` 时允许覆盖已有 `AGENTS.md`。
- 成功写盘且复查**无阻塞**时进程退出 `0`（仅有警告也视为 `0`，便于链式脚本）。
**门禁（更新）**：
- **窄豁免（无需用户再次确认）**：仅为创建 **`harness_spec.py` 中 `BLOCKING_DIRS`**（`.ai/`、`.ai/tasks/`、`.ai/workflows/`）及占位 `.gitkeep` 时，代理可直接执行 **`harness_check.py <ROOT> --ensure-blocking-dirs`**，或 **`harness_init.py <ROOT> --apply --scope ai-only`**。不得顺带改写 `AGENTS.md`、`docs/` 正文，不得使用 `--force-agents` / `--content-round1` / `--scope all`（除非用户已明确同意相应范围）。
- **其余写盘**：在用户明确说出同意补齐（如「是」「按建议执行」）并尽量限定范围之前，代理**不得**调用会写入 `AGENTS.md`、`docs/`、`.ai/memory` 或覆盖正文的 `harness_init.py --apply` 组合，也不得手工批量改外部仓库。
## 1. 检查清单（与脚本一致；可人工复核）
逐项记录 **OK / 缺失 / 警告**，并附一行证据（路径或「不存在」）。
### 1.1 `.ai/` 运行时目录（Harness 常见必备）
以「是否存在且可被代理与工具稳定写入」为准（具体子目录以当前 Harness 蓝图为锚；缺蓝图时脚本按下述最小集判断）：
- `.ai/` 根目录是否存在。
- `.ai/tasks/`：任务与执行上下文的持久化（如 `task.yaml` 等）。
- `.ai/workflows/`：工作流模板或运行期工作流落盘占位。
- **建议项**：`.ai/memory/`（执行记忆、可消费中间态；与正式 `docs/` 区分）。
若外部工程文档中规定了额外子路径（如审计、策略快照目录），脚本未覆盖时由代理**额外**核对并标为「契约项」或「建议项」。
### 1.2 Harness 向的代理说明（仓库根）
- **规范文件名**：`AGENTS.md`（若目录中存在与 `AGENTS.md` 仅大小写不同的变体，记**警告**并建议统一为 `AGENTS.md`；在大小写不敏感系统上脚本会避免误报）。
- 内容是否**非空**、长度与锚点是否达到脚本阈值（过短或缺少 `.ai` / `tasks` / `workflows` / `docs` / 验证或证据等语义之一组，记**阻塞**）；空壳或一句话占位记为**缺失**。
- 是否与 **Harness 工程**语义一致（能支撑多会话续跑、文档与 `.ai` 分工、门禁/证据等叙述之一即可；不必照抄本仓库全文）。
### 1.3 `docs/` 项目文档持久化区
`docs/` 的定位：**正式知识、归档、文档治理与清理结果的持久化存储**（人类可读、可评审、可版本化），与 `.ai/memory/` 等执行态区分。
检查：
- `docs/` 是否存在（脚本层为建议/警告；代理可结合工程契约升为阻塞）。
- 是否有**可导航入口**（`docs/index.md` 或 `docs/README.md`）。
- 与 Harness 常见约定相关的子树是否在**该外部工程**中有落点。
## 2. 输出格式（给用户）
1. **结论**：该外部工程是否满足「按 Harness 最小可运转」条件；阻塞项与可后补项分开写（与 `harness_check.py` 退出码一致）。
2. **检查结果表**：覆盖 1.1～1.3；优先引用脚本输出或 `--json` 中的 `rows`。
3. **优化建议**：按 **阻塞 / 建议 / 可选** 排序，并说明每项对「续跑、归档、文档清理持久化」的影响。
4. **明确提问**（仅当需要 **超出**「阻塞项 `.ai` 三件套」的补齐时）：`是否需要我继续补齐？请回复「是」并说明范围（例如 .ai/memory、AGENTS.md 骨架、docs 最小入口、`--content-round1` 等）。`
在用户确认前：**不要**调用会写入 `AGENTS.md`、`docs/`、`.ai/memory` 或 `--content-round1` / `--force-agents` 的 `harness_init.py --apply`；**不要**手工写/覆盖 `AGENTS.md`、不要批量改 `docs/`。**允许**直接执行 `harness_check.py <ROOT> --ensure-blocking-dirs`（或等价的 `harness_init.py --apply --scope ai-only`）以创建阻塞项 `.ai` 目录树。
## 3. 用户确认后的「补齐」约定
**阻塞项 `.ai` 三件套**已可由第 0 节命令在无额外确认下完成。以下针对 **`.ai/memory`、`AGENTS.md`、`docs/`、内容轮次** 等超出窄豁免的写盘：
仅在用户明确同意（如「是」「优化」「按建议执行」并限定范围）后执行：
1. 先对外部根目录执行 `harness_init.py <ROOT>`（dry-run），与用户确认范围一致后再 `--apply`。
2. **`.ai/`**：按 `--scope` 创建缺失目录；空目录使用 `.gitkeep`（路径使用正斜杠描述，如 `.ai/workflows/.gitkeep`）。若仅需阻塞子集，优先用 `harness_check.py <ROOT> --ensure-blocking-dirs` 或 `--scope ai-only`。
3. **`AGENTS.md`**：由脚本写入与该外部工程一致的骨架（若存在 `package.json` 则**仅摘录已有 `scripts` 键名**）；**禁止**编造不存在的命令或路径。需要覆盖旧文件时必须有用户明确授权并使用 `--force-agents`。
4. **`docs/`**：在同意范围内补最小入口；**不**擅自大段覆盖已有规格/蓝图类正文。内容仍偏弱时，可再使用 `--content-round1` 追加带标记段落（**一轮**；重复执行会因标记存在而跳过追加）。
5. 结束后给出**变更文件列表**与需人工补全的条目，并再运行 `harness_check.py` 作为证据。
## 4. 自检
- `description` 为第三人称，含能力与触发场景。
- 术语统一：**外部工程**、**Harness**、**持久化**；路径统一正斜杠。
- 脚本与清单冲突时，以 `harness_spec.py` 与脚本实现为准，并**更新本技能**使二者一致。