✨ feat(workflow): adopt Matt Pocock ticket workflow

Replace the Superpowers plan pipeline with grill-with-docs, specs, local tickets, and ticket-native execution. BREAKING CHANGE: Remove the legacy Plan CLI, prompt templates, and Superpowers skills.
2026-08-10 16:55:46 +08:00
parent 29d110110b
commit 699b431cac
164 changed files with 9039 additions and 12273 deletions
@@ -6,7 +6,8 @@

 <!-- playbook:agents:start -->

- [.agents/index.md](.agents/index.md) - 语言规则索引
+- 入口：`.agents/index.md`（由 `[sync_standards]` 同步生成）
+
 <!-- playbook:agents:end -->

 <!-- playbook:templates:start -->
@@ -17,19 +18,16 @@

 - [AGENT_RULES.md](./AGENT_RULES.md) - 执行规则与工作流入口

-### 项目状态
+### 工程上下文

- [memory-bank/project-brief.md](memory-bank/project-brief.md) - 项目定位
- [memory-bank/active-context.md](memory-bank/active-context.md) - 当前上下文
- [memory-bank/progress.md](memory-bank/progress.md) - 进度追踪
+- [memory-bank/project-brief.md](memory-bank/project-brief.md) - 项目定位、边界与目标
+- [memory-bank/tech-context.md](memory-bank/tech-context.md) - 技术栈、工具链与验证入口
+- [memory-bank/system-patterns.md](memory-bank/system-patterns.md) - 当前架构与系统不变量
+- [docs/agents/issue-tracker.md](docs/agents/issue-tracker.md) - ticket 存储约定
+- [docs/agents/domain.md](docs/agents/domain.md) - 领域文档布局
+- [CONTEXT.md](CONTEXT.md) - 稳定领域词汇（如存在）
+- [.scratch/queue.md](.scratch/queue.md) - feature 队列与执行入口

-### 任务入口
-
- [docs/prompts/README.md](docs/prompts/README.md) - 提示词与任务入口
 <!-- playbook:templates:end -->

 <!-- playbook:framework:end -->
-
---
-
-**最后更新**：{{DATE}}
@@ -1,10 +1,10 @@
 # AGENT_RULES

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

-本文件是框架流程约束基线；`docs/superpowers/`
-是唯一设计与计划产物中心；执行状态统一写回
-`memory-bank/progress.md`。
+`.scratch/` 是 spec、ticket、feature 队列和执行状态的唯一事实源。
+`memory-bank/` 保存稳定的项目定位、技术上下文和当前系统模式。
+`CONTEXT.md` 保存稳定领域词汇，`docs/adr/` 保存关键架构决策。

 ## 优先级

@@ -16,303 +16,384 @@
 ## 沟通原则

 - 统一使用简体中文
- 专业、直接、简洁，避免对话填充词
 - 发现用户理解有误时，礼貌纠正
- 无法满足请求时，简洁说明原因；如有可行替代方案则一并给出
 - 不给时间估算，专注事实、风险与下一步

 ## 项目边界

-### Playbook 目录
-
- `{{PLAYBOOK_ROOT}}/` 是 Playbook 模板/供应商目录，不是业务项目源码、
-  业务文档或当前项目私有规则
- 除非用户明确要求维护、升级或调试 Playbook 本身，不得修改
-  `{{PLAYBOOK_ROOT}}/` 下内容
- 当前项目的生效规则是项目根目录的 `AGENT_RULES.md`、`AGENT_RULES.local.md`、
-  `AGENTS.md` 与 `.agents/`；`{{PLAYBOOK_ROOT}}/templates/` 与
-  `{{PLAYBOOK_ROOT}}/rulesets/` 只是模板源，不是当前项目已生效规则
- 可按 `.agents/` 指向读取 `{{PLAYBOOK_ROOT}}/docs/` 作为标准文档；
-  读取不代表该目录属于业务改动范围
- 搜索、批量修改、代码审查、归档/提交时，默认排除 `{{PLAYBOOK_ROOT}}/`；
-  只有任务目标明确涉及 Playbook 时才纳入
+- `{{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. `memory-bank/active-context.md`：当前目标、最近变更、下一步
-7. `memory-bank/decisions.md`：重要决策记录
-8. `memory-bank/progress.md`：执行进度与 Plan 状态
-9. `docs/superpowers/specs/`：最新设计稿
-10. `docs/superpowers/plans/`：相关实施计划
+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` 的当前状态

-**执行约束**：加载顺序可调整，但在处理首个实质性任务前（修改文件、运行项目命令、给出实现结论），必须先完成上述相关上下文加载。
+## 任务入口

-## 规划与执行模型
+### 可直接执行

-> 记号约定：`$<skill-name>` 表示在对话中点名触发的 skill（如
-> `$brainstorming`）；无 `$` 的同名 skill 指其阶段或产物，二者指向同一 skill。
-> `using-superpowers` 是会话启动时判断并加载适用 skill 的入口 skill。
+只读分析、定位、审查，以及不改变行为的局部机械修改可以直接执行，不生成
+spec/tickets。仍须遵守项目规则、验证实际结果，并只处理本次相关改动。

- 规划阶段必须走 `using-superpowers -> brainstorming -> writing-plans`
- `$brainstorming` 必须用第一性原理推导设计：质疑既有假设，拆解到不可再分的
-  基本事实，再从基本事实重新构建方案；禁止仅基于类比、惯例或"业界都这么做"
-  得出结论
- `$brainstorming` 产出 `docs/superpowers/specs/*-design.md`；spec 文件本身即为设计留痕，
-  并须显式列出关键假设及其依据，便于后续审查
- `$writing-plans` 产出 `docs/superpowers/plans/*.md`；写出 plan 后立即用
-  `playbook.py -record-plan` 追加到 `memory-bank/progress.md` 的
-  `plan-status` 队列，初始状态为 `pending`
- spec/plan 产出阶段不单独提交或归档，只做文件落地与 Plan 入队；如外部 skill
-  要求写完后立即提交，以本文件为准，推迟到 Plan 完成后统一处理
- Plan 生命周期由 `main_loop.py` 协调，通过 `memory-bank/progress.md` 留痕
- Plan 执行入口只能是主循环：领取前不得进入 `$executing-plans`，领取后默认用
-  `$executing-plans` 执行，`$subagent-driven-development` 仅在 Plan 或平台明确要求时使用
- 代码类执行必须同时遵循 `$karpathy-guidelines`、`.agents/`、`AGENT_RULES.md`
- 执行完成后按「Plan 完成归档契约」收尾
+### 新 feature 或设计变更

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

-以下 skill 是额外能力，只在满足触发条件时使用，不改变主流程顺序，
-也不由 `main_loop.py` 自动调度：
+### 已明确预期行为的 bug

