devflow

Files (4)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• reuse_scan.py · scripts/

SKILL.md (first lines)

# Devflow

对外只有五个节点：`Brainstorm → Save Design → Improve Design → Impl → Review`。
节点负责自己的输入和产物，workflow 负责顺序、授权和返工；不另建五套 skill。
设计优先，把关键决策和失败语义在实现前说清，不把“90% 设计、10% 实现”变成固定时间配额。

## 调用与编排

- **单节点**：例如 `$devflow Save Design，把已确认方案保存到 docs/design.md`、`$devflow Improve Design docs/design.md`、`$devflow Impl，按已批准设计实现`、`$devflow Review --base main`。明确只做某一步时记为 `mode=node`；完成该节点即停止，不自动启动下一节点。节点名使用上面的五个名称，大小写/自然语言同义说法均可识别；Implementation 映射 Impl，Deepreview 映射 Review。
- **整条或明确组合**：例如 `$devflow 走完整研发流程`、`$devflow 从现有设计开始，优化后实现并审查`。记为 `mode=workflow`，列出本次授权的节点序列；只有 workflow 可以衔接节点。仅说“用 devflow”时先澄清任务并建议路径，不猜已经获得实现授权。
- 先检查当前节点必要输入。已有完整、有效且可回读的输入可直接使用，不为补节点名重跑 Brainstorm/Save Design；输入缺失时只补缺项，涉及其它节点的写操作先确认，不静默扩大单节点任务。PRD 交接只是证据输入，不能虚构前序节点已经执行或通过。
- 原子化指职责与授权边界，不承诺文件操作具备数据库事务。每个节点报告产物、实际验证、未决项和退出状态；输出文件存在不等于节点通过。

### 简单 / 完整预设

两个预设复用同一套五节点及质量规则，都包含 Improve Design 内的四路 Panel；不能为了简单而减少 reviewer。已有输入对应的前序工作只核验，不重复执行。

- `simple`：适合行为清晰、局部、可独立验证的任务；设计可简短，合并展示范围与后续动作，不要求长篇备选方案。
- `full`：适合重要设计取舍、跨系统契约、schema/migration、权限、并发/状态机、交易/账本、幂等或恢复行为变化；充分展示决策、失败场景和验收，再请用户确认实现。文件数量或仅位于这些模块中不单独构成理由。
- workflow 先基于源码事实给出建议、依据、节点序列、所需内部检查及差别，最终由用户选择。没有答复或选择含糊不代表接受推荐；已明确选择则不重复确认。单节点不强制选择 simple/full。
- Planreview 是 Improve Design 的按需内部检查：项目/用户要求，或仍有重要设计风险需对抗性验证时使用，并说明具体原因；不因 full 标签固定加一轮。两个预设均不豁免项目强制检查。
- 发现新事实影响路径建议时说明影响并让用户决定，不自动切换。切换保留有效证据及 review 计数，不绕过未关闭缺陷或失败检查。

### 决策与返工

只在目标/范围、重要产品或设计取舍、实现授权及新的副作用边界上等待确认；已有明确授权在原范围内持续有效，不为节点完成或普通修复重复确认。等待期间不得提前执行依赖该决定的节点。

workflow 中，已确认的目标与范围可进入 Save Design，再进入 Improve Design。完成设计优化后展示实际设计版本、关键决策、验收及 workspace 决策；仅在已有授权覆盖这些输入时进入 Impl，否则请求实现授权。已授权的 Impl 完成后进入 Review。最终报告即收尾，不要求再回复“完成”。

Review 只审查，不改业务代码或设计；问题交由 workflow 返回责任节点：实现缺陷回 Impl，设计缺口回 Improve Design，目标/范围变化回 Brainstorm。授权范围内的普通实现修复合批完成后验证并重审；策略或权限变化先询问。单独 Review 只报告 findings 和建议下一节点，不自动修复或重启全流程。

## 节点契约

