sampx/dev-flow

dev-flow — Issue / Plan 驱动开发流程

脚本执行

所有 flow.sh 命令必须从本技能根目录执行：

• workdir: .wopal/skills/dev-flow/
• 命令格式: bash scripts/flow.sh <command> [args]

本文档中所有 flow.sh xxx 引用（如 flow.sh plan new、flow.sh complete、flow.sh verify-switch）均按此方式执行。禁止 source、禁止绝对路径直接调用、禁止在非技能目录下执行。

命令速查

详细参数和边缘场景见 references/commands.md。

状态机推进

| 命令 | 场景 | 说明 | |------|------|------| | plan new <issue> | 创建 Plan | Issue 驱动；无 Issue 用 --title --project --type | | plan status <name> | 查看 Plan 状态 | 含状态机位置、关联 Issue、worktree 信息 | | plan list [--issue] | 浏览活跃 Plan | --issue 含 GitHub Issues 合并展示 | | plan check <name> | 校验 Plan 质量 | submit 前必走 | | submit <plan> | planning → reviewing | 提交人工审阅 | | approve <plan> --confirm | reviewing → executing | 用户审批，默认创建 worktree；--no-worktree 跳过 | | complete <plan> | executing → verifying | 实施完成，进入用户验证；脏树报错退出 | | verify <plan> --confirm | verifying → done | 用户验证通过；需先 merge feature → 集成分支 | | archive <plan> | done → 归档 | 归档 Plan、清理 worktree 和 feature 分支 |

验证辅助

| 命令 | 场景 | 说明 | |------|------|------| | verify-switch <plan> | 需在规范路径验证 | 移除 worktree + checkout feature 分支 |

Issue 管理

| 命令 | 场景 | 说明 | |------|------|------| | issue create --title "..." --project <name> --body-file <path> | 创建 Issue | --body-file 为主路径 | | issue write <issue> --body-file <path> | 全量替换 Issue body | | | sync <plan> [--body-only\|--labels-only] | Plan → Issue 同步 | Plan 内容变更后必走 |

其他

| 命令 | 场景 | 说明 | |------|------|------| | decompose-prd <prd-path> | 从 PRD 拆分 Issue | --dry-run 预览 | | roadmap <prd-path> --product <name> | 产品阶段规划 | 四阶段工作流 | | reset <plan> | 重置 Plan | 破坏性，仅用户明确要求时使用 |

心智模型

dev-flow 管理两类产物，它们在 git 中独立演化：

| 产物 | 什么 | 谁提交 | 何时提交 | |------|------|--------|----------| | Plan 文件 | 状态、checkbox、元数据 | flow.sh 脚本自动提交 | 状态推进时（submit/approve/complete/verify/archive） | | 实施代码 | 源码、测试、文档变更 | agent（Wopal 或 fae）手动提交 | rook PASS 后、complete 之前 |

铁律：脚本不操作项目代码，但管理自身基础设施。 flow.sh 命令不 add、commit、merge、push 任何实施代码——代码的 commit 和 feature → 集成分支的 merge 由 agent 负责。worktree 创建/清理和 feature 分支创建/删除属于 dev-flow 基础设施操作，由脚本管理生命周期，不在此限。

实施产物 = 原子单元。 实施代码变更 + Task Done checkbox + Agent Verification checkbox 是一个原子单元，同一次 commit 提交。禁止拆成多次 commit。

状态机

planning → reviewing → executing → verifying → done

| 命令 | 前置状态 | 后置状态 | Plan 操作 | 代码操作 | |------|---------|---------|-----------|----------| | plan | 无 | planning | 脚本提交 Plan | — | | submit | planning | reviewing | 脚本提交 Plan status | — | | approve --confirm | reviewing/planning | executing | 脚本提交 Plan status + worktree 元数据 | — | | complete | executing | verifying | 脚本提交 Plan status | 脏树报错退出 | | verify --confirm | verifying | done | 脚本提交 Plan status | — | | archive | done | 归档 | 脚本提交 Plan 归档 + worktree 清理 | — |

命令顺序不合法时，回到正确状态顺序执行，不要强行推进。

提交序列