-| Skill              | 触发条件                               | 负责范围                               |
-| ------------------ | -------------------------------------- | -------------------------------------- |
-| `codebase-recon`   | 架构、跨模块、重构、迁移或风险不明任务 | 代码库侦察、热点分析、影响面判断       |
-| `brooks-audit`     | 方案影响架构边界、模块职责或长期维护性 | 架构审查、结构风险识别                 |
-| `codebase-migrate` | 大规模迁移、多文件重构、API 替换       | 分批迁移、可审查 refactor、CI 验证节奏 |
-| `brooks-review`    | 代码类 Plan 完成后，归档前需要审查     | diff / PR 级代码审查                   |
-| `brooks-test`      | 测试改动复杂，或需要确认测试质量       | 测试有效性、覆盖边界、断言质量审查     |
-| `gitea-fix-ci`     | Gitea Actions 失败                     | 拉取 CI 日志、定位失败、形成修复计划   |
-| `commit-message`   | 需要提交或归档当前 Plan 改动           | commit message 生成与 staged diff 检查 |
+已知正确行为且可以建立失败反馈回路的 bug，使用 `diagnosing-bugs` 完整执行 Phase 1-6，
+由它负责反馈回路、回归测试、修复、验证和清理，不再进入 `implement` 或重复 `tdd`，也不为
+已确定的需求重新 grilling。若诊断暴露新的产品取舍、架构方向或缺失测试 seam，停止修复并
+转入 `grill-with-docs`。若 bug 来自已领取 ticket，Phase 6 后直接继续本地 ticket 执行协议的
+提交、review 和 finish 门禁。

-### Plan 要求
+## 正式工程主链

- `Plan Meta` 必填，位于 Plan 头部 `---` 之后、Task 1 之前
- `Plan Meta` 至少包含：
-  - `Verification Scope`
-  - `Verification Gate`
- Plan 不得包含必然失败或未确认的内容；未确认项须在 `$brainstorming`
-  阶段解决后才能产出 Plan
- Plan 内验证必须是当前阶段可通过的局部验证；跨 Plan 的集成验证自成一个独立 Plan
- 每个 Plan 应自身可独立交付，不依赖其他 Plan 的执行结果；有先后顺序的工作
-  放入同一 Plan 的有序 Task，不跨 Plan 表达执行依赖
- 不因等待确认而中断可执行步骤；待确认事项写入回复
- 每个 Plan 应小步、可验证、可快速完成
+新 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-me` 只用于无仓库的一次性讨论
+- 进入 `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`

- 常规模式：`执行主循环`、`继续执行`、`下一个 Plan`
- 无交互模式：`自动执行所有 Plan`
+## On-ramps 与 detours

-### Plan 状态
+- 超过单个 session 可容纳的巨大、模糊工作先走 `wayfinder`；决策地图清晰后进入
+  `to-spec -> to-tickets`，不得从决策 ticket 直接跳到实现
+- `research` 产出的高可信一手来源报告先进入 `grill-with-docs`，作为设计输入；调研不能
+  替代 grilling
+- 设计问题需要 runnable answer 时，从原设计会话 `handoff` 到独立目录运行
+  `prototype`，再 `handoff` 结论回原设计会话
+- 已由 `to-tickets` 生成的 ticket 直接从 `main_loop.py claim -> 本地 ticket 执行协议` 开始，
+  不再 triage 或重复需求采访

- `pending`：待执行
- `in-progress`：执行中，用于恢复中断任务
- `done`：已完成
- `blocked`：阻塞，需人工介入或切换环境
- `skipped`：永久跳过，不再执行
+## Phase boundaries

-`skipped` 如需恢复，必须手动改回 `pending`。
+只在阶段边界按以下顺序判断，首个满足项生效：

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

- 格式：`env:<环境>:<Task列表>`
- 示例：`env:windows:Task2,Task4`
- `Task` 列表必须使用英文逗号分隔，且不要包含空格
+上下文过长不等于必须 `handoff`；`handoff` 解决的是可移植性。`compact` 是决策树的默认
+落点，但不是第一选择。`CONTEXT.md` 和 memory-bank 都不能替代阶段上下文。

-### 领取与写回
+## 本地 Ticket 执行协议

-**领取 Plan**：
+这是 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 \
-  -plans docs/superpowers/plans \
-  -progress memory-bank/progress.md \
-  -owner "<当前session或agent标识>"
+  --state-root .scratch --repo-root . \
+  --owner "<owner>" --isolation in-place|worktree|auto
 ```

-该命令在锁保护下完成：自动识别当前环境（windows/linux/darwin）、校验 Plan Meta、优先恢复 `in-progress`、按 `plan-status` 行顺序选择第一个可执行 Plan，并在对应 Plan 行写入 `claimed_by`/`claimed_at`。
+stdout 返回 `FEATURE`、`TICKET`、`CONTROL_ROOT`、绝对 `STATE_ROOT`、`WORKSPACE`、
+`BRANCH`、`BASE` 和 `ISOLATION`：

-stdout 必须包含 `PLAN=<path>`；如为环境恢复，还会附带 `NOTE=env:<环境>:<Task列表>`。
+- `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 finish \
-  -plan <plan> -status done \
-  -progress memory-bank/progress.md \
-  -verified "<本轮已通过的验证命令或证据>"
+python {{PLAYBOOK_SCRIPTS}}/main_loop.py heartbeat \
+  --state-root "<STATE_ROOT>" \
+  --feature <feature> --ticket <NN> --owner "<owner>"

-# 阻塞（环境）
-python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
-  -plan <plan> -status blocked \
-  -progress memory-bank/progress.md \
-  -note "env:<所需环境>:<Task列表>"
-
-# 阻塞/跳过（其他原因）
-python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
-  -plan <plan> -status blocked|skipped \
-  -progress memory-bank/progress.md \
-  -note "<原因>"
+python {{PLAYBOOK_SCRIPTS}}/main_loop.py reclaim \
+  --state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
+  --feature <feature> --ticket <NN> --owner "<new-owner>"
 ```