| 节点 | 必要输入 | 输出与退出条件 |
| --- | --- | --- |
| Brainstorm | 需求、相关现状、约束 | 目标、非目标、范围、验收、取舍及未决项；必要决定已确认 |
| Save Design | 已确认目标/方案、可回读的依据、保存目标 | 唯一 design_doc 及快照引用，决策和验收可独立阅读；涉既有设计复用时含复用清单（不新增概念、名称或实现时记 `not-applicable`）；缺失选择不得代填 |
| Improve Design | design_doc 快照、目标/边界、事实、允许的设计写入范围 | 四份独立建议、主 agent 裁决、更新后的同一设计及版本；无未决 blocking finding，适用内部检查通过 |
| Impl | 已批准设计版本、实现授权、workspace/base、验收 | 范围内改动、验证证据及 scope 检查通过；单节点到此停止 |
| Review | 正确 base 下完整改动、目标/设计依据、可用验证证据 | review artifact、覆盖、verdict、findings 与风险；无 blocking finding 且证据充分才通过 |

Review 可检查已有改动，即使尚无正式设计文档；以真实需求/授权记录核对已知行为，并明确设计一致性及验证的覆盖缺口，不伪造设计批准、不替用户创建方案。缺口影响结论时保持未通过。

## 共用边界与证据

- 读取适用 AGENTS.md 和当前节点相关源码、配置、测试及文档；只加载当前节点需要的 companion skill。Save Design 与 Improve Design 的主 agent 使用可用 ponytail（已激活不重复初始化）：在已确认目标和验收内，先核对拟新增的概念、抽象与依赖是否必要，优先复用现有 owner、标准库和平台能力，收敛为最小可交付设计；四路 Panel 保持独立，不强制使用 ponytail。Impl 继续使用 ponytail 约束具体代码；Improve Design 仅在内部检查适用时加载 planreview；Review 使用 deepreview。OM 设计/实现涉及文档时使用可用 om-doc-hygiene，其余按仓库 owner 约定。
- companion 缺失记 `fallback:unavailable`，主 agent 执行同等必要检查和 artifact 要求；不适用记 `not-applicable`，不得伪称 pass。不自动安装或配置工具。
- 原始 goal、non-goals、scope、success signals、本次授权的实现范围（对应 design_doc 中本次实际授权的 slice/块及各自成功标准）和用户确认依据构成 scope contract，只落盘一处：`<worktree>/.devflow/scope.md`（git 跟踪，随提交同步）。已有 `codex/<task>-devflow-handoff.md`、`docs/gateflow/<task>/scope.md` 或 prdflow 交接的 `prd_doc` 只作为交接输入，进入时把仍有效的授权、范围、产品决定与 design_ref 迁入该文件，不并行维护两份。产品合同（prd_doc）与实现设计（design_doc）各自用 `prd_doc_ref` / `design_ref` 绑定路径加内容 hash；无产品合同的纯实现任务记 `not-applicable`。后续真实授权在该文件追加差异和引用，不能用新版设计或新版 PRD 覆盖原始批准。建议本身不是范围授权；范围外建议记 `deferred-with-owner`。
- 设计与实现绑定 `design_ref`：仓库路径加实际内容 hash，已有固定 commit/permalink 时一并引用；Impl 和 Review 核对同一版本。不得仅引用可变 main 链接。方案决策、理由及相关验收留在唯一设计 owner，避免 v2/final 副本。
- 研发结束时向 Delivery 交接 design_ref、实现及 review 证据。用户另行授权提交/PR时，建议将设计随提交保存，或在 PR 附本次版本的固定链接；无可访问链接时如实提供路径/hash，不编造 URL。
- commit/push/PR/merge/release/upgrade 及生产操作不属于这五个节点；已有旧交付授权不自动覆盖新的研发变更。

## Review 完成与重试

有效且未关闭的严重、高、中问题是 blocking finding。调用失败、输出缺失/无法解析/矛盾、材料截断或覆盖不足均为 `review-unusable`，不得当成无问题或通过。低风险不为清零而扩展范围，保留 owner、影响及后续去向。

