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

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

templates/
├── AGENTS.template.md           # 项目主入口与导航模板
├── AGENT_RULES.template.md      # Matt Pocock ticket-native 执行规则模板
├── gitignore.template           # .scratch 持久状态与本机运行时忽略规则
├── memory-bank/                 # 稳定项目知识模板（3 个），不是机器状态源
├── cpp/                         # C++ 工具链模板
└── python/                      # Python 工具链模板

完整主链只在 AGENT_RULES.template.md 定义。

模板分类

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

1. 入口导航

AGENTS.md、CLAUDE.md 通过 Playbook 标记区块维护
更新标记区块时保留区块外的项目内容
已有的人工入口和项目补充说明继续由项目维护

2. 流程由 Playbook 维护，补充由项目维护

AGENT_RULES.md： 区块内的工程流程由 Playbook 维护，重新同步时刷新；项目自己的补充写在区块外，同步不会动它
AGENT_RULES.local.md：项目私有规则，Playbook 不覆盖
.gitignore：Playbook 维护专属标记区块，仅忽略 .scratch 下的本机运行时产物
memory-bank/：稳定项目定位、技术上下文和当前系统模式，不承载机器状态

Playbook 只处理框架提供的同名文件。项目新增的 memory-bank/* 不会被删除。没有标记区块的旧 AGENT_RULES.md 保持原样，不会被静默改写。

3. 参考模板

这些模板保留在快照中，按项目需要手动采用：

cpp/：C++、CMake 和 Conan 工具链模板
python/：Python 工具链配置模板

模板说明

memory-bank/

memory-bank/ 保存 grilling、设计和实现都需要的稳定项目知识。它不记录 owner、 heartbeat、ticket 或集成状态；机器状态只以 .scratch/ 和 main_loop.py 为准。

文件	用途
`project-brief.template.md`	项目定位、边界、约束和成功定义
`tech-context.template.md`	技术栈、仓库入口、工具链、平台差异和验证命令
`system-patterns.template.md`	稳定模块边界、数据流、不变量、扩展路径和禁止项

AGENT_RULES.template.md

部署为项目的 AGENT_RULES.md，是任务入口路由、Matt Pocock 工程主链、ticket 调度、 worktree、验证和集成协议的唯一流程权威。 区块内的内容由 Playbook 维护并在重新同步时刷新，项目补充写在区块外。项目私有规则写入 AGENT_RULES.local.md；该文件由项目维护，Playbook 不覆盖。

AGENTS.template.md

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

任务入口

四个入口按成本递增，取第一个满足的：直接执行（零行为变更）、单切片改动（单模块、已有 seam、一个 session 内）、已明确预期行为的 bug（diagnosing-bugs Phase 1-6）、新 feature 或设计变更（完整主链）。边界不清时从单切片改动起步，触到升级条件再转入完整主链，不要预付最重的流程。判据与升级条件见 AGENT_RULES.template.md。

部署

[sync_rules]

[sync_memory_bank]
project_name = "MyProject"

[sync_standards]
langs = ["python"]

[install_skills]
mode = "all"

部署后首次使用正式流程时运行 setup-matt-pocock-skills，并为本地主循环选择 local markdown tracker。

正式开发流程

只有第四个入口（新 feature 或设计变更）走这条链；前三个入口不入队、不建 ticket branch。

setup-matt-pocock-skills
  -> grill-with-docs
  -> to-spec
  -> to-tickets
  -> main_loop.py enqueue
  -> 提交 planning baseline（spec + tickets + queue）
  -> main_loop.py claim
  -> 本地 ticket 执行协议（tdd）
  -> commit
  -> code-review
  -> main_loop.py finish
  -> main_loop.py integrate
  -> 提交 final workflow state

产物和职责：

.scratch/<feature>/spec.md：feature spec
.scratch/<feature>/issues/*.md：ticket DAG 与执行状态
.scratch/queue.md：feature 开发和集成顺序
CONTEXT.md：稳定领域词汇
docs/adr/：长期架构决策
docs/agents/*.md：tracker 与领域文档配置

本批次 feature 全部 enqueue 后，先把对应 spec、tickets 和 queue 提交为一个 planning baseline，再开始任何 claim。生成和入队步骤本身不隐式提交。

feature 集成成功后，再在主干提交该 feature 的最终 .scratch 持久状态。此提交位于 feature merge commit 之后，并与其他活动 feature 的未提交状态隔离。

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

AGENTS 模板标记

：完整框架区块
：语言规则入口
：项目流程入口

playbook:agents 必须嵌在 playbook:framework 内。框架区块替换时， preserve_agents_subblock() 依赖该嵌套保留项目按 langs 生成的语言入口。

占位符

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

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

{{PROJECT_NAME}} 由 [sync_memory_bank].project_name 提供；未配置时保持原样。其他人工占位符不会由 playbook.py 推导。

`playbook.py` 部署后结构

project/
├── AGENTS.md                    # 任一 sync_* 节启用时创建或按区块更新
├── AGENT_RULES.md               # [sync_rules]
├── AGENT_RULES.local.md         # 首次成功写入规则时创建，后续由项目维护
├── .gitignore                   # [sync_rules] 更新 Playbook .scratch 标记区块
├── 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。

正式流程运行后按需产生的结构

project/
├── CONTEXT.md                     # setup 后按需创建的稳定领域词汇
├── .scratch/
│   ├── queue.md                   # main_loop.py 维护的 feature 顺序
│   └── <feature>/
│       ├── spec.md                # to-spec 产物
│       └── issues/                # to-tickets 产物与机器状态
└── docs/
    ├── agents/                    # setup 生成的 tracker/domain 配置
    └── adr/                       # grilling 过程中按需沉淀的长期决策

最后更新：2026-08-07

README.md Unescape Escape

项目架构模板

与 Playbook 其他部分的关系

目录