一次完整 Plan 的 git 提交序列（feature 分支视角）：

1. plan / submit / approve     → 脚本自动提交 Plan 文件（集成分支）
2. fae 实施                     → 变更留在 working tree，不提交
3. rook PASS                    → 触发下一步
4. agent 提交实施产物           → 一次 commit：代码 + Task Done + AC checkbox（feature 分支）
5. flow.sh complete             → 脚本自动提交 Plan status → verifying（feature 分支）
6. verify-switch → 用户验证    → 用户操作，无脚本提交
7. agent merge feature → 集成分支  → agent 操作（不删 feature 分支，留给 archive 清理）
8. flow.sh verify --confirm    → 脚本自动提交 Plan status → done（集成分支）
9. flow.sh archive              → 脚本自动提交 Plan 归档（集成分支）

常见错误：在步骤 4 之前执行 complete（代码未提交 → 报错）；步骤 4 拆成多次 commit（碎片化历史）；checkbox 单独 commit（多余 commit）。

核心原则

1. Plan 先行：先进入 Plan 生命周期，再开始实施。Plan 必须通过 flow.sh plan new ... 创建或定位，禁止手写创建。
2. 人类授权门：approve --confirm 和 verify --confirm 都需要用户明确授权，禁止未经授权执行。
3. 脚本不操作项目代码：flow.sh 命令不提交实施代码，但管理自身创建的基础设施（worktree、feature 分支）。complete 遇脏树报错退出。
4. 活动 Plan 路径：委派实施时，Plan 路径必须使用 feature 分支 worktree 中的活动副本，禁止使用 main 分支路径。
5. rook 门禁：实施审查（complete 前）必须委派 rook，rook PASS 才能推进，最多 3 轮修订。Plan 审查（submit 前）默认委派 rook，但 fix 类型 Plan 可跳过——方案简单明确时无需审查；若方案复杂需审查，提交前征求用户同意。
6. Plan 语言与结构：Plan 文档正文使用用户偏好语言编写，章节标题保持英文（与模板一致）。禁止混用中英文标题。

Plan Task 字段要求

写 Plan 时每个 Task 必须包含以下字段（按顺序），详见 references/plan-guide.md：

| Field | Required | Format | |-------|----------|--------| | Verification Intent | ✅ | AC#N | | Behavior | ✅ TDD=true | 输入 → 输出映射 | | Files | ✅ | path/to/file | | Pre-read | ✅ | 文件路径或 N/A | | Design | ✅ | 完整实施设计（非空） | | TDD | ✅ | true / false | | Changes | ✅ | 编号列表（禁止 checkbox） | | Verify | ✅ | 可执行命令 | | Done | ✅ | 产出描述 + 1 个 checkbox |

提交前必跑：flow.sh plan check <name>

Plan 定位

当用户提到某个 Plan 名称（如 155-enhance-dev-flow）时，必须用脚本定位，严禁 grep、glob、read 在空间内盲目搜索。

• flow.sh plan status <name> — 查看 Plan 完整状态，含状态机位置、关联 Issue、worktree 信息
• flow.sh plan list [--issue] — 浏览所有活跃 Plan（--issue 模式查看 GitHub Issues）
• flow.sh plan check <name-or-path> — 校验 Plan 质量

验证纪律

验证分三层，每层的责任人和规则不同。

第一层：Task Done（fae 即时勾选）

每个 Task 完成 → 运行 Task 内的 Verify 命令 → 通过后立即勾选 Done checkbox。

• 委派 fae 的 prompt 必须包含"完成后勾选 Plan 中对应 Task 的 Done checkbox"指令
• 禁止积压到阶段末尾统一补勾

第二层：Agent Verification（Wopal 实证勾选）

rook 审查 PASS 后，Wopal 必须逐项真实验证 Agent Verification 的每个 AC。

验证方法：按 AC 描述运行命令、检查输出、确认结果。不能凭记忆或推测打勾，不能被 complete 脚本报错催着补勾。

修复后必须重新验证：rook 审查返回 REVISE/BLOCK → fae 修复后，AC 必须重新运行验证命令，不能沿用修复前的结果。

