# AGENT_RULES

目的：为本仓库提供稳定的 Matt Pocock 工程流程与 ticket 执行约束。

`.scratch/` 是 spec、ticket、feature 队列和执行状态的唯一事实源。
`memory-bank/` 保存稳定的项目定位、技术上下文和当前系统模式。
`CONTEXT.md` 保存稳定领域词汇，`docs/adr/` 保存关键架构决策。

## 优先级

1. 系统/开发者指令
2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
3. 仓库规则：`.agents/` 与 `AGENTS.md`
4. 本文件

## 沟通原则

- 统一使用简体中文
- 发现用户理解有误时，礼貌纠正
- 不给时间估算，专注事实、风险与下一步

## 项目边界

- `{{PLAYBOOK_ROOT}}/` 是 Playbook 模板/供应商目录，不是业务项目源码
- 除非任务明确维护 Playbook，不得修改 `{{PLAYBOOK_ROOT}}/` 下内容
- 当前项目的生效规则位于项目根目录的 `AGENT_RULES.md`、
  `AGENT_RULES.local.md`、`AGENTS.md` 与 `.agents/`
- 搜索、批量修改、review 和提交时默认排除 `{{PLAYBOOK_ROOT}}/`
- 不覆盖、stash、reset 或提交不属于当前 ticket 的既有改动

## 会话启动

处理首个实质性任务前，按相关性读取；不存在则跳过：

1. `AGENT_RULES.local.md`
2. `.agents/index.md`
3. `memory-bank/project-brief.md`
4. `memory-bank/tech-context.md`
5. `memory-bank/system-patterns.md`
6. `docs/agents/issue-tracker.md`
7. `docs/agents/domain.md`
8. `CONTEXT.md` 或 `CONTEXT-MAP.md`
9. 相关 `docs/adr/`
10. `main_loop.py status --state-root .scratch` 的当前状态

## 任务入口

### 可直接执行

只读分析、定位、审查，以及不改变行为的局部机械修改可以直接执行，不生成
spec/tickets。仍须遵守项目规则、验证实际结果，并只处理本次相关改动。

### 新 feature 或设计变更

需要需求澄清、设计取舍、跨 session 调度、并发执行、迁移或回滚时，进入完整工程
主链。边界不清时也走该入口；执行中才发现存在未确认设计时停止实现，已有改动只作为
事实输入，不视为已批准方案。

### 已明确预期行为的 bug

已知正确行为且可以建立失败反馈回路的 bug，使用 `diagnosing-bugs` 完整执行 Phase 1-6，
由它负责反馈回路、回归测试、修复、验证和清理，不再进入 `implement` 或重复 `tdd`，也不为
已确定的需求重新 grilling。若诊断暴露新的产品取舍、架构方向或缺失测试 seam，停止修复并
转入 `grill-with-docs`。若 bug 来自已领取 ticket，Phase 6 后直接继续本地 ticket 执行协议的
提交、review 和 finish 门禁。

## 正式工程主链

新 feature 或设计变更使用以下顺序：

```text
setup-matt-pocock-skills
  -> grill-with-docs (grilling + domain-modeling)
  -> to-spec
  -> to-tickets
  -> main_loop.py enqueue
  -> main_loop.py claim
  -> 本地 ticket 执行协议 (tdd -> commit -> code-review -> finish)
  -> main_loop.py integrate
```

- 每个仓库首次使用时运行 `setup-matt-pocock-skills`，本地开发选择 local markdown tracker
- 正式仓库设计使用 `grill-with-docs`
- 进入 `grill-with-docs` 或本地 ticket 执行协议前，重新读取 `memory-bank/project-brief.md`、
  `memory-bank/tech-context.md` 和 `memory-bank/system-patterns.md`
- `grilling` 必须走完整 design tree，frontier 清空并经用户确认后才进入 `to-spec`
- `to-spec` 不重新进行已经完成的需求采访；但必须按其原始流程确认测试 seam。若
  grilling 尚未确认 seam，必须先向用户完成 seam confirmation
