Demand Workflow

Demand Workflow 是一个 Agent Skill，用于将复杂的产品或编码需求整理成清晰的 spec，并在用户批准后，可选生成 implementation plan，或通过持久化 CSV 工作流执行。

它适合在用户显式指定 demand-workflow 时，为复杂需求提供轻量但可恢复流程：先澄清需求，写下意图，等待批准，再通过可追踪的状态、review、验证和恢复机制推进执行。

能力概览

• 在用户显式指定本 skill 后，判断请求应进入哪个工作流阶段。
• 对小改动和简单一步任务自动退出。
• 一次只问一个关键问题，逐步澄清需求。
• 在实现前生成详细 spec。
• 可选生成 implementation plan，明确文件结构、任务依赖和验证方式。
• 在用户明确批准执行前不修改业务代码。
• 可将已批准且明确要求执行的 spec 或 plan 转换为可执行 CSV 任务。
• 根据任务规模和风险选择 light、standard 或 strict 执行级别。
• 跟踪实现、review、验证和 Git 提交状态。
• 支持从中断的执行状态中恢复。
• 强制 CSV 任务内容和提交正文使用中文自然语言。

适用场景

适合：

• 新功能。
• 跨文件或跨模块改造。
• 架构或行为变更。
• 需求模糊，需要先明确范围和验收标准。
• 需要在实现前沉淀书面 spec。
• 需要持久状态和恢复能力的长任务。

不适合：

• 小文案修改。
• 简单配置更新。
• 需求明确的单文件修复。
• 普通问答或代码解释。
• 用户明确要求跳过流程，且不涉及高风险、跨多文件复杂变更或可恢复执行需求的任务。

工作流

需求
  -> 路由判断
  -> 澄清需求
  -> 比较方案
  -> 选择执行级别
  -> 编写 spec
  -> 等待批准
  -> 可选生成 plan
  -> 可选生成 CSV
  -> 逐项执行
  -> review、验证、提交
  -> 必要时恢复或追加后续任务

本工作流采用三层产物模型：

• spec：需求与设计，回答“做什么、为什么、边界、方案、验收”。
• plan：可选实施计划，回答“怎么做、改哪些文件、任务依赖、如何验证”。
• CSV：执行状态机，负责进度、证据、review 和提交闭环。

plan 不是强制阶段。可以走 spec → plan → CSV/执行，也可以直接走 spec → CSV/执行。

目录结构

demand-workflow/
├── SKILL.md
├── README.md
├── agents/
│   └── openai.yaml
└── references/
    ├── routing.md
    ├── discovery-and-spec.md
    ├── writing-plan.md
    ├── csv-schema.md
    ├── mission-csv.md
    └── recovery-and-review.md

运行产物会写入目标项目：

.agents/workflow/
├── specs/
├── plans/
├── tasks/
└── reviews/

安装

Skills CLI

如果你使用 open agent skills 生态的 Skills CLI，可以直接从 GitHub 安装：

npx skills add xuanwolei/demand-workflow

如果使用 pnpm：

pnpm dlx skills add xuanwolei/demand-workflow

该方式要求仓库根目录就是一个标准 skill 目录，即包含 SKILL.md、README.md、references/ 等文件。

Codex

安装为全局 skill：

~/.agents/skills/demand-workflow/

或安装到单个项目：

<project>/.agents/skills/demand-workflow/

Codex 会读取：

agents/openai.yaml

默认策略禁止隐式触发，只允许用户显式指定后使用：

policy:
  allow_implicit_invocation: false

Claude Code

安装为 Claude Code 全局 skill：

~/.claude/skills/demand-workflow/

Claude Code 会根据 SKILL.md 的元数据判断何时使用该 skill。

如需项目级说明，可在项目 CLAUDE.md 中加入短规则：

只有用户显式指定 demand-workflow 时，才使用 demand-workflow。
小改动或一步任务不要使用 demand-workflow。

手动触发模式

本 skill 默认不主动发现、不隐式触发：

• Codex 侧通过 agents/openai.yaml 设置 allow_implicit_invocation: false。
• Claude Code 侧通过 SKILL.md description 明确只在用户显式点名时使用。
• 典型触发方式：使用 demand-workflow 帮我整理这个需求、$demand-workflow 继续执行这个 CSV。

触发策略

该 skill 设计为手动触发，不主动接管复杂任务或小任务。

用户显式指定本 skill 后，第一步仍会做路由判断：

• 复杂需求：在已显式指定本 skill 的前提下，进入需求澄清和 spec 阶段。
• 小任务：退出工作流，直接处理。
• 已批准且明确要求执行的 spec、plan 或 CSV：进入对应执行路径。
• 用户只要求整理需求或生成 spec：进入 spec-only 模式，生成 spec 后停止。
• 用户只要求生成 plan：必须基于已批准 spec 生成 plan，生成后停止。
• 恢复请求：扫描未完成的工作流状态。

执行级别

Demand Workflow 会根据需求规模、风险和恢复需求选择执行级别。默认选择能满足质量要求的最低流程级别。

light

用于已经经过 spec 批准并明确批准执行的轻量任务；普通小需求在路由阶段退出工作流。

• 不生成 CSV。
• 不生成 REVIEW-01。
• 直接实现、验证、提交。

standard

用于多步但风险可控的任务。

