csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✨ feat(playbook): version durable scratch workflow state

Browse Source
This commit is contained in:
csh
2026-08-14 17:11:54 +08:00
parent 9487dbddf1
commit 8f1056130d
8 changed files with 237 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1
View File
@@ -63,6 +63,7 @@ project_name = "MyProject"
- **配置节存在即启用**：只写需要同步的配置节
- **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`）
- **CLAUDE.md**：自动检测（根目录 → `.claude/`），不存在则创建；注入 `@AGENTS.md` / `@AGENT_RULES.md`
- **.gitignore**：启用 `[sync_rules]` 时更新 Playbook 标记区块，只忽略 `.scratch` 的锁、worktree 和临时文件
- **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（会先备份）
更多说明详见 [templates/README.md](templates/README.md)。
playbook.example.toml
+1 -1
View File
@@ -19,7 +19,7 @@
# ============================================================================
[sync_rules]
# 同步 AGENT_RULES.md
# 同步 AGENT_RULES.md，并更新目标项目 .gitignore 中的 .scratch 运行时区块
# force = false # 覆盖已有文件
# no_backup = false # 跳过备份
# date = "2026-04-22" # 替换 {{DATE}}
scripts/playbook.py
+75 -1
View File
@@ -339,7 +339,12 @@ def install_snapshot(config: dict, context: dict) -> int:
if templates_ci.is_dir():
copytree(templates_ci, templates_dst / "ci")
for name in ("AGENTS.template.md", "AGENT_RULES.template.md", "README.md"):
for name in (
"AGENTS.template.md",
"AGENT_RULES.template.md",
"gitignore.template",
"README.md",
):
src = templates_root / name
if src.is_file():
copy2(src, templates_dst / name)
@@ -510,6 +515,8 @@ _AGENTS_BLOCK_START = "<!-- playbook:agents:start -->"
_AGENTS_BLOCK_END = "<!-- playbook:agents:end -->"
_RULES_BLOCK_START = "<!-- playbook:rules:start -->"
_RULES_BLOCK_END = "<!-- playbook:rules:end -->"
_GITIGNORE_BLOCK_START = "# BEGIN playbook .scratch runtime"
_GITIGNORE_BLOCK_END = "# END playbook .scratch runtime"
def replace_marked_block(
@@ -751,6 +758,10 @@ def sync_rules_action(config: dict, context: dict) -> int:
if not rules_src.is_file():
print(f"ERROR: template not found: {rules_src}", file=sys.stderr)
return 2
gitignore_src = templates_dir / "gitignore.template"
if not gitignore_src.is_file():
print(f"ERROR: template not found: {gitignore_src}", file=sys.stderr)
return 2
rules_dst = project_root / "AGENT_RULES.md"
force = bool(config.get("force", False))
@@ -809,6 +820,16 @@ def sync_rules_action(config: dict, context: dict) -> int:
)
log("Created: AGENT_RULES.local.md")
try:
sync_gitignore_block(
gitignore_src,
project_root / ".gitignore",
no_backup,
)
except ValueError as exc:
print(f"ERROR: {exc}", file=sys.stderr)
return 2
return 0
@@ -1046,6 +1067,59 @@ def sync_gitattributes_block(src: Path, dst: Path, no_backup: bool) -> None:
log("Synced .gitattributes from standards (block).")
def sync_gitignore_block(src: Path, dst: Path, no_backup: bool) -> None:
source_lines = src.read_text(encoding="utf-8").splitlines()
block_lines = [
_GITIGNORE_BLOCK_START,
*source_lines,
_GITIGNORE_BLOCK_END,
]
original_text = dst.read_text(encoding="utf-8") if dst.exists() else ""
if dst.exists():
original_lines = original_text.splitlines()
start_positions = [
index
for index, line in enumerate(original_lines)
if line.strip() == _GITIGNORE_BLOCK_START
]
end_positions = [
index
for index, line in enumerate(original_lines)
if line.strip() == _GITIGNORE_BLOCK_END
]
if (
len(start_positions) != len(end_positions)
or len(start_positions) > 1
or (
start_positions
and start_positions[0] >= end_positions[0]
)
):
raise ValueError(".gitignore has an invalid playbook .scratch block")
if start_positions:
updated_text = replace_marked_block(
original_text,
block_lines,
_GITIGNORE_BLOCK_START,
_GITIGNORE_BLOCK_END,
)
else:
content = original_text.rstrip("\n")
if content:
content += "\n\n"
updated_text = content + "\n".join(block_lines) + "\n"
else:
updated_text = "\n".join(block_lines) + "\n"
if dst.exists() and updated_text == original_text:
log("Unchanged: .gitignore (playbook .scratch block)")
return
backup_path(dst, no_backup)
dst.write_text(updated_text, encoding="utf-8", newline="\n")
log("Synced: .gitignore (playbook .scratch block)")
def sync_standards_action(config: dict, context: dict) -> int:
if "langs" not in config:
print("ERROR: langs is required for sync_standards", file=sys.stderr)
templates/AGENT_RULES.template.md
+11 -5
View File
@@ -123,9 +123,11 @@ setup-matt-pocock-skills
-> to-spec
-> to-tickets
-> main_loop.py enqueue
-> 提交 planning baseline
-> main_loop.py claim
-> 本地 ticket 执行协议 (tdd -> commit -> code-review -> finish)
-> main_loop.py integrate
-> 提交 final workflow state
```
- 每个仓库首次使用时运行 `setup-matt-pocock-skills`，本地开发选择 local markdown tracker
@@ -139,6 +141,9 @@ setup-matt-pocock-skills
- `to-spec` 不重新进行已经完成的需求采访
- `to-tickets` 产出可独立验证的 tracer-bullet tickets，并显式声明 `Blocked by`
- 一次可以先生成多个 feature 的 spec/tickets，再按期望顺序逐个 `enqueue`
- 本批次全部 `enqueue` 成功后、任何 `claim` 之前，必须把对应的
`.scratch/<feature>/spec.md`、`.scratch/<feature>/issues/*.md` 和 `.scratch/queue.md`
提交为一个 planning baseline；`to-spec`、`to-tickets` 和 `enqueue` 本身不隐式提交
- `codebase-design` 是 seam、deep module 与依赖分类的词汇来源，供 `to-spec` 和 `tdd` 查阅，
不作为独立会话运行
@@ -196,11 +201,6 @@ setup-matt-pocock-skills
不得手工修改 ticket 的 `Status` 或 `main-loop:ticket-state` 区块；只通过主循环变更。主循环
没有对应命令的状态组合按"卡死与恢复"处理，仍然不手工改。
`.scratch/` 是否纳入版本控制由项目决定并写入 `AGENT_RULES.local.md`：纳入则 spec、ticket 和
证据进入历史，可审计、新 clone 能接手队列，代价是状态变更产生提交噪音；排除则历史干净，
代价是状态只存在于本机磁盘、集成后审计线索消失，并发只靠"共享同一文件系统"兜住。无论哪种
都不得把两份 `.scratch/` 当成同一队列。
## 稳定知识维护
只记录下一 session 仍需要的稳定知识；当前 feature、ticket、owner、heartbeat、验证和集成
@@ -444,6 +444,12 @@ review 后再调用。main 合并冲突时主循环会**自动**把 feature 标
`_integration` worktree；不干净或路径异常的保留并以 `WARNING=` 行报告。已集成的 feature
再次调用时幂等返回 `INTEGRATED=`。
`integrate` 成功后必须在主干提交本 feature 的最终 workflow state。只暂存
`.scratch/<feature>/` 下的持久变更，以及确由本次集成改写时的 `.scratch/queue.md`；不得用
`git add .scratch` 把其他活动 feature 的并发状态带入。该状态提交必须位于 feature merge commit
之后，不得 amend 或 squash 进 merge commit；`.scratch/<feature>/.main-loop.json` 中记录的
`integration_commit` 必须继续指向主循环返回的 `MAIN_INTEGRATION_COMMIT`。
ready-to-integrate feature 因人工决策暂时不能集成时必须显式记录，否则主循环不会为后序
feature 继续分配开发工作：
templates/README.md
+11
View File
@@ -25,6 +25,7 @@ playbook/
templates/
├── AGENTS.template.md # 项目主入口与导航模板
├── AGENT_RULES.template.md # Matt Pocock ticket-native 执行规则模板
├── gitignore.template # .scratch 持久状态与本机运行时忽略规则
├── memory-bank/ # 稳定项目知识模板（3 个），不是机器状态源
├── cpp/ # C++ 工具链模板
└── python/ # Python 工具链模板
@@ -47,6 +48,7 @@ templates/
- `AGENT_RULES.md`：`<!-- playbook:rules:start/end -->` 区块内的工程流程由 Playbook
维护，重新同步时刷新；项目自己的补充写在区块外，同步不会动它
- `AGENT_RULES.local.md`：项目私有规则，Playbook 不覆盖
- `.gitignore`：Playbook 维护专属标记区块，仅忽略 `.scratch` 下的本机运行时产物
- `memory-bank/`：稳定项目定位、技术上下文和当前系统模式，不承载机器状态
Playbook 只处理框架提供的同名文件。项目新增的 `memory-bank/*` 不会被删除。
@@ -119,12 +121,14 @@ setup-matt-pocock-skills
-> 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
```
产物和职责：
@@ -136,6 +140,12 @@ setup-matt-pocock-skills
- `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 可单独
@@ -175,6 +185,7 @@ 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] 按配置同步
templates/gitignore.template
+8
View File
@@ -0,0 +1,8 @@
# Keep durable Playbook workflow state under .scratch version-controlled.
!/.scratch/
!/.scratch/**
# Ignore only machine-local main-loop runtime artifacts.
/.scratch/*.lock
/.scratch/worktrees/
/.scratch/**/*.tmp
test/test_playbook.py
+76
View File
@@ -108,6 +108,11 @@ def seed_custom_files(project_root: Path) -> None:
encoding="utf-8",
newline="\n",
)
(project_root / ".gitignore").write_text(
"build/\n.scratch/\n",
encoding="utf-8",
newline="\n",
)
class PlaybookDeploymentTests(unittest.TestCase):
@@ -254,6 +259,7 @@ project_root = "C:\workspace\project"
"AGENT_RULES.md",
"AGENT_RULES.local.md",
"CLAUDE.md",
".gitignore",
".gitattributes",
"memory-bank/project-brief.md",
"memory-bank/system-patterns.md",
@@ -332,6 +338,22 @@ project_root = "C:\workspace\project"
f"`{playbook_root.as_posix()}/` 是 Playbook 模板/供应商目录",
rules_text,
)
gitignore_text = (project_root / ".gitignore").read_text(
encoding="utf-8"
)
self.assertIn("build/", gitignore_text)
self.assertEqual(
gitignore_text.count("# BEGIN playbook .scratch runtime"),
1,
)
self.assertEqual(
gitignore_text.count("# END playbook .scratch runtime"),
1,
)
self.assertIn("!/.scratch/**", gitignore_text)
self.assertIn("/.scratch/*.lock", gitignore_text)
self.assertIn("/.scratch/worktrees/", gitignore_text)
self.assertIn("/.scratch/**/*.tmp", gitignore_text)
if install_mode == "snapshot":
snapshot_root = project_root / playbook_root
@@ -345,6 +367,9 @@ project_root = "C:\workspace\project"
self.assertTrue(
(snapshot_root / "playbook.example.toml").is_file()
)
self.assertTrue(
(snapshot_root / "templates/gitignore.template").is_file()
)
self.assertFalse(
(snapshot_root / "playbook.toml.example").exists()
)
@@ -355,6 +380,57 @@ project_root = "C:\workspace\project"
else:
self.assertFalse((source_root / "SOURCE.md").exists())
def test_sync_rules_gitignore_block_tracks_durable_scratch_only(self):
with tempfile.TemporaryDirectory() as tmp_dir:
project_root = Path(tmp_dir) / "project"
project_root.mkdir()
seed_custom_files(project_root)
initialized = subprocess.run(
["git", "init", "-q"],
cwd=project_root,
capture_output=True,
text=True,
)
self.assertEqual(initialized.returncode, 0, msg=initialized.stderr)
playbook_root = MODE_ROOTS["snapshot"]
config = write_config(project_root, "snapshot", playbook_root)
result = run_playbook(SCRIPT, config, project_root)
self.assertEqual(result.returncode, 0, msg=f"{result.stdout}{result.stderr}")
paths = {
"queue": project_root / ".scratch/queue.md",
"spec": project_root / ".scratch/alpha/spec.md",
"evidence": project_root / ".scratch/alpha/evidence/check.json",
"lock": project_root / ".scratch/.main-loop.lock",
"other_lock": project_root / ".scratch/worker.lock",
"worktree": project_root / ".scratch/worktrees/alpha/file.txt",
"temp": project_root / ".scratch/alpha/.spec.md.deadbeef.tmp",
}
for path in paths.values():
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("test\n", encoding="utf-8", newline="\n")
def is_ignored(path: Path) -> bool:
checked = subprocess.run(
[
"git",
"check-ignore",
"-q",
"--",
path.relative_to(project_root).as_posix(),
],
cwd=project_root,
capture_output=True,
text=True,
)
return checked.returncode == 0
for name in ("queue", "spec", "evidence"):
self.assertFalse(is_ignored(paths[name]), msg=f"{name} must be tracked")
for name in ("lock", "other_lock", "worktree", "temp"):
self.assertTrue(is_ignored(paths[name]), msg=f"{name} must be ignored")
def test_sync_without_standards_keeps_language_rules(self):
with tempfile.TemporaryDirectory() as tmp_dir:
project_root = Path(tmp_dir) / "project"
test/test_template_contracts.py
+54 -10
View File
@@ -277,17 +277,20 @@ class TemplateContractsTests(unittest.TestCase):
for legacy in LEGACY_FLOW_TERMS:
self.assertNotIn(legacy, rules)
def test_agent_rules_states_whether_scratch_is_version_controlled(self):
rules = rules_text()
responsibilities = section(rules, "## 文档职责", "## 稳定知识维护")
def test_gitignore_template_tracks_scratch_and_ignores_only_runtime(self):
template = (TEMPLATES / "gitignore.template").read_text(encoding="utf-8")
self.assertIn("AGENT_RULES.local.md", responsibilities)
self.assertIn(
"纳入版本控制",
responsibilities,
msg="the review contract reads spec sources out of .scratch/, so "
"whether it is tracked has to be an explicit project decision",
)
for durable_rule in ("!/.scratch/", "!/.scratch/**"):
self.assertIn(durable_rule, template)
for runtime_rule in (
"/.scratch/*.lock",
"/.scratch/worktrees/",
"/.scratch/**/*.tmp",
):
self.assertIn(runtime_rule, template)
rules = rules_text()
self.assertNotIn("是否纳入版本控制由项目决定", rules)
def test_agent_rules_routes_each_current_matt_on_ramp_to_its_destination(self):
rules = rules_text()
@@ -315,6 +318,47 @@ class TemplateContractsTests(unittest.TestCase):
"the skill's own phase order",
)
def test_agent_rules_commits_planning_baseline_before_claim(self):
rules = rules_text()
main_chain = section(rules, "## 正式工程主链", "## On-ramps 与 detours")
ordered_steps = (
"-> to-spec",
"-> to-tickets",
"-> main_loop.py enqueue",
"-> 提交 planning baseline",
"-> main_loop.py claim",
)
positions = [main_chain.index(step) for step in ordered_steps]
self.assertEqual(positions, sorted(positions))
for durable_input in (
"`.scratch/<feature>/spec.md`",
"`.scratch/<feature>/issues/*.md`",
"`.scratch/queue.md`",
):
self.assertIn(durable_input, main_chain)
self.assertIn("任何 `claim` 之前", main_chain)
self.assertIn("不隐式提交", main_chain)
def test_agent_rules_commits_final_workflow_state_after_integration(self):
rules = rules_text()
main_chain = section(rules, "## 正式工程主链", "## On-ramps 与 detours")
integration = section(rules, "### Feature 顺序集成", "## Git 与证据门禁")
self.assertLess(
main_chain.index("-> main_loop.py integrate"),
main_chain.index("-> 提交 final workflow state"),
)
for durable_path in (
"`.scratch/<feature>/`",
"`.scratch/queue.md`",
"`.scratch/<feature>/.main-loop.json`",
):
self.assertIn(durable_path, integration)
self.assertIn("不得用\n`git add .scratch`", integration)
self.assertIn("不得 amend 或 squash", integration)
self.assertIn("`MAIN_INTEGRATION_COMMIT`", integration)
def test_agent_rules_defines_a_local_ticket_execution_adapter(self):
rules = rules_text()
main_flow = section(rules, "## 正式工程主链", "## On-ramps 与 detours")