sampx/dev-flow
skills/dev-flow/SKILL.md
Issue/Plan 驱动的开发工作流。⚠️ 任务需以 GitHub Issue 或 Plan 为执行载体。 🔴 Trigger: "#14"、"这个 issue"、"出个计划"、"开始开发"、"执行计划"、Plan 生命周期推进（approve/complete/verify/archive）、从 PRD 拆分 Issue。 ❌ Skip: spec 驱动流程、单纯研究/讨论/解释、不需 Issue/Plan 的临时小改动。
$ install --global
skillsauthnpx skillsauth add sampx/agent-tools dev-flowInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 31, 2026, 4:41 AM247.1s137 files scanned
SKILL.md
- name:
- dev-flow
- description:
- |
- 🔴 Trigger:
- #14"、"这个 issue"、"出个计划"、"开始开发"、"执行计划"、Plan 生命周期推进（approve/complete/verify/archive）、从 PRD 拆分 Issue。
- ❌ Skip:
- spec 驱动流程、单纯研究/讨论/解释、不需 Issue/Plan 的临时小改动。
dev-flow — Issue / Plan 驱动开发流程
统一状态机：planning → executing → verifying → done
统一命令链：plan → approve → approve --confirm → complete → verify --confirm → archive
核心原则
- 先进入 Plan 生命周期，再开始实施。
approve --confirm和verify --confirm都是人类授权门。complete表示"实施完成，代码已提交，进入用户验证阶段"，不代表"用户已验证通过"。archive只做 push + 归档收尾，不承担验证职责。- Plan 必须先通过
flow.sh plan ...生成或定位 stub；禁止手写创建 Plan 文件，禁止自行猜测 Plan 路径。
最容易遗漏的两步
- Plan 写完后：
--check→ 必要时sync <issue> --body-only→approve→ 等用户审批。 - 实施完成后：每个 Task 运行 Verify 通过后立即勾选 Done → 完成 Agent Verification →
complete→ 再等用户验证。
Done 勾选范围：Implementation 中每个 Task 的 - [ ] checkbox，以及 ### Agent Verification 中的所有 checkbox。complete 强制校验全部勾选。
状态机与命令映射
| 命令 | 前置状态 | 后置状态 | 作用 |
|------|---------|---------|------|
| plan | 无 | planning | 创建或定位 Plan |
| approve | planning | planning | 校验 Plan，提交方案评审 |
| approve --confirm | planning | executing | 用户审批通过，开始实施 |
| complete | executing | verifying | 实施完成，提交代码 |
| verify --confirm | verifying | done | 用户验证通过 |
| archive | done | 归档 | push 代码，归档 Plan，关闭 Issue |
命令顺序不合法时，回到正确状态顺序执行，不要强行推进。
人类授权门
| 命令 | 用户信号 |
|------|---------|
| approve --confirm | "审批通过"、"approved"、"可以开始" |
| verify --confirm | "验证通过"、"没问题"、"validation passed" |
| reset | "重置"、"reset" |
禁止未经授权执行任何 --confirm；禁止跳过 approve 直接开工。
标准流程
A. 进入 planning
Issue 驱动：flow.sh plan <issue>。无 Issue：flow.sh plan --title "..." --project <name> --type <type>。
Plan 目录规则
- 先执行
flow.sh plan ...生成或定位 stub，再编辑内容。 - Plan 目录由
--project决定；--project是必填参数。 - 标准项目：
projects/<project>/docs/plans/ - ontology-worktree：
.wopal/docs/plans/ docs/projects/<project>/plans/是 DEPRECATED 只读回退，禁止新写入。
--project 必填
--project 是 plan 命令的必填参数。不存在"空间级 Plan"——每个 Plan 必须归属一个项目。
A+. Plan 编写要点
业务规则影响评估：
Plan 编写时，读取产品已有 projects/<project>/docs/BUSINESS_RULES.md，判断本次改动是否影响业务规则：
| 场景 | Plan 中标注 |
|------|-----------|
| 引入新业务约束 | ## Business Rules Impact → 新增: BR-NNN 规则描述 |
| 改变已有规则判定条件 | ## Business Rules Impact → 修改: BR-NNN 旧→新（原因） |
| 系统设计变更使规则不再适用 | ## Business Rules Impact → 废弃: BR-NNN 废弃原因 |
| 纯技术重构、bug 修复（无新约束） | N/A — 无业务规则变更 |
同步时机：complete 前 Wopal 负责将 ## Business Rules Impact 中非 N/A 的变更同步到 BUSINESS_RULES.md，然后勾选同步确认 checkbox。
B. Plan 写完后，方案评审
- 完成 Plan 编写，运行
flow.sh plan <issue> --check - Issue 驱动时若 Plan 影响 Issue body，执行
flow.sh sync <issue> --body-only - 委派 rook 审 Plan（强制）—— prompt 契约格式见 agents-collab
- 根据 rook 判定：PASS → 继续；REVISE/BLOCK → 修订后重审（最多 3 轮）
- 通过后：
flow.sh approve <issue>，停止推进，等用户审批 - 用户授权后：
flow.sh approve <issue> --confirm（默认创建 worktree 隔离）
禁止：跳过 rook 审查直接 approve、rook BLOCK 后强行 approve。
C. 进入 executing 后实施
每完成一个 Task 立即勾选 Done checkbox，不积压。
委派体系：
- 实施 Task → 委派 fae。Wopal 职责：切片 → 委派 → 验证 → 推进下一 Wave
- 审查 Task → 委派 rook。rook 返回 PASS/REVISE/BLOCK
Plan 切片 → 委派 fae 实施 → 委派 rook 审查 → 根据结果推进/修正 → 下一 Wave
fae 保留策略：rook 审查未完成前不 finish fae task（上下文 >50% 例外）。rook REVISE/BLOCK 时 reply 同一 fae 修复，不新开 task。
rook 委派时机：
- Plan 写完后（approve 前）— 审方案质量
- fae 最终交付后（complete 前）— 最终审查
rook 契约格式见 agents-collab。委派 rook 前不预加载 df-plan-review / df-implement-review —— rook 自行加载。
委派 prompt 必须：末尾附加 Done checkbox 更新指令（格式见 references/plan-authoring.md）。
D. 实施完成后，进入用户验证
- 确认所有 Task Done 已勾选
- 委派 rook 审 fae 实施结果（强制，prompt 格式见 agents-collab）
- 根据 rook 判定：PASS → 继续；REVISE/BLOCK → fix + re-review（最多 3 轮）
- 通过后勾选
### Agent Verification - 同步业务规则：如 Plan 的
## Business Rules Impact非 N/A，将变更同步到projects/<project>/docs/BUSINESS_RULES.md，勾选 Plan 中的同步确认 checkbox flow.sh complete <issue>
complete 硬门控：所有 Task Done ✓ + Agent Verification ✓ + rook PASS ✓。
worktree 隔离下的验证切换
complete 后代码在 feature 分支。用户验证需切换运行时环境：
Phase 1 — 切换验证：
flow.sh verify-switch <issue>
自动完成：移除隔离 worktree → 检出 feature 分支 → 记录主分支。提示用户重启验证。
Phase 2 — 合并回主分支（用户确认验证通过后，Wopal 自动执行）：
flow.sh verify-switch <issue> --merge
自动完成：检出主分支 → merge feature 分支 → flow.sh verify <issue> --confirm。
⚠️ 硬约束：合并（Phase 2）必须在用户明确确认验证通过后执行。禁止手动 merge，统一使用本命令。
E. 用户验证通过后进入 done
用户确认后：flow.sh verify <issue> --confirm。前置：Plan 状态 = verifying，User Validation 最终 checkbox 已勾选。
F. 最后归档
flow.sh archive <issue>。前置：Plan 状态 = done。
Roadmap
产品阶段规划前置工作流。从 PRD/DESIGN 文档生成 phase 文档和 Issue。
flow.sh roadmap <prd-path> [--product <name>] [--project <name>] [--yes] [--dry-run]
四阶段流程：
- Analyze（全自动）：解析 PRD，提取 Phase 定义
- Discuss（交互式）：逐 Phase 与用户确认目标、范围、退出条件（
--yes跳过） - Produce（全自动）：按模板写入 phase 定义文档到
phases/目录 - Decompose（全自动）：为每个涉及项目创建 Issue，注入 Product/Phase 元信息
Issue 标题格式：feat({scope}): {phase-id} — {goal-summary}（≤72 chars）
Issue 编写
创建 Issue
以 --body-file 为主路径——agent 直接写 markdown 文件，不需要通过 CLI 参数拼装 body：
flow.sh issue create --title "feat(scope): desc" --project <name> --body-file body.md
--type 可选覆盖（默认从标题自动推断），--body-file 指向包含完整五段结构的 markdown 文件。
写入 Issue body
flow.sh issue write <issue> --body-file <path> # 全量替换 body
flow.sh issue write <issue> --append <path> # 追加到 body 末尾
--body-file：用文件内容替换整个 Issue body--append：在现有 body 末尾追加文件内容，用\n\n分隔，保留已有内容
decompose --from ROADMAP.md
从 ROADMAP.md 的 Slices 表生成 Slice Issues：
flow.sh decompose-prd --from ROADMAP.md [--product <name>] [--dry-run]
Slices 表格式见 ROADMAP.md Slices 语法规范。
主流路径
| 场景 | 命令路径 |
|------|----------|
| Issue 驱动 | plan → --check → sync(如需) → approve → approve --confirm → complete → verify --confirm → archive |
| Plan 驱动 | plan → approve → approve --confirm → complete → verify --confirm → archive |
worktree 隔离（默认）
worktree 是默认执行策略。approve --confirm 自动创建 worktree 隔离环境；只有 --no-worktree 才跳过。
flow.sh approve <issue> --confirm # 默认创建 worktree
flow.sh approve <issue> --confirm --no-worktree # 跳过 worktree
WorktreeContext 结构化元数据（9 字段）自动写入 Plan metadata：
- **Worktree**:
- enabled: true
- project_type: standard
- branch: feature/test-1-slug
- path: .worktrees/project-issue-1-slug
- repo_root: /path/to/project/repo
- base_branch: main
- merge_target: main
- verify_mode: direct # standard=direct, ontology=switch-runtime
- cleanup_policy: archive
验证目录结构：ls .worktrees/<project>-issue-<N>-*/
禁止在主工作空间编辑——所有变更在 worktree 内进行。
Git 语义（repo-aware）
Plan 文件在其所属 repo 中提交和推送：
| 阶段 | Git 行为 |
|------|---------|
| approve --confirm | Plan-only 提交到 PlanLocation.repo_root（planning → executing） |
| complete | 同仓（Plan 与代码同一 repo）：代码+Plan status=verifying 单次提交；不同仓：分别提交 |
| verify --confirm | Plan status=done 提交到 Plan 所属 repo |
| archive | git mv/commit/push 在 Plan 所属 repo 内完成 |
| ontology-worktree complete | .wopal 内代码+Plan 单次提交 |
不要这样做
- Task 完成但不勾选 Done checkbox
- Agent Verification 未完成就推进
- 忘记执行
complete - 跳过 rook 审查直接 complete
- rook BLOCK 后强行 complete
- 用户验证通过前 merge feature 分支到主分支——提前 merge 留下 revert 补丁，后续 merge 产生大量冲突
参考
对所有命令，使用 flow.sh <cmd> --help 获取完整参数。以下文档补充使用模式和边缘场景：
| 文件 | 用途 |
|------|------|
| references/commands.md | 命令概览与使用模式 |
| references/plan-authoring.md | Plan 质量门、AC、TDD、委派 prompt 格式 |
| references/troubleshooting.md | 错误处理、边缘场景、PR 工作流 |
| templates/plan.md | Plan 骨架模板 |
| templates/issue*.md | 各类型 Issue 模板 |
| references/plan-validation.md | Plan 校验规则 |
| references/tdd-guide.md | TDD Task 编写指南 |
| references/issue-format.md | Issue 标题、Plan 命名规范与 Issue body 五段结构 |
Related Skills
sampx/ellamaka-config
tools
VerifiedTrustedCommunity
Configure ellamaka, a fork of OpenCode with wopal-space mode. MUST use for any task about ellamaka config, agent frontmatter, permission rules, model/provider selection, formatter settings, config loading order, or why config changes are ignored. Trigger on requests about ellamaka or opencode config files, agent permission overrides, restricting subagents, custom/plugin tool permissions (e.g. wopal_task_*), disabling tools, configuring providers or models, formatter setup, config precedence or layering, or debugging settings that do not take effect. Use this skill even when the user says "opencode" if the actual runtime, config path, or behavior is ellamaka. Prefer this skill whenever the answer depends on the difference between ellamaka and upstream opencode, including wopal-space config loading, plugin tool permissions, or agent frontmatter precedence.
1SKILL.mdUpdated May 31, 2026
sampx/df-plan-review
development
VerifiedTrustedCommunity
Plan quality verification for dev-flow. Goal-backward analysis ensures plans WILL achieve their stated goal before execution burns context. ⚠️ MUST use when: (1) Reviewing Plan quality before approve (2) Wopal completes Plan writing and needs quality gate (3) User asks to "check plan", "verify plan", "review plan" (4) Plan enters planning status and needs pre-execution validation 🔴 Trigger automatically when Plan is ready for review, even if user doesn't explicitly say "review". Agent: rook (read-only verification subagent) Mode: verification, not execution
1SKILL.mdUpdated May 31, 2026
sampx/df-implement-review
development
VerifiedTrustedCommunity
Review implementation results for goal achievement and code quality. Supports both Plan-backed review and planless diff review. ⚠️ MUST use when: (1) Wopal delegates rook to review fae implementation output, (2) Prompt contains "review_type: implementation", (3) Prompt contains changed code file list or Plan path + implementation scope, (4) Any code review request from Wopal. 🔴 Trigger even when user does not explicitly mention "review" if the task involves verifying implementation results. This skill is rook-exclusive (only rook agent can load it).
1SKILL.mdUpdated May 31, 2026
sampx/agents-collab
tools
VerifiedTrustedCommunity
Foundation rules for how Wopal collaborates with sub-agents such as fae and rook. ⚠️ MUST load before ANY delegation — covers delegation tool APIs, task lifecycle, notifications, status handling, and recovery. 🔴 Trigger: "delegate", "let fae implement", "fae task", "rook review", "check task status", "cancel task", "abort task", "agent collaboration", "委派", "让 fae 执行", "fae 任务", "rook 审查", "检查状态", or any intent to hand work to a sub-agent. 🔴 Never delegate without loading this skill first. Skipping it is serious negligence. Note: this skill does not include workflow-specific prompt templates such as dev-flow templates. Those belong to the corresponding workflow skills.
1SKILL.mdUpdated May 31, 2026