♻️ refactor(cook-it-through): move workflow engine into skill
This commit is contained in:
+25
-53
@@ -24,14 +24,15 @@ playbook/
|
||||
```text
|
||||
templates/
|
||||
├── AGENTS.template.md # 项目主入口与导航模板
|
||||
├── AGENT_RULES.template.md # Matt Pocock ticket-native 执行规则模板
|
||||
├── AGENT_RULES.template.md # 任务入口与按需 skill 路由模板
|
||||
├── gitignore.template # .scratch 持久状态与本机运行时忽略规则
|
||||
├── memory-bank/ # 稳定项目知识模板（3 个），不是机器状态源
|
||||
├── cpp/ # C++ 工具链模板
|
||||
└── python/ # Python 工具链模板
|
||||
```
|
||||
|
||||
完整主链只在 `AGENT_RULES.template.md` 定义。
|
||||
`AGENT_RULES.template.md` 只定义常驻边界和 Skill 入口；任务路由、完整主链与本地 Markdown
|
||||
ticket 协议只在第一方 `skills/cook-it-through/` 定义，并在工程任务中按需加载。
|
||||
|
||||
## 模板分类
|
||||
|
||||
@@ -66,7 +67,8 @@ Playbook 只处理框架提供的同名文件。项目新增的 `memory-bank/*`
|
||||
### memory-bank/
|
||||
|
||||
`memory-bank/` 保存 grilling、设计和实现都需要的稳定项目知识。它不记录 owner、
|
||||
heartbeat、ticket 或集成状态；机器状态只以 `.scratch/` 和 `main_loop.py` 为准。
|
||||
heartbeat、ticket 或集成状态；`.scratch/` 是唯一机器状态源，状态格式、转换语义和执行入口
|
||||
由第一方 `cook-it-through` Skill 权威定义。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ----------------------------- | ---------------------------------------------- |
|
||||
@@ -76,23 +78,18 @@ heartbeat、ticket 或集成状态；机器状态只以 `.scratch/` 和 `main_lo
|
||||
|
||||
### AGENT_RULES.template.md
|
||||
|
||||
部署为项目的 `AGENT_RULES.md`，是任务入口路由、Matt Pocock 工程主链、ticket 调度、
|
||||
worktree、验证和集成协议的唯一流程权威。`<!-- playbook:rules:start/end -->` 区块内的
|
||||
部署为项目的 `AGENT_RULES.md`，只常驻指令优先级、项目边界和 Skill 加载入口。
|
||||
`<!-- playbook:rules:start/end -->` 区块内的
|
||||
内容由 Playbook 维护并在重新同步时刷新，项目补充写在区块外。项目私有规则写入
|
||||
`AGENT_RULES.local.md`；该文件由项目维护，Playbook 不覆盖。
|
||||
|
||||
完整工程流程由 `cook-it-through` skill 按需定义；rules 只保留加载触发条件，不复制其协议。
|
||||
|
||||
### AGENTS.template.md
|
||||
|
||||
部署为项目的 `AGENTS.md`，只提供语言规则、核心规则和工程上下文导航。
|
||||
标记区块的更新约束见下文“AGENTS 模板标记”。
|
||||
|
||||
## 任务入口
|
||||
|
||||
四个入口按成本递增，取第一个满足的：直接执行（零行为变更）、单切片改动（单模块、
|
||||
已有 seam、一个 session 内）、已明确预期行为的 bug（`diagnosing-bugs` Phase 1-6）、
|
||||
新 feature 或设计变更（完整主链）。边界不清时从单切片改动起步，触到升级条件再转入
|
||||
完整主链，不要预付最重的流程。判据与升级条件见 `AGENT_RULES.template.md`。
|
||||
|
||||
## 部署
|
||||
|
||||
```toml
|
||||
@@ -108,49 +105,26 @@ langs = ["python"]
|
||||
mode = "all"
|
||||
```
|
||||
|
||||
部署后首次使用正式流程时运行 `setup-matt-pocock-skills`，并为本地主循环选择
|
||||
local markdown tracker。
|
||||
本示例启用了 `[sync_rules]`，因此安装集合必须包含 `cook-it-through`：
|
||||
`[install_skills].mode = "list"` 时显式列出，`mode = "all"` 时不得通过 `exclude` 排除。
|
||||
只有不部署官方 `AGENT_RULES.md` 且不使用正式工程主链的安装场景，才可以排除该 skill。
|
||||
同一配置违反该约束时，部署器会在写入任何同步文件前拒绝执行。
|
||||
部署后首次使用正式流程时运行 `setup-matt-pocock-skills`，并为本地主循环选择 local Markdown
|
||||
tracker；工程工作流与主循环协议只查该 skill。
|
||||
|
||||
## 正式开发流程
|
||||
|
||||
只有第四个入口（新 feature 或设计变更）走这条链；前三个入口不入队、不建 ticket branch。
|
||||
新 feature 或设计变更走这条链；任务分级和是否升级到主链的判据只查 `cook-it-through`。
|
||||
|
||||
```text
|
||||
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
|
||||
-> 按 cook-it-through 的本地 ticket 生命周期继续
|
||||
```
|
||||
|
||||
产物和职责：
|
||||
|
||||
- `.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`。
|
||||
从 `to-tickets` 到 final workflow state 的格式、命令、产物职责、隔离、恢复、证据和集成顺序
|
||||
只查 `cook-it-through`；本 README 不维护第二份流程定义。
|
||||
|
||||
## AGENTS 模板标记
|
||||
|
||||
@@ -159,7 +133,7 @@ merge commit 之后，并与其他活动 feature 的未提交状态隔离。
|
||||
- `<!-- playbook:templates:start/end -->`：项目流程入口
|
||||
|
||||
`playbook:agents` 必须嵌在 `playbook:framework` 内。框架区块替换时，
|
||||
`preserve_agents_subblock()` 依赖该嵌套保留项目按 `langs` 生成的语言入口。
|
||||
该嵌套关系用于保留项目按 `langs` 生成的语言入口。
|
||||
|
||||
## 占位符
|
||||
|
||||
@@ -170,7 +144,6 @@ merge commit 之后，并与其他活动 feature 的未提交状态隔离。
|
||||
| `{{DATE}}` | 同步日期 | 是 |
|
||||
| `{{PROJECT_NAME}}` | 可选项目名 | 配置 `project_name` 时替换 |
|
||||
| `{{PLAYBOOK_ROOT}}` | 项目内 Playbook 根目录 | 是 |
|
||||
| `{{PLAYBOOK_SCRIPTS}}` | 项目内脚本目录 | 是 |
|
||||
| `{{PROJECT_GOAL}}` | 项目目标 | 否，项目手工填写 |
|
||||
| `{{PROJECT_DESCRIPTION}}` | 项目描述 | 否，项目手工填写 |
|
||||
| 其他 `{{...}}` | 模板中的项目特定内容 | 否，项目手工填写或删除所在行 |
|
||||
@@ -193,7 +166,10 @@ project/
|
||||
```
|
||||
|
||||
`[install_skills]` 安装到 `agents_home/skills/`，通常不在项目目录内。`mode = "list"`
|
||||
要求用户逐项列出 skills 及其依赖；`mode = "all"` 安装全部 skills。
|
||||
要求用户逐项列出 skills 及其依赖；`mode = "all"` 安装全部未排除的 skills。两种模式都可用
|
||||
`exclude = ["skill-name"]` 从本次安装集合排除同名 skill；该选项不会卸载已有目录。
|
||||
同时启用 `[sync_rules]` 时，必须遵守上文对 `cook-it-through` 的保留约束。
|
||||
`cook-it-through` 会随 skill 一起安装并包含其内部执行引擎，不依赖 snapshot 根目录下的脚本路径。
|
||||
|
||||
## 正式流程运行后按需产生的结构
|
||||
|
||||
@@ -201,7 +177,7 @@ project/
|
||||
project/
|
||||
├── CONTEXT.md # setup 后按需创建的稳定领域词汇
|
||||
├── .scratch/
|
||||
│ ├── queue.md # main_loop.py 维护的 feature 顺序
|
||||
│ ├── queue.md # claim 优先级与严格的 feature 集成顺序
|
||||
│ └── <feature>/
|
||||
│ ├── spec.md # to-spec 产物
|
||||
│ └── issues/ # to-tickets 产物与机器状态
|
||||
@@ -209,7 +185,3 @@ project/
|
||||
├── agents/ # setup 生成的 tracker/domain 配置
|
||||
└── adr/ # grilling 过程中按需沉淀的长期决策
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：2026-08-07
|
||||
|
||||
Reference in New Issue
Block a user