AC 全部通过 → 勾选 Agent Verification checkbox → 与代码一起提交（见提交序列步骤 4）。

第三层：User Validation（用户独占）

用户验证功能是否符合预期。checkbox 勾选权在用户，Agent 绝对禁止代勾。

Agent 可以执行验证动作、展示结果，但必须等用户明确确认。

标准流程

A. Planning

flow.sh plan new <issue>                              # Issue 驱动
flow.sh plan new --title "..." --project <name> --type <type>  # 无 Issue

完整命令链：plan new → plan check → rook review → submit → approve --confirm → complete → verify --confirm → archive。

Plan 目录：统一存放在 .wopal-space/plans/<项目名>/。

B. Plan 审查与提交

flow.sh plan check <name-or-path>   # 校验 Plan 质量（必走）
flow.sh sync <issue> --body-only    # 同步 Issue body（变更目标和范围必须）

1. 委派 rook 审 Plan — prompt 契约见 agents-collab。fix 类型 Plan 默认跳过此步骤；若方案复杂需审查，提交前征求用户同意
2. rook PASS → flow.sh submit <issue>（planning → reviewing）
3. rook REVISE/BLOCK → 修订后重审（最多 3 轮）
4. Plan 处于 reviewing 状态时可直接修订内容，无需 flow.sh reset 回退到 planning。修订完成后告知用户即可，无需重新 submit
5. 等用户审批后：flow.sh approve <issue> --confirm（reviewing/planning → executing）

C. Executing

1. flow.sh approve <issue> --confirm（默认创建 worktree）
2. 委派 fae 实施（prompt 含活动 Plan 路径 + Done checkbox 指令）
3. fae 完成 Task → Verify 通过 → 即时勾选 Done checkbox 和 git commit
4. 全部 Task 完成 → Wopal 逐项实证 Agent Verification AC
5. AC 通过 → 勾选 checkbox，与代码一起一次 commit（提交序列步骤 4）
6. 委派 rook 审查实施（强制）
7. rook PASS → flow.sh complete <issue>（脚本提交 Plan status → verifying）

委派要点：

• 实施 → fae；审查 → rook
• 上下文复用原则：fae/rook 完成后，优先 reply 续审或修复，禁止 finish 后新开。前提：子任务上下文 < 50%
• 复用链路：fae IDLE → reply rook 续审 → rook REVISE → reply fae 修复 → fae fix IDLE → reply rook 续审 → rook PASS → finish 两个 task
• rook 契约格式见 agents-collab；rook 自行加载 df-plan-review / df-implement-review 技能

complete 硬门控：所有 Task Done ✓ + Agent Verification ✓ + rook PASS ✓ + 实施代码已提交。

⚠️ complete 时序铁律（严格约束）： 实施代码提交 → rook PASS 后，Wopal 必须立即执行 flow.sh complete <issue> 将 Plan 状态推进至 verifying，然后才能进入用户验证环节。

违反模式：实施代码提交 → 跳过 complete → 直接邀约用户"验证/验收/测试" → 用户确认后才发现 Plan 还在 executing。

正确模式：实施代码提交 → rook PASS → flow.sh complete（executing→verifying） → 再向用户发出任何验证邀约。

Plan 状态未达 verifying 之前，Wopal 不得以任何形式（口头提示、命令行建议、checkbox 勾选邀请）请求用户进行功能验证。此规则是 Wopal 的自主执行义务，不依赖用户提醒。违反 = 严重失职。

D. 验证（verifying）

complete 后 Plan 状态为 verifying。complete 会输出验证选项和规范路径 git status， agent 必须将其完整传达给用户，由用户选择验证方式。

分支生命周期铁律：

• 分支创建：approve --confirm（脚本会自动创建）
• 分支删除：archive（脚本会自动删除）
• Agent 唯一的分支操作是 merge：git checkout <集成分支> && git merge <feature>
• Agent 禁止 git branch -d/-D、禁止 git branch <name>、禁止任何分支的创建或删除
• 工作树生命周期由脚本管理：approve 创建，verify-switch 或 archive 删除

验证场景

complete 后 agent 必须将验证选项完整呈现给用户，由用户选择验证方式。 Agent 不得自行决定跳过任何场景。