- `tdd` 不得在未经确认的 seam 上开始
- `to-tickets` 产出可独立验证的 tracer-bullet tickets，并显式声明 `Blocked by`
- 一次可以先生成多个 feature 的 spec/tickets，再按期望顺序逐个 `enqueue`

## On-ramps 与 detours

- 超过单个 session 可容纳的巨大、模糊工作先走 `wayfinder`；决策地图清晰后进入
  `to-spec -> to-tickets`，不得从决策 ticket 直接跳到实现
- `research` 产出的高可信一手来源报告先进入 `grill-with-docs`，作为设计输入；调研不能
  替代 grilling
- 已由 `to-tickets` 生成的 ticket 直接从 `main_loop.py claim -> 本地 ticket 执行协议` 开始，
  不再 triage 或重复需求采访

## Phase boundaries

只在阶段边界按以下顺序判断，首个满足项生效：

1. 下一阶段需要当前 primary source 且 smart zone 足够时，继续当前 session
2. 当前上下文与下一阶段无关时，使用 `clear`
3. 仅在跨 harness、跨目录/仓库、交给同事或 mid-phase 分出旁支任务时使用 `handoff`
4. 任务可独立 AFK 完成时交给 subagent
5. 其余同 harness、同目录且仍需当前上下文的情况使用 `compact`

上下文过长不等于必须 `handoff`；`handoff` 解决的是可移植性。`compact` 是决策树的默认
落点，但不是第一选择。`CONTEXT.md` 和 memory-bank 都不能替代阶段上下文。

## 本地 Ticket 执行协议

这是 Playbook 对 Matt 工程 skills 的调度适配层。它复用 `tdd` 和 `code-review`。
不直接调用上游 `implement`；后者的 `code-review -> commit` 尾部顺序无法生成主循环要求的
固定 commit 证据。

对每个 claim 严格按以下顺序执行：

1. 读取已领取 ticket 的 spec、ticket、相关稳定知识和 ADR
2. 在已确认 seam 上按 `tdd` 完成 ticket 的可观察行为，并运行局部验证
3. 提交全部实现，使 ticket branch `HEAD` 成为固定、干净的审查点
4. 运行 `code-review`，显式提供 fixed point 和 Review 适配契约规定的需求来源
5. 修复硬 finding 后重新提交、验证和 review，直到两个 axis 均满足 pass 条件
6. 调用 `main_loop.py finish`，提交与当前 `HEAD`/base 绑定的结构化证据

## 文档职责

- `memory-bank/project-brief.md`：稳定项目定位、边界、目标和成功定义
- `memory-bank/tech-context.md`：技术栈、工具链、环境差异和验证入口
- `memory-bank/system-patterns.md`：当前模块边界、数据流、系统不变量和扩展路径
- `CONTEXT.md`：稳定领域词汇和定义，不记录 feature 状态
- `docs/adr/`：难以逆转且需要长期背景的真实技术取舍
- `.scratch/<feature>/spec.md`：单个 feature 的问题、方案、用户故事和测试决策
- `.scratch/<feature>/issues/*.md`：ticket DAG、验收标准和机器状态
- `.scratch/queue.md`：feature 开发与集成顺序
- `docs/agents/*.md`：tracker、领域文档布局和 skill 配置

不得手工修改 ticket 的 `Status` 或 `main-loop:ticket-state` 区块；只通过主循环变更。

## 稳定知识维护

只记录下一 session 仍需要的稳定知识；当前 feature、ticket、owner、heartbeat、验证和
集成状态只由 `.scratch/` 与 `main_loop.py` 维护。

- 项目定位、边界、目标或成功定义长期变化时，更新 `project-brief.md`
- 技术栈、工具链、环境差异或验证入口长期变化时，更新 `tech-context.md`；写入
  `tech-context.md` 的命令和环境事实必须已经验证
- `system-patterns.md` 记录当前成立的架构；关键取舍及理由写入 `docs/adr/`
- `CONTEXT.md` 只记录稳定领域词汇和定义；不把聊天流水、未验证猜测或短期进度写入
  `CONTEXT.md`