Improve Design 的四人 Panel 必须有四个可用结果；无建议但有依据的结果可用。适用的 Planreview 和 Review/Deepreview 各自最多五次调用尝试（含失败），分别计数；第 5 次仍未通过时停下，未经明确授权不得第 6 次。返回责任节点修复、路径切换或上下文恢复不清零计数。

重审前由对应责任节点合批处理本轮范围内全部有效 blockers，完成所需验证，核对快照/base/授权和材料可读性；未就绪不派发，未调用不占尝试。Planreview 在 Improve Design 内对完整修订设计重审；Review 对全部当前改动重审，不只审修复文件。单节点 Review 无修复授权时只交回结果。

去重仅限同一检查、同一 reviewer 身份和同一有效快照。恢复时读取原 in-flight handle，不重复派发；内容/base/scope/依赖或验证环境变化时核验失效部分。四位 Panel reviewer 不能共用彼此结论，Panel 不能替代适用 Planreview 或 Review。仅复用仍有效的完整参考输入和检查证据，不用旧 verdict 代替变更后的重审。

## 进度与交接

scope contract、进度、`implementation_baseline` 与 inventory 指纹共用一个 `.devflow/scope.md`（上文），字段如下；conversation-only 结果不足以替代，不得只在交接摘要里留存。只在节点/内部检查边界、授权或内容变化时更新同一文件：

```yaml
# —— scope contract（原始批准，只此一处；授权差异见下方 authorization_diffs，不覆盖本段）——
goal: null
non_goals: []
scope: null
success_signals: []           # 有 PRD 时逐项溯源到 prd_doc 对应验收（章节/ID）；无 PRD 记 not-applicable
authorized_slices: []          # [{slice, design_doc_ref, success_signal, depends_on}]；success_signal 逐项列出本 slice 覆盖的验收，depends_on 列前序 slice；未授权块 deferred
slice_checkpoints: []          # [{slice, diff_fingerprint, validation, done}]；每片完成时落一条边界快照（可回退、可 bisect）
user_confirmation: []          # 用户确认原话/依据；转述不编造时间戳或消息 ID

# —— product & design & workspace 绑定（Impl/Review 核对同一版本）——
prd_doc: null                  # 产品合同（prdflow 交接的 PRD）路径；纯实现任务无产品需求记 not-applicable
prd_doc_ref: null              # 路径 + 内容 hash；有固定 commit/permalink 时一并引用，不引用可变 main
design_doc: null
design_ref: null               # 路径 + 内容 hash；有固定 commit/permalink 时一并引用，不引用可变 main
implementation_workspace: null
review_base: null

# —— 授权差异（追加；覆盖记录在 scope contract 之外，不覆盖原始批准）——
authorization_diffs: []        # [{when, what, ref}]

# —— 进度 ——
workflow_version: 2
mode: node                     # node | workflow
workflow_path: null            # simple | full；单节点不适用
node_sequence: []              # 只列本次授权节点
current_node: null
internal_step: null            # Panel | Revise | Planreview 等；不是独立外部节点
status: in_progress            # awaiting_user_confirmation | blocked | completed
next_action: "实际尚未完成的动作"
approved_scope_ref: null
path_approval_ref: null

# —— implementation_baseline（进入 Impl 时冻结，不得覆盖）——
implementation_baseline:
  design_doc: null
  implementation_workspace: null
  review_base: null
  head: null
  git_status: null             # git status --short 快照
  staged: []                   # [{path, hash, size}]
  unstaged: []                 # [{path, hash, size}]
  untracked: []                # [{path, hash, size}]

# —— 实现阶段 inventory / 指纹（随检查更新；不替代 Deepreview 完整走读）——
inventory: []                  # [{path, status, hash, size, type, mode, classification, evidence_ref}]

# —— 检查预算、飞行中与证据 ——
content_revision: null
planreview_round: 0
deepreview_round: 0
in_flight: []
evidence_paths: []

From liuxie066/liuxie-skills, MIT.

More from liuxie066/liuxie-skills