MoonCoder-HAPPY/SpecWorkflow

English | 中文

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

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

功能

阶段	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/<feature-slug>/ 目录下，后续每一轮都能接得上。

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/<feature-slug>/
  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.