• 生成 CSV。
• 使用简化 REVIEW-01。
• 不强制多轮 review。

strict

用于高风险、长任务或需要强审计的任务。

• 生成 CSV。
• 使用完整 REVIEW-01。
• 执行任务专属声明/证据检查。
• 严格记录受限验收。
• 可追加后续任务和后续 review。

硬规则：

• 涉及安全、权限、支付、删除、数据迁移、不可逆操作：使用 strict。strict 不等于授权危险操作，删除数据、覆盖未提交改动、数据库结构变更、生产 API 调用等仍需再次明确确认。
• 用户要求完整审计、强 review、可恢复执行：使用 strict。
• 已进入 workflow、已完成 spec 且获得执行批准后，如果用户要求轻量处理，优先 light，但不能覆盖高风险硬规则。
• 不确定时选择 standard。

Spec 产物

Spec 写入：

.agents/workflow/specs/

一份 spec 通常包括：

• 背景。
• 目标。
• 非目标。
• 用户场景。
• 推荐方案。
• 备选方案。
• 功能需求。
• 数据与状态。
• 交互与边界行为。
• 技术约束。
• 执行级别。
• 验收标准。
• 验证建议。
• 风险与待确认问题。
• 执行拆分建议。

Spec 获得批准前，不应进入实现。仅批准 spec 不等于批准执行；只有用户明确说“批准并执行”“按这个执行”“批准，拆成 CSV 执行”或“可以开始改代码”时，才进入执行。

Plan 产物

Plan 是可选阶段，写入：

.agents/workflow/plans/

一份 plan 通常包括：

• 来源 spec。
• 目标。
• 架构与策略。
• 全局约束。
• 文件结构和文件职责。
• 任务拆分。
• 每个任务的输入依赖、输出接口、实施步骤和验证方式。
• Spec 覆盖检查。
• Plan 自检。

Plan 生成后也必须停止等待用户确认。仅批准 plan 不等于批准执行。

如果存在已批准 plan，后续 CSV 优先从 plan 拆解；如果没有 plan，可以直接从 spec 拆解 CSV。

CSV 执行

当用户批准 spec 或 plan 且明确选择执行时，standard 或 strict 级别可以生成：

.agents/workflow/tasks/YYYY-MM-DD_HH-mm-ss-<topic>.csv

CSV 是执行阶段的状态源。

执行前必须检查 Git 工作区；若存在与当前任务无关的既有改动，不得暂存无关文件。详细规则见 references/mission-csv.md，包括基线记录、同文件 dirty 处理、按 hunk 暂存和 existing_dirty_worktree notes 标签。每条普通任务都应完成：

实现 -> 初次 review -> 回归 review -> 自我验收 -> Git 提交

每个 standard 或 strict CSV 都包含一条 REVIEW-01。该 review 用于检查最终交付是否真正满足已批准的 spec，并包含对应级别要求的声明/证据检查项。

语言规则

面向用户的自然语言产物默认使用简体中文。

CSV 中以下字段必须使用中文自然语言：

• title
• description
• acceptance_criteria
• review_initial_requirements
• review_regression_requirements
• notes 中的自然语言值

协议标识可以保留英文：

• CSV 表头。
• 枚举值。
• MCP 工具 id。
• skill 名称。
• 文件路径。
• 命令。
• 代码符号。

Git 提交标题建议使用 conventional commit 风格。常用 type 包括 feat、fix、docs、test、refactor、perf、style、chore、build、ci、revert。

Git 提交正文应使用自然中文说明，面向未来维护者描述工程事实，不要写成 Agent 执行流程日志：

<1-2 行说明变更目的和主要做法。>

验证：
- <实际运行的命令或验证说明>

备注：
- <可选；仅在有风险、受限验收、人工步骤或剩余事项时填写；没有就省略>

避免使用 Why、Why this works、Validation、Remaining 等英文提交正文字段，也避免把 demand-workflow、skill、agent、standard、strict、REVIEW-01、CSV 状态机 等内部执行术语写进业务仓库提交说明。需要提及工作流产物时，优先使用“任务账本”“复核记录”“验证证据”“交付闭环”等中性表达。git_state=已提交 的证据可以来自 notes 中的 commit_hash，也可以来自包含该 CSV 状态变更的 Git 提交，不要求当前提交包含自身 hash。

恢复

恢复时，skill 会扫描工作流 CSV，并从第一个未完成任务继续。

恢复前会检查：

• CSV 表头。
• 状态枚举是否合法。
• git_state 是否与提交证据一致。
• 部分写入或损坏的 CSV 是否需要用户确认。

Review 日志写入：

.agents/workflow/reviews/

维护建议

• SKILL.md 保持简洁，只放入口规则、文件读取顺序和硬约束。
• 详细行为放在 references/ 中。
• 修改 CSV 行为时，同步更新 csv-schema.md、mission-csv.md 和 recovery-and-review.md。
• 修改触发策略时，同步更新 SKILL.md 和 agents/openai.yaml。
• 每次修改后重新运行 skill 校验。

建议校验命令：

python <skill-creator>/scripts/quick_validate.py demand-workflow

建议扫描以下高风险英文模板残留：

WHEN
THEN
follow-up
gaps_found
vision_met
Source spec
Review agent
Why this works
Validation
Remaining

致谢

本工作流参考了以下项目中的优秀思路：

• obra/superpowers
• flowing-water1/Missions