- 项目特有执行规则写入 `AGENT_RULES.local.md`
- 符合 phase-boundary 窄条件的可移植上下文由 `handoff` 写入 OS 临时目录，不写入稳定
  知识文件；同 harness、同目录的续作优先按决策树选择 continue、clear 或 compact
- 不为普通实现选择创建 ADR；没有长期价值的信息时不更新这些文件

## 调度语义

- feature 按 `.scratch/queue.md` 顺序调度
- 同一 feature 中 blocker 全部满足的 tickets 构成 frontier，按稳定编号领取
- 同一 feature 的多个 frontier tickets 可在 worktree 模式并发执行
- 当前 feature 的 frontier 全被领取时返回 `BUSY`，不向后续 feature 扩张
- 只有前序 feature 无 frontier、无活动 claim 且确实 blocked 时，才可开发后序 feature
- 前序 feature 恢复后，新 claim 重新优先前序 feature
- 后序已领取 ticket 可以完成，但 feature 集成到 `main` 必须严格遵循队列顺序
- `resolved` 和显式 `skipped` 满足 blocker；`claimed`、`blocked`、
  `ready-for-agent` 不满足
- 含 `skipped` ticket 的 feature 标记为 partial，集成时必须显式授权
- stale 只由 heartbeat 时间派生，不自动转移 owner；只有 `reclaim` 可以接管

## 执行隔离

`claim --isolation` 支持：

- `in-place`：串行执行，不创建额外 worktree；claim 生命周期内其他 owner 得到 `BUSY`
- `worktree`：每个 ticket 独立 branch/worktree，适用于多 session 并发
- `auto`：无其他活动 claim 时使用 in-place，否则使用 worktree

计划并发时，第一个 session 就必须指定 `worktree`。明确不并发时可使用
`in-place` 或 `auto`，不必创建 worktree。

in-place 模式要求 checkout 无非 `.scratch` 改动、HEAD 非 detached，且目标 branch
未被其他 worktree 占用。主循环不得自动 stash、reset、覆盖或丢弃改动。

`main_loop.py` 只支持 local Markdown tracker，并要求所有 sessions 共享同一文件系统、
control checkout 和 Git common directory。远程 tracker 可以由 Matt skills 单独使用，
但本主循环没有远程 tracker adapter，不能接入远程 claim/finish 状态。跨机器或独立
clone 的并发不受支持，不得把两份 `.scratch/` 当成同一队列。

## 主循环命令

### 入队和状态

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py enqueue \
  --state-root .scratch --feature <feature-slug>

python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
  --state-root .scratch
```

### 领取

`<owner>` 必须是当前 session 全局唯一且稳定的标识，例如
`<agent>-<UTC timestamp>-<random suffix>`。不得在并行 session 间复用 `codex`、`claude`
等通用名称；同一 owner 的重复 claim 只用于原 session 恢复自己的 ticket。

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
  --state-root .scratch --repo-root . \
  --owner "<owner>" --isolation in-place|worktree|auto
```

stdout 返回 `FEATURE`、`TICKET`、`CONTROL_ROOT`、绝对 `STATE_ROOT`、`WORKSPACE`、
`BRANCH`、`BASE` 和 `ISOLATION`：

- `CONTROL_ROOT` 是共享 Git control checkout
- `STATE_ROOT` 是唯一状态目录；它不必位于 `WORKSPACE` 内
- `WORKSPACE` 是当前 ticket 的代码工作区

领取成功后立即读取 `<STATE_ROOT>/<FEATURE>/spec.md` 和
`<STATE_ROOT>/<FEATURE>/issues/<TICKET>-*.md`；不得在 claim 前根据 frontier 猜测本 session
将领取哪个 ticket。后续 review 也必须使用这两个已领取上下文，而不是 worktree 内相对
`.scratch` 的偶然副本。

