prd-to-parallel-loop

prd-to-parallel-loop

这个 skill 做什么

把一批要并行开发的变更搭成可跑的 loop 脚手架。核心对应关系:一个 openspec change = 一个并行任务 = 一个 git worktree = 一个 codex 会话。

PRD / 产品文档  或  里程碑文档 (docs/roadmap/milestone-N-xxx.md)
   ↓  切分与依赖协商(里程碑文档里已经写好就沿用,不重写)
openspec/changes/<change-id>/ × N            ← 变更单元 = 并行单元
   ↓  一个 change 一个 worktree
~/dev-loops/<project>/<slug>/runtime.json    ← 依赖 DAG 与调度状态的事实源
   ↓  /loop 心跳
主 loop 分三段驱动每个任务:实施 → 反思 → 归档 → 自己 squash merge 落地

跑完 skill,用户在新对话粘贴 loop-prompt.md 里那段 + /loop 就能开跑。

为什么是 change 粒度,不是 change 内的 task 粒度

change 是 openspec 里"一个连贯的变更提案",也是天然的可归档单元。把一个 change 切成 N 份丢给 N 个互相看不见的 codex,等于把提案的内部一致性交给并发去赌,还会让 N 个执行者共写同一份 tasks.md 与 spec-delta。按 change 并行则每个 worktree 自成闭环:codex 在里面走完 openspec-driven-development 的步骤 5→7,产出的 spec-delta 走标准路径,归档动作也在它自己手里。

任务的三段式生命周期

主 loop 每次心跳只推进一段,段与段之间是调度器的检查关:

段	谁做	内容
implement	codex(spawn)	按 change 定义写码,勾自己的 tasks.md,写 spec-delta
reflect	codex(resume)	对照 proposal/design/tasks 核有无遗漏与有无多做,有则改
archive	codex(resume,已 rebase 到最新 main 之后)	spec-delta 合进 specs/、change 移进 archive/
落地	主 loop(不占独立心跳)	squash merge → 核对归档结果 → 在合并后的工作区跑验证 → 勾里程碑那一行 + 写证据锚 → commit

rebase 卡在 archive 之前,是因为归档要写 openspec/specs/<domain>/spec.md——多 worktree 并行时唯一的共享写点。让它在最新 main 上做,冲突提前摆到 codex 面前解掉。

落盘范围(ownership: edit-file)

本 skill 会直接写入用户文件系统。写盘范围仅限:

• {{PROJECT_REPO}}/openspec/changes/<change-id>/ × N(从项目 openspec/changes/_template/ 拷贝再填)
• ~/dev-loops/bin/ 下的 3 个 .mjs(已存在则跳过,永不覆盖)
• ~/dev-loops/<project-name>/<slug>/ 下的 runtime.json / loop-instructions.md / loop-prompt.md /(必要时)acceptance-map.md

绝不写用户的里程碑文档或 PRD。里程碑文档是人类文档,skill 只读它;唯一的写入发生在 loop 跑起来之后、由主 loop 在落地时勾对应那一行 checkbox 并追加证据锚——那是运行时行为,不是本 skill 的落盘。

也绝不修改 openspec/changes/_template/、git 历史、产品代码,或已在跑的 runtime.json。

这个 skill 不做什么

• 不代替产品文档写作。PRD / 里程碑文档怎么写、验收怎么定,由用户与 credibility-review / project-init-docs 负责。尤其不给里程碑文档规定格式——skill 尽力解析,解析不到就问
• 不代替 codex 里的实现判断。怎么写代码、用什么工具验证,是 codex 的事;skill 只保证它拿到清晰的 change 定义、明确的验证命令、清楚的分段规范
• 不建 openspec 骨架。项目缺 openspec/ 就打回,让用户先走 openspec-driven-development
• 不接单个 change。拆出来只有一个 change 就打回:不值得起 loop,直接走 openspec-driven-development
• 不推送、不合并到远端。主 loop 只本地 squash merge 到 main;push 是用户人工决定
• 不做 update 模式。runtime.json 已在跑就拒绝重建;强行覆盖会丢失 phase / attempts / merged_sha / codex_session_id 等运行时数据