-**查看状态**（只读，不修改 progress.md）：
+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 status \
-  -plans docs/superpowers/plans \
-  -progress memory-bank/progress.md
+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
-# writing-plans 完成后
-python {{PLAYBOOK_SCRIPTS}}/playbook.py \
-  -record-plan docs/superpowers/plans/<topic>.md \
-  -progress memory-bank/progress.md
+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
 ```

-### Plan 场景下的执行上下文与隔离策略
+release 返回 `ready-for-agent` 并保留 workspace；blocked ticket 可由原 owner release 后恢复。

- 本节仅适用于通过主循环领取并执行 Plan 的场景
- 默认在当前项目上下文直接执行 Plan，不强制创建隔离上下文
- 仅在以下场景使用隔离工作区：
-  - 用户明确要求隔离执行
-  - Plan 文本自身明确要求隔离执行
-  - 当前任务需要并行隔离以避免相互影响
- 如外部技能、工具或默认流程要求先隔离，再执行 Plan，以本文件和用户当前指令为准
+### Feature 集成阻塞

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

-1. 先 `claim`，拿到 `PLAN=` 后再读取 Plan 内容
-2. 如返回 `NOTE=env:...`，本轮只执行列出的 Task
-3. 代码类任务在执行前必须显式加载 `$karpathy-guidelines`
-4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan
-5. 按顺序执行 Task，并完成 Plan 约定的验证
-6. 环境不匹配时，记录所需环境和 Task，继续处理本 Plan
-   其余可执行 Task
-7. 其他阻塞写回 `blocked`；永久放弃写回 `skipped`
-8. 遇到决策点时按「需要确认的场景」处理：常规模式下满足该节
-   条件的先向用户确认；无交互模式按该节自动处理
-9. 每次 `claim` 只领取一个 Plan；写回并归档当前 Plan 变更后
-   再领取下一个
-10. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、
-    环境需求与待确认事项
+```bash
+python {{PLAYBOOK_SCRIPTS}}/main_loop.py block-feature \
+  --state-root "<STATE_ROOT>" --feature <feature> --reason "<明确原因>"

-### Plan 完成归档契约
+python {{PLAYBOOK_SCRIPTS}}/main_loop.py release-feature \
+  --state-root "<STATE_ROOT>" --feature <feature>
+```

-**核心原则**：
+release 后该 feature 重新成为队首 `INTEGRATION_REQUIRED`。后序 feature 即使已开发完成，
+仍不得越过它集成到 main。

- Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个 Plan
- `main_loop.py finish -status done` 只负责写回机器状态，不自动提交或归档，不代表已完成交付
- Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断
+### Feature 顺序集成

-**收尾顺序**：
+feature 必须吸收最新 `main`，完成 feature 验证、main 候选验证和最终双轴 review：

-1. 完成 Plan 约定验证
-2. 运行 `main_loop.py finish -status done -verified "<证据>"` 写回状态
-3. 必要时更新 `progress.md` 上半部分摘要和相关 memory
-4. 检查当前变更清单与差异
-5. 只归档/提交当前 Plan 相关改动
+```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"
+```

-**当前 Plan 相关改动包括**：
+partial feature 还需 `--allow-partial`。返回 `RETRY: feature needs main sync` 时，
+先在 feature integration workspace 合并最新 main；若发生冲突，先 `block-feature`，解决后
+`release-feature`，重新验证和 review 后再调用。

- 本轮代码、配置、测试、模板改动
- 当前 Plan 文件（创建、补充、勾选 Task、记录结果等）
- `memory-bank/progress.md` 中本轮 `plan-status` 与摘要更新
- 必要 memory 更新（如 `active-context.md`、`decisions.md`）
+## 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

- 不得把用户已有改动或其他 Plan/session 的改动混入当前 Plan 交付单元；
-  这类改动只要不属于、不冲突当前 Plan，允许其未归档共存
- 如 Plan `done` 后没有当前 Plan 相关差异，必须在回复中说明无归档原因
- 如当前 Plan 相关差异仍未归档，只能声称「状态已写回，交付未完成」，不得声称 Plan 完成
- `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的局部成果需要保留时才归档
- 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户确认；无交互模式将当前 Plan 写回 `blocked` 并记录冲突，继续领取下一个
+局部 ticket 验证、feature 验证和 main 候选验证是三个独立门禁，不能互相替代。
+证据必须来自实际 fresh run；无法运行时不得伪造 `pass`。

-### 决策与留痕
+## 辅助能力

- 重要决策记录到 `memory-bank/decisions.md`
- 待确认事项在回复中显式列出
- `plan-status` 是唯一机器状态源，只能通过
-  `{{PLAYBOOK_SCRIPTS}}/main_loop.py` 或
-  `{{PLAYBOOK_SCRIPTS}}/playbook.py -record-plan` 维护
- `progress.md` 上半部分是短期状态快照，不是 changelog；
-  阶段变化或执行结束后整理/替换摘要，不做无限追加
- `active-context.md` 是短期上下文快照，不是长期日志；
-  只保留当前 Plan / 下一轮仍重要的目标、变化、文件与下一步
- 同一错误重复两次以上，或发现项目特有规律时，沉淀到
-  `AGENT_RULES.local.md`（决策类记入 `memory-bank/decisions.md`）
+以下能力在对应阶段内按需使用，不替代上面的入口路由和证据门禁：

-### 归档操作
-
- 不改写既有归档历史，除非用户明确要求
- 不覆盖他人或其他 session 的归档成果；如用户坚持，必须先说明风险
- 不跳过项目约定的归档前检查
- 如项目没有归档机制，在回复中列出本轮交付的文件清单与验证证据
+| Skill              | 触发条件                            |
+| ------------------ | ----------------------------------- |
+| `codebase-recon`   | 架构、跨模块、重构、迁移或风险不明  |
+| `brooks-audit`     | 架构边界和长期维护性审查            |
+| `codebase-migrate` | 大规模迁移或宽重构                  |
+| `commit-message`   | 需要检查 staged diff 或生成提交信息 |

 ## 需要确认的场景

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

-执行 Plan 过程中，遇到以下决策点先向用户确认：
+- ticket/spec 仍存在会改变实现的真实歧义
+- 需要 spec 未授权的行为、兼容性或架构取舍
+- 需要破坏性操作、覆盖他人改动或扩大任务范围

- 需求不明确，或存在多种可行方案
- 需要行为、兼容性或性能取舍
- 涉及架构变更、破坏性修改或约束冲突
- 风险较高，且继续执行可能放大返工成本
-
-以下 Plan 改动可直接推进，无需确认：
-
- 明显的 bug 修复
- 符合现有模式的小改动
- 测试用例补充或局部验证补齐
-
-### 无交互模式
-
-严格按 Plan 的 Task 执行，不自行做设计决策；一个 Plan 卡住不影响其余 Plan，
-继续领取下一个，直到所有 Plan 处理完毕：
-
- Task 明确可执行：直接执行
- Task 存在歧义或需要未在 Plan 中确认的设计决策：写回 `blocked`，不猜测、不替代设计
-  （此类决策本应在 `$brainstorming` 阶段解决，缺失说明 Plan 不合格）
- 需要架构变更、破坏性修改，且 Plan 未明确授权：写回 `blocked`
- 环境不匹配：记录 `env:<环境>:<Task列表>`，跳过该 Task，继续本 Plan 其余 Task
-
-每个被 `blocked` 的 Plan 记录原因，继续领取下一个，不因单个 Plan 卡住而中止整批。
+已明确预期行为的 bug 按 `diagnosing-bugs` 路由推进；符合既有模式的小改动、测试补齐和
+已批准 ticket 范围内的实现不重复需求采访。
+无交互模式下不得替用户作设计决策；将 ticket 标记 blocked 并记录原因。

 ## Session 收尾