场景 1：工作树内验证

条件：有 worktree，且项目在 worktree 目录内可独立运行/测试（无路径依赖）。 流程：用户在 worktree 路径验证 → merge → verify --confirm → archive。

场景 2：verify-switch 切换验证分支

条件：项目有路径依赖（目录结构要求、运行时加载路径、配置文件位置等）， 必须在规范路径（repo 根目录）验证。适用于 standard 和 ontology-worktree 项目。 流程：agent 执行 flow.sh verify-switch <issue>（移除 worktree + checkout feature）→ 用户在规范路径验证 → merge → verify --confirm → archive。

场景 3：先合并后验证

条件：用户希望在集成分支直接验证，无需保留 feature 分支隔离。 流程：merge → 用户在集成分支验证 → verify --confirm → archive。

场景 4：无 worktree（--no-worktree）

条件：approve --confirm --no-worktree 时全程在集成分支，无 feature 分支。 流程：用户直接在集成分支验证 → verify --confirm → archive。

verify --confirm 内部机制

Agent 需要知道脚本做了什么，以便在出错时排查。

1. 状态门控：Plan status 必须为 verifying
2. 用户验证门控：User Validation checkbox 必须已勾选
3. Merge 检测（场景 4 自动跳过）：
   • 优先使用 complete 写入的 Verification Commit（SHA）做祖先检测： git merge-base --is-ancestor <sha> <集成分支>
   • SHA 检测不依赖 branch ref，合并后分支删除也能正常通过
   • 若无 Verification Commit（旧 Plan），回退到 branch ref 检测
   • 未合并时报错退出，提示 agent 先 merge
4. 状态转换：verifying → done，commit 在集成分支

Agent 检查清单

complete 后 agent 必须：

• [ ] 将 complete 输出的验证选项和路径状态完整传达给用户
• [ ] 等用户选择验证方式并确认验证通过
• [ ] merge feature → 集成分支（场景 1-3；场景 4 跳过）
• [ ] 执行 flow.sh verify <issue> --confirm
• [ ] 执行 flow.sh archive <issue>

Agent 不得：

• [ ] 未等用户确认就执行 merge 或 verify --confirm
• [ ] 创建或删除任何分支
• [ ] 删除工作树（verify-switch 和 archive 负责）
• [ ] 跳过 merge 直接 verify --confirm（场景 4 除外）

E. Done

flow.sh verify <issue> --confirm

前置：Plan 状态 = verifying，User Validation checkbox 已勾选。

有工作树的场景（场景 1-3）还要求 feature 分支已合并到集成分支， 脚本通过 Verification Commit SHA 或 branch ref 检测合并状态。

脚本在集成分支提交 Plan-only commit（verifying → done）。

F. Archive

flow.sh archive <issue>

前置：Plan 状态 = done。脚本归档 Plan、清理 worktree、更新 Issue 链接。

人类授权门

| 命令 | 用户信号 | |------|---------| | approve --confirm | "审批通过"、"approved"、"可以开始" | | verify --confirm | "验证通过"、"没问题"、"validation passed" | | reset | "重置"、"reset" |

submit 不需要用户授权——Plan 审阅通过后 agent 可直接执行。approve 不带 --confirm 直接报错，提示使用 submit。

分支归属

| 阶段 | 归属分支 | 提交者 | 内容 | |------|---------|--------|------| | planning / submit / approve | 集成分支 | 脚本 | Plan 文件状态变更 | | executing（实施代码） | feature 分支 | agent | 实施产物（代码 + checkbox） | | complete | feature 分支 | 脚本 | Plan status → verifying + Verification Commit SHA | | verify --confirm | 集成分支 或 feature 分支 | 脚本 | Plan status → done（SHA 或 branch ref 检测 merge） | | agent merge feature → 集成分支 | 集成分支 | agent | 代码 merge（不删 feature 分支） | | archive | 集成分支 | 脚本 | Plan 归档 + 删 worktree + 删 feature 分支 |

--no-worktree 模式：无 feature 分支，全部阶段在集成分支。

委派规则

