MoonCoder-HAPPY/SpecWorkflow

SpecWorkflow

SpecWorkflow 是一套可分享的 workflow skill pack，面向 DeepSeek Harness 和其它兼容 Agent Skills 的工具。它给 Agent 一条清晰路径：从粗糙需求开始，推进到需求澄清、实施规格、代码执行、交付检查、修复规划、bug 诊断和带来源的调研。

它不会把每个请求都拖进重流程。简单明确的修改可以直接处理；需求模糊、跨模块、影响产品体验、数据、权限、接口或发布风险的工作，才进入完整 workflow。

SpecWorkflow Architecture

功能

| 阶段 | Skill | 处理内容 |
| --- | --- | --- |
| 调研 | deep-research | 基于官方文档、API、标准、源码等一手来源做调研。 |
| 1 | to-grill | 需求质询、消除歧义、风险审查，并判断直接实施还是进入完整流程。 |
| 2 | to-spec | 编写可实施 spec、修订说明、验收标准、验证计划和可选 tickets。 |
| 3 | spec-do | 根据已批准的 spec、issue、修订或修复计划进行实施。 |
| 4 | do-review | 对照需求、spec、代码和证据做最终交付检查。 |
| 5 | fix-review | 把 must-fix review findings 转成修复 spec 和修复 tickets。 |
| 调试 | bugs-fix | 针对 bug、回归和性能问题做复现、根因定位、修复和证据留存。 |

安装

DSH

dsh plugin --profile web add specworkflow
dsh web

其它 Agent

npx specworkflow install codex

使用 -g 安装到全局目录：

npx specworkflow install -g codex

需要时把 codex 换成其它预设：

| 输入 | 项目安装位置 | -g 全局安装位置 |
| --- | --- | --- |
| codex, openai, agents, agent, agent-skills, agents-md, goose, zed, amp, sourcegraph-amp | .agents/skills | ~/.agents/skills |
| gemini, gemini-cli, antigravity, google-antigravity | .agents/skills | ~/.gemini/antigravity/skills |
| claude, claude-code, claudecode | .claude/skills | ~/.claude/skills |
| cursor, cursor-agent, cursor-native | .cursor/skills | ~/.cursor/skills |
| copilot, github-copilot, vscode, vs-code | .github/skills | ~/.github/skills |
| dsh, deepseek, deepseek-harness | .dsh/skills | ~/.dsh/skills |
| opencode, open-code | .opencode/skills | ~/.opencode/skills |
| windsurf, cascade | .windsurf/skills | ~/.windsurf/skills |
| cline, claudine | .cline/skills | ~/.cline/skills |
| roo, roo-code, roocode | .roo/skills | ~/.roo/skills |
| qwen, qwen-code, qwencode | .qwen/skills | ~/.qwen/skills |
| kiro | .kiro/skills | ~/.kiro/skills |
| kilo, kilo-code, kilocode | .kilo/skills | ~/.kilo/skills |
| augment, augment-code, augmentcode, auggie | .augment/skills | ~/.augment/skills |
| openclaw, claw | skills | ~/.openclaw/skills |

未识别的纯名称会直接报错，避免因为拼错而创建错误目录。如果当前工具不在预设里，请传入明确的项目级 skills 路径：

npx specworkflow install .my-agent/skills

带 -g 时，相对显式路径会从用户 home 目录解析。

快速开始

典型功能开发：

使用 to-grill 澄清这个需求，需求收口后再进入 to-spec。

简单修改保持简单：

把表格字体调大一点。

这类请求应该直接实施，不应该强行进入五阶段流程。

工作流

SpecWorkflow 的第一步不是写 spec，而是判断这件事值不值得进入 spec。很多请求本来就很小，比如改一段文案、调一个样式、补一个明显遗漏的判断；这类工作应该直接完成。

只有当需求开始牵涉产品含义、数据语义、权限边界、跨模块影响、发布风险，或者“做错了会很难收拾”时，才进入完整流程。同一件事产生的材料都放在同一个 .spec-workflow// 目录下，后续每一轮都能接得上。

to-grill -> to-spec -> spec-do -> do-review -> fix-review -> spec-do repair -> do-review

to-grill 负责把模糊需求压实。它不是机械提问，也不是把仓库里能查到的事实甩给用户确认；它会先自己读上下文、找现有实现、识别真正需要用户拍板的地方。到这一阶段结束时，应该已经知道这件事是直接改、暂缓、还是进入 spec，并留下可以交给下一步使用的需求结论。

to-spec 把结论变成实施契约。好的 spec 不只是“要做什么”，还要写清楚不做什么、哪些模块会受影响、数据和权限怎么处理、用户最终会看到什么、验收时看哪些证据。如果是在已有 spec 上做调整，它会记录修订和影响范围，而不是把历史上下文抹掉重写一份。

到 spec-do 才真正动代码。实施前先处理 git 分支、脏工作区和是否允许自动提交；实施时按已批准的 spec、tickets、修订或修复计划推进。临时证据、调试脚本、截图和运行记录可以放进 .spec-workflow，但长期存在的测试必须回到项目自己的测试目录。这里有一条硬规则：业务逻辑要真实接上，不能为了让验证变绿而 mock 掉系统本身。

实现完成后，do-review 接手判断能不能交付。它会把原始需求、spec、代码 diff、测试和证据放在一起看，找遗漏、回归、边界和验收缺口。review 不是顺手修代码的阶段，也不应该暗中扩大范围；它只负责给出清楚的 ship / no-ship 判断。

如果 review 发现必须修的问题，fix-review 会把这些 finding 收束成修复计划。它关心根因、优先级、验证方式和是否需要拆 ticket，然后把修复计划交回 spec-do。修完以后再回到 do-review，形成一个很短的闭环；直到结果可以交付，或者下一步确实需要用户做决定。

deep-research 和 bugs-fix 不属于主链上的固定阶段，更像两条随时可以插入的支线。遇到外部事实、官方文档、API 行为、标准差异时，先用 deep-research 把依据找齐；如果起点不是新需求，而是失败、回归、异常或性能问题，就直接走 bugs-fix，先复现和定位根因。

Goal Mode 是给单个 spec 用的连续执行开关。用户明确启用后，Agent 可以从实施一路跑到 review、修复规划、修复实施和再次 review，不必每个交接点都停下来等确认。但它不是无限授权；遇到产品选择、安全风险、git 决策、验证缺口、环境问题或 scope 变化时，仍然要停下来。

目录产出

SpecWorkflow 把 workflow 文件放在 .spec-workflow 下，避免把项目代码和 Agent 证据混在一起。

.spec-workflow//
requirements.md
spec.md
issues/
amendments/
implementation/
review/
repair-spec.md
repair-issues/
verification/
debug/
bugs/
research/

项目长期测试仍然放在项目原本的测试目录，不放进 .spec-workflow。

验证

安装到 DSH 后运行：

dsh --profile web --dump-config

组合配置里应该出现：

== specworkflow
- id: specworkflow
name: specworkflow

也可以直接询问 Agent 当前有哪些 SpecWorkflow skills，以及什么时候使用 to-grill。

卸载

dsh plugin --profile web remove specworkflow

把 web 换成你实际安装的 profile。

许可证

MIT. See LICENSE.