-出现以下情况时，建议开启新 Session：
-
- 当前方向明显跑偏
- 讨论阶段产出多个候选方案，准备进入执行
- Session 过长，开始重复犯同类错误
-
-## 验证清单
-
-每个 Plan 完成后，至少确认：
-
- [ ] 代码修改符合 `.agents/` 下的规则（如有）
- [ ] 相关验证已执行，且测试在未豁免时通过
- [ ] 换行符与文件格式正确
- [ ] 无语法错误或明显运行时错误
- [ ] 已通过 `main_loop.py finish` 写回 Plan 状态
- [ ] Plan `done` 后已完成当前 Plan 变更归档/提交，或已说明无当前 Plan
-      差异无需归档
+- 运行与声明相匹配的 fresh verification
+- ticket 执行必须通过 `finish` 写回；不得手工改状态
+- 列出已完成、未完成、验证证据、风险和下一步
+- 只提交当前 ticket/feature 相关改动，不混入其他 session 差异
+- 工作未结束时在阶段边界按 Continue -> clear -> handoff -> subagent -> compact 的顺序选择
+  去向；不要仅因上下文过长就创建 handoff

 ---

@@ -1,209 +1,192 @@
 # 项目架构模板

-本目录包含基于 superpowers 工作流的项目模板，用于快速初始化 AI 智能体工作环境。
+本目录包含项目架构与工作流入口模板，以及按需采用的语言配置模板。正式工程主链采用
+Matt Pocock workflow 与 ticket-native 主循环。

 ## 与 Playbook 其他部分的关系

 ```text
 playbook/
-├── rulesets/        # 语言级硬规则 → 部署到 .agents/
-├── skills/          # 按需加载的技能
+├── rulesets/        # 语言级规则模板 -> 通过 sync_standards 部署到 .agents/
+├── skills/          # 按需安装的工作流与知识技能
 ├── docs/            # 权威静态文档
-├── templates/       # 本目录：项目架构模板 → 部署到 memory-bank/ 等
+├── templates/       # 本目录：项目架构与工作流入口模板
 └── scripts/
-    └── playbook.py    # 统一入口
+    └── playbook.py  # 统一部署入口
 ```