实现、提交和 review 必须在返回的 `WORKSPACE`/`BRANCH` 中完成。heartbeat、reclaim、
finish、status、block/release-feature 和 integrate 必须使用
`--state-root "<STATE_ROOT>"`，不得在 ticket worktree 中使用相对 `.scratch`。

同一 owner 重复 claim 恢复原 ticket。其他 owner 不得接管；失联时使用显式 reclaim。

### 心跳和接管

claim 的 stale 租约固定为 30 分钟，调用者不得缩短。claim 存续期间至少每 10 分钟发送一次
heartbeat，并在预计耗时较长的验证、构建或 review 前后各发送一次。无法继续维持 heartbeat
时，使用 `finish --result released|blocked` 明确交还或阻塞 ticket。

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py heartbeat \
  --state-root "<STATE_ROOT>" \
  --feature <feature> --ticket <NN> --owner "<owner>"

python {{PLAYBOOK_SCRIPTS}}/main_loop.py reclaim \
  --state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
  --feature <feature> --ticket <NN> --owner "<new-owner>"
```

reclaim 只允许接管 stale claim，并保留原 branch、worktree 和未提交改动。

### Review 适配契约

调用 Matt `code-review` 时不得依赖其自动搜索或交互补问，必须显式提供：

- fixed point：ticket review 使用 claim 的 `BASE` 或重试返回的 `FEATURE_HEAD`；feature review
  使用最新 `main` HEAD
- ticket review 的 Spec sources：逻辑路径 `.scratch/<feature>/spec.md` 与
  `.scratch/<feature>/issues/<ticket>-*.md`，实际从绝对 `STATE_ROOT` 解析
- feature review 的 Spec sources：`.scratch/<feature>/spec.md` 和该 feature 的全部 ticket
  acceptance criteria，实际从绝对 `STATE_ROOT` 解析

只有对应 axis 零个未解决的硬 finding 时才能记录 `pass`：

- `standards=pass`：没有未解决的仓库标准违规；baseline smell 属 judgement call，必须逐项记录
  已修复或带理由接受，但不会仅因被提出就自动失败
- `spec=pass`：没有遗漏、部分实现、错误实现或未授权范围扩张

任一来源缺失、Spec axis 被跳过、review 尚在询问输入，或仍有未解决的硬 finding 时，
不得据此填写 `standards=pass` 或 `spec=pass`。修复会改变 `HEAD`，因此必须重新运行受影响
验证和完整双轴 review，不能沿用旧报告。

### Ticket 完成或状态转换

`resolved` 前必须先提交实现，再按 Review 适配契约对 `BASE...HEAD` 运行 Matt
`code-review` 的 Standards/Spec 双轴审查。
验证证据必须包含被验证 commit，review 证据必须包含被审查 commit 和固定 base；任意
非空文本或裸 `pass` 不能替代结构化证据。

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
  --state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
  --feature <feature> --ticket <NN> --owner "<owner>" \
  --result resolved \
  --implementation-commit <HEAD> \
  --feature-head <已验证feature HEAD> --review-base <同一feature HEAD> \
  --verified "commit=<HEAD>; result=pass; <实际局部验证证据>" \
  --reviewed "commit=<HEAD>; base=<review-base>; standards=pass; spec=pass"
```

首次 review base 是 claim 返回的 `BASE`。feature HEAD 已推进时返回
`RETRY: feature advanced` 和新的 `FEATURE_HEAD`；把该 `FEATURE_HEAD` 合入 ticket branch，
重新运行受影响验证，并以它作为新的 review base 重跑双轴 review。重试时
`--feature-head`、`--review-base` 和 review evidence 的 `base` 必须都使用该新值，验证与
review evidence 的 `commit` 必须等于新的 ticket `HEAD`。只有成功集成到 feature branch
后 ticket 才变为 `resolved`。

其他转换：

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
  --state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
  --feature <feature> --ticket <NN> --owner "<owner>" \
  --result blocked|skipped --reason "<明确原因>"

python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
  --state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
  --feature <feature> --ticket <NN> --owner "<owner>" \
  --result released
