✨ 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
@@ -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