csh/playbook

Fork 0

Files

T

csh 34a3a5dec1 ♻️ refactor(agent): streamline skills and rulesets

2026-08-11 14:56:21 +08:00

18 KiB

Raw Blame History

AGENT_RULES

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

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

优先级

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

沟通原则

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

项目边界

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

会话启动

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

AGENT_RULES.local.md
.agents/index.md
memory-bank/project-brief.md
memory-bank/tech-context.md
memory-bank/system-patterns.md
docs/agents/issue-tracker.md
docs/agents/domain.md
CONTEXT.md 或 CONTEXT-MAP.md
相关 docs/adr/
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 或设计变更使用以下顺序：

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

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

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

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

本地 Ticket 执行协议

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

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

读取已领取 ticket 的 spec、ticket、相关稳定知识和 ADR
在已确认 seam 上按 tdd 完成 ticket 的可观察行为，并运行局部验证
提交全部实现，使 ticket branch HEAD 成为固定、干净的审查点
运行 code-review，显式提供 fixed point 和 Review 适配契约规定的需求来源
修复硬 finding 后重新提交、验证和 review，直到两个 axis 均满足 pass 条件
调用 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/ 当成同一队列。

主循环命令

入队和状态

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。

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。

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 不能替代结构化证据。

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。

其他转换：

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 分配开发工作：

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：

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 与证据门禁

每个 ticket 使用 ticket/<feature>/<NN>-<slug> branch
每个 feature 使用 feature/<feature> branch
按 TDD 完成一个可观察行为切片并运行局部验证
提交全部实现，使 HEAD 成为可审查固定点
首次以 claim 的 BASE 运行 code-review；同步推进后的 feature 时改用新的 FEATURE_HEAD
修复 finding 后重新提交、验证和 review
finish 校验验证/review commit、review base 和 feature HEAD，再集成 ticket
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}}

18 KiB Raw Blame History Unescape Escape