-部署方式详见主 README.md 的"在其他项目中使用本 Playbook"章节。
+`templates/` 负责生成或更新 `AGENTS.md`、`AGENT_RULES.md` 和 `memory-bank/` 等项目
+入口与知识文件；`memory-bank/` 不承载新流程机器状态。完整部署方式见
+[主 README 的“在其他项目中使用本 Playbook”章节](../README.md#在其他项目中使用本-playbook)。

-## 目录结构
+## 目录

 ```text
 templates/
-├── AGENTS.template.md           # 入口导航模板
-├── AGENT_RULES.template.md      # superpowers 执行规则模板
-├── memory-bank/                 # 项目上下文模板（6 个）
-├── prompts/                     # 任务入口模板（6 个 + README）
-├── ci/                          # CI 配置模板
+├── AGENTS.template.md           # 项目主入口与导航模板
+├── AGENT_RULES.template.md      # Matt Pocock ticket-native 执行规则模板
+├── memory-bank/                 # 稳定项目知识模板（3 个），不是机器状态源
 ├── cpp/                         # C++ 工具链模板
 └── python/                      # Python 工具链模板
 ```

+完整主链只在 `AGENT_RULES.template.md` 定义。
+
 ## 模板分类

-从部署和维护角度，模板分为三类：
+从部署和维护职责看，本目录中的模板分为三类。

-### 1. 框架模板（会自动更新）
+### 1. 入口导航

-这些文件由 playbook 框架维护，每次同步时可能更新：
+- `AGENTS.md`、`CLAUDE.md` 通过 Playbook 标记区块维护
+- 更新标记区块时保留区块外的项目内容
+- 已有的人工入口和项目补充说明继续由项目维护

- `AGENT_RULES.md`
- `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新）
- `docs/prompts/README.md`
- `docs/prompts/system/*.md`
- `docs/prompts/coding/*.md`
+### 2. 初始化后由项目维护

-### 2. 项目上下文（首次创建后由项目维护）
+- `AGENT_RULES.md`：项目采用的完整工程流程与执行规则
+- `AGENT_RULES.local.md`：项目私有规则，Playbook 不覆盖
+- `memory-bank/`：稳定项目定位、技术上下文和当前系统模式，不承载机器状态

-这些文件首次创建后应由项目填写，`force=true` 会覆盖已填写内容并先备份：
+Playbook 只处理框架提供的同名文件。项目新增的 `memory-bank/*` 不会被删除。

- `memory-bank/*.md`
- `AGENT_RULES.local.md`（首次自动创建，后续不再覆盖）
+### 3. 参考模板

-### 3. 参考模板（需手动复制）
+这些模板保留在快照中，按项目需要手动采用：

-这些模板保留在快照中供参考，需手动复制到项目根目录：
-
- `ci/`：Gitea Actions 工作流
- `cpp/`：C++ 工具链配置
- `python/`：Python 工具链配置
-
-**补充说明**：
-
- `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*` 不会被 playbook 删除
- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用 `@AGENTS.md` 则追加；如已手工引用则跳过
- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/` 只负责把智能体导向正确的任务入口
-
-## 部署方式
-
-使用 `playbook.py` 统一入口部署，通过配置节控制同步内容：
-
-```toml
-# playbook.toml
-[sync_rules]           # 同步 AGENT_RULES.md
-[sync_memory_bank]     # 同步 memory-bank/
-[sync_prompts]         # 同步 docs/prompts/
-```
-
-详细配置说明见主 README.md 和 playbook.toml.example。
+- `cpp/`：C++、CMake 和 Conan 工具链模板
+- `python/`：Python 工具链配置模板

 ## 模板说明

 ### memory-bank/

-项目上下文文档，用于让 AI 快速理解项目：
+`memory-bank/` 保存 grilling、设计和实现都需要的稳定项目知识。它不记录 owner、
+heartbeat、ticket 或集成状态；机器状态只以 `.scratch/` 和 `main_loop.py` 为准。

-| 文件                          | 用途                       |
-| ----------------------------- | -------------------------- |
-| `project-brief.template.md`   | 项目定位、边界、约束       |
-| `tech-context.template.md`    | 技术上下文、工具链、入口   |
-| `system-patterns.template.md` | 系统模式、边界、不变量     |
-| `active-context.template.md`  | 当前目标、最近变更、下一步 |
-| `progress.template.md`        | 人类摘要 + Plan 状态块     |
-| `decisions.template.md`       | 架构决策记录（ADR）        |
-
-### prompts/
-
-任务入口模板，部署后去掉 `.template` 后缀。`prompts/README.md` 作为任务入口索引。
-
-| 文件                                | 用途         | 使用场景            |
-| ----------------------------------- | ------------ | ------------------- |
-| `system/agent-behavior.template.md` | 入口路由模板 | 选择执行路径        |
-| `coding/clarify.template.md`        | 需求澄清模板 | 需求不明确时        |
-| `coding/verify-change.template.md`  | 变更验证模板 | 声称完成前验证      |
-| `coding/close-task.template.md`     | 本轮收尾模板 | 一轮工作结束时      |
-| `coding/update-memory.template.md`  | 回写记忆模板 | 上下文变化后回写    |
-| `coding/code-review.template.md`    | 代码评审入口 | 执行 MR/PR 代码评审 |
+| 文件                          | 用途                                           |
+| ----------------------------- | ---------------------------------------------- |
+| `project-brief.template.md`   | 项目定位、边界、约束和成功定义                 |
+| `tech-context.template.md`    | 技术栈、仓库入口、工具链、平台差异和验证命令   |
+| `system-patterns.template.md` | 稳定模块边界、数据流、不变量、扩展路径和禁止项 |

 ### AGENT_RULES.template.md

-执行规则模板，定义 AI 的工作循环和约束。如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]` 首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 playbook 覆盖。
-
-计划编排与执行细节统一指向 `docs/superpowers/`、`playbook.py -record-plan` 与 `main_loop.py claim/finish`。
+部署为项目的 `AGENT_RULES.md`，是 Matt Pocock 工程主链、ticket 调度、worktree、
+验证和集成协议的唯一流程权威。项目私有规则写入 `AGENT_RULES.local.md`；该文件由
+项目维护，Playbook 不覆盖。

 ### AGENTS.template.md

-入口导航模板，作为项目的主入口（Codex 入口）。
+部署为项目的 `AGENTS.md`，只提供语言规则、核心规则和工程上下文导航。
+标记区块的更新约束见下文“AGENTS 模板标记”。

-**设计理念**：
+## 部署

- **最小化内容**：只包含导航链接，不包含详细规则
- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块
+```toml
+[sync_rules]

-**playbook 标记**（用于自动更新）：
+[sync_memory_bank]
+project_name = "MyProject"

- `<!-- playbook:agents:start/end -->`：语言规则链接，由 `[sync_standards]` 管理
- `<!-- playbook:templates:start/end -->`：路由链接，`AGENTS.md` 始终按区块更新
- `<!-- playbook:framework:start/end -->`：完整框架，`AGENTS.md` 始终按区块更新
+[sync_standards]
+langs = ["python"]

-### superpowers 工作流约定
+[install_skills]
+mode = "all"
+```

-`docs/superpowers/` 统一承载设计稿和实施计划：
+部署后首次使用正式流程时运行 `setup-matt-pocock-skills`，并为本地主循环选择
+local markdown tracker。

- **设计稿**：`specs/YYYY-MM-DD-<topic>-design.md`（`brainstorming` 产出）
- **实施计划**：`plans/YYYY-MM-DD-<topic>.md`（`writing-plans` 产出）
- **执行状态**：回写到 `memory-bank/progress.md`
+## 正式开发流程

-其中 `plans/` 为主执行入口；`specs/` 只作为设计背景和上游文档。
+```text
+setup-matt-pocock-skills
+  -> grill-with-docs
+  -> to-spec
+  -> to-tickets
+  -> main_loop.py enqueue
+  -> main_loop.py claim
+  -> implement + tdd
+  -> commit
+  -> code-review
+  -> main_loop.py finish
+  -> main_loop.py integrate
+```

-**生命周期**：
+产物和职责：

- `docs/prompts/`：任务入口层，只负责把智能体导向正确入口
- `docs/superpowers/specs/`：设计稿
- `docs/superpowers/plans/`：实施计划与主执行输入
- `memory-bank/progress.md`：执行状态留痕
+- `.scratch/<feature>/spec.md`：feature spec
+- `.scratch/<feature>/issues/*.md`：ticket DAG 与执行状态
+- `.scratch/queue.md`：feature 开发和集成顺序
+- `CONTEXT.md`：稳定领域词汇
+- `docs/adr/`：长期架构决策
+- `docs/agents/*.md`：tracker 与领域文档配置

-完整主链只在 `AGENT_RULES.template.md` 定义。
+明确串行时可用 in-place，不创建 worktree；计划多个 session 并发时，第一个 claim
+就指定 worktree。并发 sessions 必须共享同一文件系统与 Git common directory；
+`main_loop.py` 不支持跨机器、独立 clone 或远程 tracker adapter。Matt skills 可单独
+使用远程 issue tracker，但不能把远程状态接入本主循环。完整隔离、恢复和证据协议见
+`AGENT_RULES.template.md`。

-### 语言配置模板（ci/、cpp/、python/）
+## AGENTS 模板标记

-语言和 CI 配置模板，`install_mode = "snapshot"` 安装快照时会复制这些模板：
+- `<!-- playbook:framework:start/end -->`：完整框架区块
+- `<!-- playbook:agents:start/end -->`：语言规则入口
+- `<!-- playbook:templates:start/end -->`：项目流程入口

- `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt` 等文件，部署到快照 `templates/cpp/`
- `python/`：`pyproject.toml`、`.editorconfig` 等文件，部署到快照 `templates/python/`
+`playbook:agents` 必须嵌在 `playbook:framework` 内。框架区块替换时，
+`preserve_agents_subblock()` 依赖该嵌套保留项目按 `langs` 生成的语言入口。

-**使用方式**：这些模板保留在快照中供参考，需手动复制到项目根目录使用。
+## 占位符

-## 技术细节
+模板同时包含部署工具自动替换的占位符和需要项目手工填写的内容：

-### 占位符说明
+| 占位符                    | 说明                   | 自动替换                     |
+| ------------------------- | ---------------------- | ---------------------------- |
+| `{{DATE}}`                | 同步日期               | 是                           |
+| `{{PROJECT_NAME}}`        | 可选项目名             | 配置 `project_name` 时替换   |
+| `{{PLAYBOOK_ROOT}}`       | 项目内 Playbook 根目录 | 是                           |
+| `{{PLAYBOOK_SCRIPTS}}`    | 项目内脚本目录         | 是                           |
+| `{{PROJECT_GOAL}}`        | 项目目标               | 否，项目手工填写             |
+| `{{PROJECT_DESCRIPTION}}` | 项目描述               | 否，项目手工填写             |
+| 其他 `{{...}}`            | 模板中的项目特定内容   | 否，项目手工填写或删除所在行 |

-模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值：
+`{{PROJECT_NAME}}` 由 `[sync_memory_bank].project_name` 提供；未配置时保持原样。
+其他人工占位符不会由 `playbook.py` 推导。

-| 占位符                    | 说明         | 自动替换 |
-| ------------------------- | ------------ | -------- |
-| `{{DATE}}`                | 日期         | ✅ 是    |
-| `{{PROJECT_NAME}}`        | 项目名称     | ✅ 可选  |
-| `{{PLAYBOOK_ROOT}}`       | Playbook 根  | ✅ 是    |
-| `{{PLAYBOOK_SCRIPTS}}`    | 脚本路径     | ✅ 是    |
-| `{{PROJECT_GOAL}}`        | 项目目标     | ❌ 手动  |
-| `{{PROJECT_DESCRIPTION}}` | 项目描述     | ❌ 手动  |
-| 其他 `{{...}}`            | 项目特定内容 | ❌ 手动  |
-
- `{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；未配置时保持原样
- `{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录（默认 `docs/standards/playbook`）
- `{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径（默认 `docs/standards/playbook/scripts`）
-
-### 部署后的目录结构
+## `playbook.py` 部署后结构

 ```text
 project/
-├── AGENTS.md              # 入口导航（Codex 入口）
-├── AGENT_RULES.md         # superpowers 执行规则
-├── AGENT_RULES.local.md   # 项目私有规则（自动创建，项目维护）
-├── CLAUDE.md              # Claude Code 入口
-├── memory-bank/           # 项目上下文
-│   ├── project-brief.md
-│   ├── tech-context.md
-│   ├── system-patterns.md
-│   ├── active-context.md
-│   ├── progress.md
-│   └── decisions.md
+├── AGENTS.md                    # 任一 sync_* 节启用时创建或按区块更新
+├── AGENT_RULES.md               # [sync_rules]
+├── AGENT_RULES.local.md         # 首次成功写入规则时创建，后续由项目维护
+├── CLAUDE.md                    # 默认位置；也可使用 .claude/CLAUDE.md
+├── .agents/                     # [sync_standards]
+├── .gitattributes               # [sync_standards] 按配置同步
+└── memory-bank/                 # [sync_memory_bank] 部署三个稳定知识文件
+```
+
+`[install_skills]` 安装到 `agents_home/skills/`，通常不在项目目录内。`mode = "list"`
+要求用户逐项列出 skills 及其依赖；`mode = "all"` 安装全部 skills。
+
+## 正式流程运行后按需产生的结构
+
+```text
+project/
+├── CONTEXT.md                     # setup 后按需创建的稳定领域词汇
+├── .scratch/
+│   ├── queue.md                   # main_loop.py 维护的 feature 顺序
+│   └── <feature>/
+│       ├── spec.md                # to-spec 产物
+│       └── issues/                # to-tickets 产物与机器状态
 └── docs/
-    ├── prompts/           # 任务入口层
-    │   ├── README.md
-    │   ├── system/agent-behavior.md
-    │   └── coding/
-    │       ├── clarify.md
-    │       ├── verify-change.md
-    │       ├── close-task.md
-    │       ├── update-memory.md
-    │       └── code-review.md
-    └── superpowers/
-        ├── specs/         # brainstorming 产物
-        └── plans/         # writing-plans / main_loop 消费
+    ├── agents/                    # setup 生成的 tracker/domain 配置
+    └── adr/                       # grilling 过程中按需沉淀的长期决策
 ```

 ---

-**最后更新**：2026-06-17
+**最后更新**：2026-08-07
@@ -1,53 +0,0 @@
-# 当前上下文
-
-<!--
-填写指南：
- 本文件记录高频变化的上下文，供 AI 在跨 Session 时快速恢复工作状态
- 本文件是短期上下文快照，不是长期日志
- 保持简洁，只写“现在仍然重要”的信息
- `Recent Changes` 只保留最近 3-5 条仍影响后续判断的变化
- `Touched Files` 只保留当前 Plan / 下一轮仍相关的文件
- `Next Steps` 只保留接下来最优先的 1-3 步
- 更新时整理/替换旧上下文，不做无限追加
- 任务完成或方向切换后及时更新
-->
-
-## Current Goal
-
-<!-- 当前最重要的目标；一句话即可 -->
-
- {{CURRENT_GOAL}}
-
-## Recent Changes
-
-<!-- 最近完成且会影响后续判断的变更 -->
-
- {{RECENT_CHANGE_1}}
-
-## Touched Files
-
-<!-- 最近修改或正在关注的关键文件 -->
-
- `{{FILE_1}}` - {{FILE_1_REASON}}
-
-## Open Questions
-
-<!-- 尚未确认、但会影响实现或验证的事项 -->
-
- {{QUESTION_1}}
-
-## Next Steps
-
-<!-- 接下来最优先的 1-3 步 -->
-
-1. {{NEXT_STEP_1}}
-
-## Session Notes
-
-<!-- 只记录本轮最容易忘的上下文 -->
-
- {{SESSION_NOTE_1}}
-
---
-
-**最后更新**：{{DATE}}
@@ -1,33 +0,0 @@
-# 架构决策记录
-
-<!--
-填写指南：
- 本文件记录重要架构决策，使用 ADR 格式
- 初始可为空，遇到重要决策时由 AI 或人工添加
- 每个决策使用下方模板
-->
-
-## ADR 模板
-
-```markdown
-## ADR-XXX: 决策标题
-
-**日期**: YYYY-MM-DD
-**状态**: 已采纳 / 已废弃 / 待讨论
-
-### 决策
-
-简要描述决策内容
-
-### 理由
-
-为什么做出这个决策
-
-### 影响
-
-对项目的影响
-```
-
---
-
-**最后更新**：{{DATE}}
@@ -1,44 +0,0 @@
-# 当前进展
-
-<!--
-填写指南：
- 上半部分给人类和 AI 快速恢复上下文
- 上半部分是短期状态快照，不是 changelog
- `Recent Changes` 只保留最近 3-5 条对恢复上下文有价值的变化
- 更新摘要时整理/替换旧摘要，不做无限追加
- 下半部分的 plan-status 块由 main_loop.py 维护，是唯一机器状态源
-->
-
-## Current Focus
-
- {{CURRENT_FOCUS}}
-
-## Recent Changes
-
- {{RECENT_CHANGE_1}}
-
-## Next Steps
-
-1. {{NEXT_STEP_1}}
-
-## Open Risks
-
- {{RISK_1}}
-
-## 状态块示例
-
-以下示例仅用于说明结构，真实状态由 `main_loop.py` 维护：
-
-```text
-## Plan Status
-<!-- plan-status:start -->
- [ ] `2026-05-18-demo.md` pending
- [ ] `2026-05-19-next.md` in-progress: claimed_by: codex; claimed_at: 2026-05-19T08:00:00Z
- [x] `2026-05-20-done.md` done: verified: python -m unittest
-<!-- plan-status:end -->
-```
-
-## Plan Status
-
-<!-- plan-status:start -->
-<!-- plan-status:end -->
@@ -1,55 +0,0 @@
-# 提示词入口
-
-本目录包含 AI 智能体的任务入口模板，用于把任务路由到合适的执行路径。
-它是薄入口层，不是流程权威；完整流程与执行约束只在
-`AGENT_RULES.md` 定义。
-
-## 目录结构
-
-```text
-prompts/
-├── README.md              # 本文件
-├── system/
-│   └── agent-behavior.md  # 入口路由
-├── coding/
-│   ├── clarify.md         # 需求澄清模板
-│   ├── verify-change.md   # 变更验证模板
-│   ├── close-task.md      # 本轮收尾模板
-│   ├── update-memory.md   # 回写记忆模板
-│   └── code-review.md     # MR/PR 代码评审入口
-└── custom/                # 可选：项目私有提示词
-```
-
-## 使用方式
-
-| 模板                  | 触发场景             |
-| --------------------- | -------------------- |
-| **agent-behavior.md** | 选择任务入口         |
-| **clarify.md**        | 需求不明确时澄清     |
-| **verify-change.md**  | 声称完成前做验证     |
-| **close-task.md**     | 本轮工作收尾         |
-| **update-memory.md**  | 上下文变化后回写记忆 |
-| **code-review.md**    | 执行 MR/PR 代码评审  |
-| **custom/\*.md**      | 项目私有补充入口     |
-
-## 入口边界
-
- 需求不明确：看 `clarify.md`
- 需要判断设计、计划或执行路径：先回到 `AGENT_RULES.md`
- 需要验证交付结果：看 `verify-change.md`
- 需要结束本轮并整理交付摘要：看 `close-task.md`
- 需要回写上下文：看 `update-memory.md`
- 需要评审 MR/PR：看 `code-review.md`
- 需要保留设计与计划产物：只写入 `docs/superpowers/`
-
-> `coding/` 下是可被框架覆盖更新的标准入口模板；
-> 项目私有补充入口应沉淀到 `custom/`。
->
-> `prompts/` 只负责把智能体导向正确入口；`AGENT_RULES.md`
-> 是唯一流程权威；`AGENT_RULES.local.md` 保存项目私有规则；
-> `memory-bank/` 保存项目上下文与状态；`docs/superpowers/`
-> 保存设计与计划产物。
-
---
-
-**最后更新**：{{DATE}}
@@ -1,54 +0,0 @@
-# 需求澄清模板
-
-<!--
-用途：当需求存在歧义时，只补齐会改变实现或验证路径的最小信息。
-触发：需求不明确、存在两种以上合理实现路径、缺少关键约束时。
-->
-
-## 何时使用
-
- 需求描述不明确
- 存在多种合理理解方式
- 缺少会改变实现路径的关键信息
-
-## 先读
-
- `AGENT_RULES.md`
- `memory-bank/project-brief.md`
- `memory-bank/active-context.md`
-
-## 规则
-
- 每轮最多问 1 个问题
- 只问会改变实现或验证路径的问题
- 能低风险继续时，优先给出默认项后推进
- 不重复询问已能从上下文推断的信息
-
-## 澄清步骤
-
-1. 用自己的话复述当前理解
-2. 识别真正影响实现路径的歧义点
-3. 只提出 1 个最高价值问题
-4. 给出推荐默认项和理由
-
-## 输出协议
-
-```markdown
-## Current Understanding
- ...
-
-## Open Question
- ...
-
-## Recommended Default
- ...
-```
-
-## 停止条件
-
- 已有足够信息可低风险推进时停止提问
- 问题不影响实现路径时停止提问
-
---
-
-**最后更新**：{{DATE}}
@@ -1,75 +0,0 @@
-# 收尾模板
-
-<!--
-用途：一轮实现或一个 Plan 结束后形成可交付摘要，并把下一轮仍重要的信息留痕。
-触发：准备结束当前任务、切换上下文、交付结果前。
-->
-
-## 目标
-
-确认当前任务已经形成可交付结果，并把后续工作所需的信息留痕。
-
-## 先读
-
- `AGENT_RULES.md`
- `memory-bank/active-context.md`
- `memory-bank/progress.md`
-
-## 规则
-
- 如本轮来自 `main_loop.py claim` 且任务状态变更，优先通过
-  `main_loop.py finish` 留痕
- 如本轮来自 `main_loop.py claim` 且结果为 `done`，`finish` 之后还必须
-  完成当前 Plan 变更归档/提交；未归档不得声明 Plan 完成
- 未验证内容必须显式说明
- 只写对下一轮仍重要的信息
- 不手工改写 `plan-status` 状态块
-
-## 执行步骤
-
-1. 核对已完成项与未完成项
-2. 核对已运行验证与未运行验证
-3. 如本轮来自 `main_loop.py claim`，核对 `main_loop.py finish`
-   是否已经写回 `plan-status`
-4. 如需回写上下文，更新 `active-context`、`progress` 上半部分和 `decisions`
-5. 如本轮来自 `main_loop.py claim` 且结果为 `done`，按项目归档机制只归档
-   当前 Plan 相关差异
-6. 复核剩余差异是否属于其他 session / 其他 Plan，且未混入本轮交付单元
-7. 输出本轮摘要与下一步
-
-## 状态留痕复核
-
- 如本轮来自 `main_loop.py claim`，`main_loop.py finish` 是否已经写回
-  `plan-status`
- 如本轮来自 `main_loop.py claim` 且结果为 `done`，当前 Plan 相关差异
-  是否已经归档/提交，或是否已说明无当前 Plan 差异
-
-## 输出协议
-
-```markdown
-## Completed
- ...
-
-## Not Completed
- ...
-
-## Verification
- ...
-
-## Risks
- ...
-
-## Next Steps
- ...
-```
-
-## 停止条件
-
- 如已领取 Plan 但状态未写回，先完成留痕再收尾
- 如当前 Plan 结果为 `done` 但相关差异未归档/提交，停止并完成归档；
-  只能报告“状态已写回，交付未完成”
- 如验证不足以支持交付，停止并标记风险
-
---
-
-**最后更新**：{{DATE}}
@@ -1,57 +0,0 @@
-# Code Review 入口
-
-## 触发场景
-
-收到 MR/PR 需要评审时。
-
-## 准备
-
-切换到对应分支并获取变更内容：
-
-```bash
-# GitLab
-glab mr checkout <MR_ID>
-glab mr view <MR_ID> | cat
-glab mr diff <MR_ID> | cat
-
-# GitHub
-gh pr checkout <PR_NUMBER>
-gh pr view <PR_NUMBER>
-gh pr diff <PR_NUMBER>
-```
-
-## 审查顺序
-
-1. 先理解业务目标；目标不明确先要求补足上下文
-2. 优先审查 bug、风险、回归和缺失测试
-3. 再审查代码清晰度、KISS 和单一职责
-4. 最后汇总剩余风险与待确认项
-
-## 规则
-
- Findings 优先，按严重度排序
- 每条结论必须附文件路径、行号或可复现依据
- 没有证据的问题按待确认假设处理
- 评审不只看 diff，需结合代码库整体上下文
-
-## 输出协议
-
-```markdown
-## Findings
-1. [severity] path - issue
-
-## Open Questions
- ...
-
-## Residual Risk
- ...
-```
-
-## 停止条件
-
- 目标不明时停止并要求补足上下文
- 缺少 diff 或无法读取关键上下文时停止并说明
-
---
-
-**最后更新**：{{DATE}}
@@ -1,93 +0,0 @@
-# 回写记忆模板
-
-<!--
-用途：在任务完成、方向切换或发现新规律后更新 memory-bank。
-触发：完成一轮实现、形成新决策、当前焦点变化时。
-->
-
-## 什么时候需要回写
-
- 当前目标已经变化
- 最近改动会影响下一轮判断
- 发现新的系统模式或约束
- 做出了值得保留的决策
-
-## 先读
-
- `memory-bank/active-context.md`
- `memory-bank/progress.md`
- `memory-bank/decisions.md`
- `memory-bank/system-patterns.md`
-
-## 回写目标
-
-### `memory-bank/active-context.md`
-
- 当前目标
- 最近变更
- touched files
- 下一步
- 本文件是短期上下文快照，不是长期日志
- `Recent Changes` 只保留最近 3-5 条仍影响后续判断的变化
- `Touched Files` 只保留当前 Plan / 下一轮仍相关的文件
- `Next Steps` 只保留接下来最优先的 1-3 步
- 更新时整理/替换旧上下文，不做无限追加
-
-### `memory-bank/progress.md`
-
- 读取 `plan-status`：Plan 队列与机器状态
- 只更新上半部分的人类摘要，不修改状态块
- 上半部分是短期状态快照，不是长期日志
- `Recent Changes` 只保留最近 3-5 条对恢复上下文有价值的变化
- 更新时整理/替换旧摘要，不要把 `Recent Changes` 当作无限追加日志
-
-### `memory-bank/decisions.md`
-
- 为什么这样做
- 备选方案是什么
- 影响范围是什么
-
-### `memory-bank/system-patterns.md`
-
- 模块边界
- 不变量
- 扩展路径
- 禁止破坏的约束
-
-## 规则
-
- 只回写长期有价值的信息
- 临时聊天内容不要写进去
- 高变化信息放 `active-context`，稳定技术模式放 `system-patterns`
- 流程规则或项目私有约束变更写入 `AGENT_RULES.local.md`
- `progress.md` 的 `plan-status` 状态块只由 `main_loop.py` 或
-  `playbook.py -record-plan` 维护
- 摘要应与 `plan-status` 保持一致
- 摘要区保持短期状态快照；长期历史依赖项目归档记录、Plan 文件和
-  `decisions.md`
-
-## 禁止事项
-
- 手工改写 `<!-- plan-status:start/end -->`
- 把临时聊天内容、未验证猜测写进摘要
-
-## 输出协议
-
-```markdown
-## Updated Files
- ...
-
-## New Context
- ...
-
-## Outstanding Risks
- ...
-```
-
-## 停止条件
-
- 如果没有值得沉淀的信息，则停止并说明
-
---
-
-**最后更新**：{{DATE}}
@@ -1,73 +0,0 @@
-# 变更验证模板
-
-<!--
-用途：在声明“完成 / 修复 / 可交付”前，用 fresh run 证明改动成立。
-触发：代码、配置、模板、规则修改后；准备交付结果前。
-->
-
-## 验证目标
-
- 这次改动要证明什么
- 哪些行为必须通过
- 哪些验证本轮不做
-
-## 先读
-
- `AGENT_RULES.md`
- `memory-bank/progress.md`
- 如存在：`docs/prompts/custom/verify.md`
-
-## 规则
-
- 没有证据，不宣称完成
- 验证命令必须 fresh run
- 局部修改优先局部验证
- 不能运行的验证必须写明原因
- 不手工改写 `plan-status` 状态块
- 如本轮来自 `main_loop.py claim`，验证通过不等于 Plan 完成；Plan
-  `done` 还必须完成当前 Plan 变更归档/提交
-
-## 验证步骤
-
-1. 做语法或结构检查，确认改动文件可读、可解析
-2. 运行与本次改动直接相关的验证命令
-3. 记录命令、结果和关键输出
-4. 复核 diff 是否只包含预期修改
-5. 如本轮来自 `main_loop.py claim`，复核 `plan-status` 与当前声明一致
-6. 如本轮来自 `main_loop.py claim` 且结果为 `done`，复核当前 Plan
-   相关差异是否已经归档/提交；未归档时只能声明“验证完成”，
-   不能声明“Plan 完成”
-7. 汇总未覆盖项和剩余风险
-
-## 输出协议
-
-```markdown
-## Validated
- ...
-
-## Evidence
- ...
-
-## Not Validated
- ...
-
-## Risks
- ...
-```
-
-## 状态留痕复核
-
- 如本轮来自 `main_loop.py claim`，`plan-status` 是否已经通过
-  `main_loop.py finish` 写回
- 如本轮来自 `main_loop.py claim` 且结果为 `done`，当前 Plan 相关差异
-  是否已经归档/提交，或是否已说明无当前 Plan 差异
-
-## 停止条件
-
- 关键验证失败时停止并汇报
- 当前 Plan 相关差异未归档/提交时，不得声明 Plan 完成
- 证据不足以支持“完成”结论时停止并汇报
-
---
-
-**最后更新**：{{DATE}}
@@ -1,28 +0,0 @@
-# 任务入口路由
-
-<!--
-本文件不重复定义核心规则；它只负责把任务路由到合适的任务入口。
-验证要求、主循环规则见 AGENT_RULES.md。
-->
-
-## 路由原则
-
- 需求不明确：先看 `docs/prompts/coding/clarify.md`
- 需要判断设计、计划或执行路径：先回到 `AGENT_RULES.md`
- 需要确认改动是否站得住：看 `docs/prompts/coding/verify-change.md`
- 一轮工作收尾：看 `docs/prompts/coding/close-task.md`
- 需要更新上下文：看 `docs/prompts/coding/update-memory.md`
- 需要评审 MR/PR：看 `docs/prompts/coding/code-review.md`
-
-## 边界说明
-
- `prompts/` 是入口，不是规则权威
- 完整流程与执行约束只在 `AGENT_RULES.md`
- 项目私有规则写入 `AGENT_RULES.local.md`
- 设计产物只放 `docs/superpowers/specs/`
- 计划产物只放 `docs/superpowers/plans/`
- 项目上下文与执行状态写入 `memory-bank/`
-
---
-
-**最后更新**：{{DATE}}