| 原则 | 说明 | |------|------| | 优先 wopal_task | 委派时必须优先用 wopal_task，不可用时才用 Task | | 委派前检查 | 加载记忆"委派"、检查路径（基于空间根的相对路径）、确认项目上下文 | | 活动 Plan 路径 | 委派 prompt 使用 feature 分支 worktree 中的 Plan 路径 | | Done checkbox 指令 | 委派 fae 的 prompt 必须包含"完成后勾选对应 Task 的 Done checkbox" + "每完成一个 task commit git" | | 树交接失败 | complete 因脏树报错 → 要求 fae 提交代码后重试 | | 委派边界 | Plan Task → 委派 fae；单文件小变更（删几行、改配置）→ 直接执行，不委派 | | 强依赖处理 | 多 Task 存在强逻辑依赖时，整组委派给单个 fae，禁止拆分导致上下文丢失 | | 非 dev-flow 的 rook | 对话模式下小修小补，委派 rook 前先征得用户同意；dev-flow 中的 rook 审查自动执行 | | 回复复用优先 | rook/fae 完成后，修复和复审必须 reply 续原 task，禁止 finish 后新开。前提：上下文 < 50%；> 50% 时 finish 后新开 |

不要这样做

• 跳过 dev-flow 直接手动操作 — Issue/Plan 驱动的任务必须走 flow.sh 命令链
• 直接调 gh issue create 绕过 flow.sh — Issue 创建必须走 flow.sh issue create，脚本通过 detect_space_repo 自动定位空间仓库，无需也不允许手动指定 --repo。直接调 gh 会导致 Issue 创建到错误仓库 = 严重失职
• 跳过 rook 审查直接 submit 或 complete — Plan 审查和实施审查都是强制门禁（fix 类型 Plan 的 Plan 审查除外）
• rook BLOCK 后强行 submit 或 complete — 必须修订后重审，最多 3 轮
• rook 复审新开 task — rook 返回 REVISE/BLOCK → fae 修复后，必须 wopal_task_reply 续审原 rook task，禁止 finish 后新开。新开会话丢失审查上下文，浪费 token
• checkbox 单独 commit — 实施产物 = 代码 + checkbox，同一次 commit
• 未实际验证就勾选 AC — 必须运行命令、检查输出，凭记忆打勾 = 严重失职
• 被 complete 报错催着补勾 — 应在 rook PASS 后立即实证，不是等到 complete 才发现
• User Validation 越权代勾 — checkbox 勾选权在用户
• grep/glob 搜索 Plan — 使用 flow.sh plan <name> 或 flow.sh plan status <name>
• approve 不带 --confirm — 报错退出，使用 submit 提审
• verify-switch 前未先移除 worktree — 脚本内已处理顺序（先 remove worktree 再 checkout），agent 不手动操作
• 合并后手动删除 feature 分支 — 分支由 archive 自动删除。verify --confirm 通过 SHA 检测 merge 状态，分支删除不影响检测
• 手动创建或删除分支 — 分支生命周期由脚本独占：approve --confirm 创建，archive 删除。Agent 唯一的分支操作是 merge
• 手动删除工作树 — 工作树由 verify-switch 或 archive 删除
• 跳过 complete 直接邀用户验证 — 代码提交 + rook PASS 后必须先 flow.sh complete 推进到 verifying，然后才能进入用户验证。未达 verifying 前请求用户验收 = 严重失职
• 归档时清理未声明的资源 — archive 只处理 Plan metadata 中声明的 Worktree/分支。看到名字相似不等于归属相同，必须确认。误删用户活跃分支 = 严重失职
• 在 dev-flow 中加载 git-worktrees 技能 — dev-flow 的 worktree 创建/清理由 flow.sh approve 和 flow.sh archive 脚本内置管理，禁止加载 git-worktrees 技能或手动执行 worktree 命令

参考

| 文件 | 用途 | |------|------| | references/commands.md | 命令完整参数与使用模式 | | references/plan-guide.md | Plan 编写详细指导：TDD、AV/UV 规则、Metadata、委派 prompt、分支归属 | | references/issue-guide.md | Issue 编写指南：标题格式、body 结构、同步规则、Plan 命名 | | references/troubleshooting.md | 错误处理、边缘场景 |