```

release 返回 `ready-for-agent` 并保留 workspace；blocked ticket 可由原 owner release 后恢复。

### Feature 集成阻塞

ready-to-integrate feature 若因 main 同步冲突或人工决策暂时不能集成，必须显式记录；
这样主循环才会继续为后序 feature 分配开发工作：

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py block-feature \
  --state-root "<STATE_ROOT>" --feature <feature> --reason "<明确原因>"

python {{PLAYBOOK_SCRIPTS}}/main_loop.py release-feature \
  --state-root "<STATE_ROOT>" --feature <feature>
```

release 后该 feature 重新成为队首 `INTEGRATION_REQUIRED`。后序 feature 即使已开发完成，
仍不得越过它集成到 main。

### Feature 顺序集成

feature 必须吸收最新 `main`，完成 feature 验证、main 候选验证和最终双轴 review：

```bash
python {{PLAYBOOK_SCRIPTS}}/main_loop.py integrate \
  --state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
  --feature <feature> --feature-head <已验证feature HEAD> \
  --verified "commit=<feature HEAD>; result=pass; <feature级验证证据>" \
  --main-verified "commit=<feature HEAD>; result=pass; <main候选验证证据>" \
  --reviewed "commit=<feature HEAD>; base=<最新main HEAD>; standards=pass; spec=pass"
```

partial feature 还需 `--allow-partial`。返回 `RETRY: feature needs main sync` 时，
先在 feature integration workspace 合并最新 main；若发生冲突，先 `block-feature`，解决后
`release-feature`，重新验证和 review 后再调用。

## Git 与证据门禁

1. 每个 ticket 使用 `ticket/<feature>/<NN>-<slug>` branch
2. 每个 feature 使用 `feature/<feature>` branch
3. 按 TDD 完成一个可观察行为切片并运行局部验证
4. 提交全部实现，使 `HEAD` 成为可审查固定点
5. 首次以 claim 的 `BASE` 运行 `code-review`；同步推进后的 feature 时改用新的
   `FEATURE_HEAD`
6. 修复 finding 后重新提交、验证和 review
7. `finish` 校验验证/review commit、review base 和 feature HEAD，再集成 ticket
8. `integrate` 把两级验证和最终 review 绑定到 feature HEAD，并把 review base 绑定到
   最新 main HEAD

局部 ticket 验证、feature 验证和 main 候选验证是三个独立门禁，不能互相替代。
证据必须来自实际 fresh run；无法运行时不得伪造 `pass`。

## 辅助能力

以下能力在对应阶段内按需使用，不替代上面的入口路由和证据门禁：

| Skill            | 触发条件                            |
| ---------------- | ----------------------------------- |
| `codebase-recon` | 架构、跨模块、重构、迁移或风险不明  |
| `brooks-audit`   | 架构边界和长期维护性审查            |
| `commit-message` | 需要检查 staged diff 或生成提交信息 |

## 需要确认的场景

设计阶段由 `grilling` 收敛所有决策。执行 ticket 时仅在以下情况暂停确认：

- ticket/spec 仍存在会改变实现的真实歧义
- 需要 spec 未授权的行为、兼容性或架构取舍
- 需要破坏性操作、覆盖他人改动或扩大任务范围

已明确预期行为的 bug 按 `diagnosing-bugs` 路由推进；符合既有模式的小改动、测试补齐和
已批准 ticket 范围内的实现不重复需求采访。
无交互模式下不得替用户作设计决策；将 ticket 标记 blocked 并记录原因。

## Session 收尾

- 运行与声明相匹配的 fresh verification
- ticket 执行必须通过 `finish` 写回；不得手工改状态
- 列出已完成、未完成、验证证据、风险和下一步
- 只提交当前 ticket/feature 相关改动，不混入其他 session 差异
- 工作未结束时在阶段边界按 Continue -> clear -> handoff -> subagent -> compact 的顺序选择
  去向；不要仅因上下文过长就创建 handoff

---

**最后更新**：{{DATE}}