Workflow 命令执行逻辑总览
本页按 spec-first 当前的 21 个 command-backed workflow skills 说明执行逻辑。Claude Code 使用 /spec:*，Codex 使用 $spec-*；入口语法不同，workflow 边界一致。
这些图不是强制状态机，而是帮助用户理解每个命令会读取什么、判断什么、写出什么，以及什么时候应该降级、停止或交接给下一步。
总体入口治理
text
用户提出任务
|
v
using-spec-first 判断是否需要进入公开 workflow
|
+-- 环境 / MCP / runtime readiness
| v
| spec-mcp-setup
|
+-- graph readiness
| v
| spec-graph-bootstrap
|
+-- 项目规范 / glue baseline
| v
| spec-standards
|
+-- 需求、计划、执行、审查、沉淀或专项研究
|
v
对应的 spec-* workflow
|
v
输出可检查 artifact、验证结果或明确的 blocked / degraded 说明命令索引
| Skill | Claude Code | Codex | 主要用途 |
|---|---|---|---|
spec-mcp-setup | /spec:mcp-setup | $spec-mcp-setup | 安装并验证 harness runtime |
spec-graph-bootstrap | /spec:graph-bootstrap | $spec-graph-bootstrap | 编译 graph readiness facts |
spec-standards | /spec:standards | $spec-standards | 编译项目规范与 glue baseline |
spec-update | /spec:update | $spec-update | 检查版本并修复 runtime drift |
spec-ideate | /spec:ideate | $spec-ideate | 生成和评估方向候选 |
spec-brainstorm | /spec:brainstorm | $spec-brainstorm | 收敛需求、边界和验收标准 |
spec-plan | /spec:plan | $spec-plan | 形成实施计划或深化已有计划 |
spec-work | /spec:work | $spec-work | 执行计划或 task pack |
spec-work-beta | /spec:work-beta | $spec-work-beta | 带外部 delegate 的 beta 执行 |
spec-debug | /spec:debug | $spec-debug | 复现、定位并修复 bug |
spec-code-review | /spec:code-review | $spec-code-review | 代码 diff / PR 评审 |
spec-doc-review | /spec:doc-review | $spec-doc-review | 需求、计划、task pack 或文档评审 |
spec-compound | /spec:compound | $spec-compound | 沉淀已解决问题 |
spec-compound-refresh | /spec:compound-refresh | $spec-compound-refresh | 刷新过期 learning docs |
spec-app-consistency-audit | /spec:app-consistency-audit | $spec-app-consistency-audit | 移动 App 静态一致性审查 |
spec-sessions | /spec:sessions | $spec-sessions | 检索和总结历史会话 |
spec-skill-audit | /spec:skill-audit | $spec-skill-audit | 审计 skill 质量与治理边界 |
spec-slack-research | /spec:slack-research | $spec-slack-research | 研究 Slack 组织上下文 |
spec-release-notes | /spec:release-notes | $spec-release-notes | 查询近期 release 变化 |
spec-optimize | /spec:optimize | $spec-optimize | 围绕指标做迭代优化 |
spec-polish-beta | /spec:polish-beta | $spec-polish-beta | 浏览器可见 UI 打磨 beta |
spec-mcp-setup
入口：/spec:mcp-setup / $spec-mcp-setup
text
开始 setup
|
v
读取 host、developer profile、AGENTS.md / CLAUDE.md、项目拓扑
|
v
运行 project preflight 和本地 config bootstrap
|
v
检查 required MCP、graph providers、helper CLIs、Serena 项目状态
|
+-- 缺依赖或 host 配置不可写
| |
| v
| 记录 blocked / degraded、失败阶段和下一步修复动作
|
+-- baseline ready
|
v
写 .spec-first/config/runtime-capabilities.json
|
v
写 graph-providers.json / provider-artifacts.json
|
v
提示重启宿主，并进入 spec-graph-bootstrap关键输出：host readiness ledger、.spec-first/config/* setup facts。
spec-graph-bootstrap
入口：/spec:graph-bootstrap / $spec-graph-bootstrap
text
开始 graph bootstrap
|
v
读取 runtime-capabilities、host ledger、graph-providers、provider-artifacts
|
+-- baseline_ready=false 或 schema 不匹配
| |
| v
| fail closed，不运行 provider commands
|
+-- setup facts 可用
|
v
校验 provider id 和 argv command shape
|
v
执行 gitnexus / code-review-graph bootstrap、status、query_probe
|
v
写 raw logs、normalized status、canonical graph facts、impact envelope
|
v
下游 plan / work / review 可读取 readiness facts关键输出：.spec-first/providers/*、.spec-first/graph/*、.spec-first/impact/*。
spec-standards
入口：/spec:standards / $spec-standards
text
开始 standards baseline / quick / refresh / deep / import
|
v
读取 repo facts、graph facts、shared standards、已有 .spec-first/standards/*
|
v
脚本识别 project shape、domains、modules、glue capabilities
|
v
LLM 合成 standards-candidates.json
|
+-- confirmed
| |
| v
| 可作为下游硬约束
|
+-- imported / observed / suggested / conflict / unknown
|
v
只能作为软上下文或待确认事项
|
v
输出 standards-preview.md 给维护者确认关键输出：.spec-first/standards/project-shape.json、glue-map.json、standards-candidates.json、standards-preview.md。
spec-update
入口：/spec:update / $spec-update
text
开始 update 检查
|
v
读取当前 spec-first 版本、host runtime assets、managed blocks、manifest
|
v
对比 package 版本、source assets 和已生成 runtime copies
|
+-- 只需报告
| |
| v
| 输出 up-to-date / stale / drifted 状态
|
+-- 需要修复
|
v
运行受控 update / init / repair 命令
|
v
重新检查 runtime assets 和 managed blocks
|
v
输出版本、修复文件和仍需人工处理项关键输出：版本状态、runtime drift 修复结果、下一步 setup 或 graph bootstrap 建议。
spec-ideate
入口：/spec:ideate / $spec-ideate
text
开始 ideate
|
v
读取聚焦提示、repo facts、README、近期 diff、graph / standards 上下文
|
v
识别问题空间、机会、约束和用户价值
|
v
生成多个候选方向
|
v
按价值、证据强度、风险、复杂度去重排序
|
v
输出 ideation artifact
|
v
用户选择方向后进入 spec-brainstorm关键输出：docs/ideation/*.md 或当前项目约定的 ideation 文档。
spec-brainstorm
入口：/spec:brainstorm / $spec-brainstorm
text
开始 brainstorm
|
v
读取用户想法、ideate 输出、代码事实、业务约束、standards
|
v
澄清目标用户、问题、非目标、成功标准
|
+-- 关键需求不明确
| |
| v
| 提出少量澄清问题或记录待确认假设
|
+-- 范围可收敛
|
v
形成需求、边界、验收标准、风险和开放问题
|
v
输出 requirements / brainstorm artifact
|
v
进入 spec-plan关键输出：docs/brainstorms/* 或项目约定的 requirements brief。
spec-plan
入口：/spec:plan / $spec-plan
text
开始 plan
|
v
读取 requirements、repo facts、standards、graph readiness、相邻实现
|
v
明确目标、非目标、文件范围、接口影响和验证策略
|
v
拆分 Implementation Units
|
+-- 路径或行为仍不清楚
| |
| v
| 标记 Deferred to Implementation 或回到 brainstorm
|
+-- 可执行
|
v
写计划、风险、测试矩阵、handoff notes
|
v
需要大规模执行时交给 standalone write-tasks
|
v
进入 spec-work关键输出：docs/plans/* 计划文档；必要时再生成可 hash / validate 的 task pack。
spec-work
入口：/spec:work / $spec-work
text
开始 work
|
v
读取 plan 或 task pack，校验 target_repo、hash、stop_if、文件范围
|
v
检查分支、工作区状态、测试入口、相邻代码模式
|
v
建立执行任务列表
|
v
逐个实施最小必要改动
|
v
同步测试、文档、CHANGELOG 和生成资产
|
+-- 验证失败
| |
| v
| 调试并修复，或明确 blocked
|
+-- 验证通过
|
v
输出 diff 摘要、验证结果、剩余风险
|
v
进入 code-review / doc-review关键输出：可审查 diff、验证结果、交付说明。
spec-work-beta
入口：/spec:work-beta / $spec-work-beta
text
开始 work beta
|
v
继承 spec-work 的 plan / task pack 校验
|
v
识别可分派、写集不重叠、不会阻塞主路径的任务
|
+-- 不适合 delegate
| |
| v
| 回退到 inline spec-work 执行
|
+-- 适合 delegate
|
v
分派 bounded worker，声明文件所有权和验证重点
|
v
主线程继续处理非重叠任务
|
v
集成 worker diff，运行项目级验证
|
v
输出合并结果和风险关键输出：与 spec-work 相同，额外包含 delegate 任务边界和集成说明。
spec-debug
入口：/spec:debug / $spec-debug
text
开始 debug
|
v
收集错误、复现步骤、测试失败、日志、相关 diff
|
v
建立最小复现或可重复验证命令
|
v
定位失败路径和根因假设
|
+-- 根因证据不足
| |
| v
| 继续缩小输入、加观测、读取相邻实现
|
+-- 根因成立
|
v
做最小修复
|
v
跑复现验证和相邻回归验证
|
v
输出根因、修复、测试结果和残余风险关键输出：根因说明、最小修复 diff、复现和回归验证结果。
spec-code-review
入口：/spec:code-review / $spec-code-review
text
开始 code review
|
v
读取 diff、base ref、相关 plan / task pack、测试结果、standards
|
v
按风险面分派或模拟多视角审查
|
v
收集 correctness、regression、security、test gap、maintainability findings
|
v
按证据强度去重和排序
|
+-- 有阻断问题
| |
| v
| 先列 findings、文件行号、影响和修复方向
|
+-- 无明显问题
|
v
明确 no findings，并说明剩余测试缺口关键输出：按严重度排序的 review findings、开放问题和测试缺口。
spec-doc-review
入口：/spec:doc-review / $spec-doc-review
text
开始 doc review
|
v
读取 requirements / plan / task pack / markdown 文档
|
v
识别文档类型、目标读者、决策状态和执行契约
|
v
从产品、工程、测试、交接、治理视角审查
|
v
合并重复问题，过滤低置信噪音
|
+-- 文档无法安全交接
| |
| v
| 输出阻断问题和需要补齐的上下文
|
+-- 文档可用
|
v
输出改进建议、剩余假设和可执行性结论关键输出：文档质量 findings、可执行性判断、待澄清问题。
spec-compound
入口：/spec:compound / $spec-compound
text
开始 compound
|
v
确认问题已经解决且有可复用价值
|
v
读取 diff、验证命令、失败尝试、最终根因、项目模式
|
v
提炼触发信号、诊断步骤、稳定解法和反例
|
v
检查 docs/solutions/ 是否已有重叠 learning
|
+-- 有过期或冲突 learning
| |
| v
| 标记后续 compound-refresh 范围
|
+-- 可新增
|
v
写入 docs/solutions/* learning
|
v
后续 workflow 可作为软上下文读取关键输出：docs/solutions/* 经验文档和可能的 refresh 提示。
spec-compound-refresh
入口：/spec:compound-refresh / $spec-compound-refresh
text
开始 compound refresh
|
v
读取指定 docs/solutions 范围、当前代码、相关测试和新 learning
|
v
判断每篇文档是 fresh、stale、overlap、superseded 还是 wrong
|
+-- 仍然准确
| |
| v
| 保留并可补充当前证据
|
+-- 过期 / 重叠 / 被替代
|
v
更新、合并、替换或删除
|
v
输出 refresh 摘要和仍需人工确认的知识边界关键输出：更新后的 docs/solutions/*、合并/删除说明、知识漂移摘要。
spec-app-consistency-audit
入口：/spec:app-consistency-audit / $spec-app-consistency-audit
text
开始 App consistency audit
|
v
读取 PRD、Figma evidence、source routes、KMP / Clean Architecture、analytics、i18n
|
v
按页面、流程、组件、状态、埋点、文案、行业规则建立检查矩阵
|
v
静态审查 PRD -> design -> implementation 的一致性
|
+-- evidence 缺失
| |
| v
| 标注 degraded，不把猜测当结论
|
+-- 发现不一致
|
v
输出文件位置、违反的来源事实、影响和修复建议
|
v
运行时验证前先处理关键差异关键输出：App 一致性审查报告、按严重度排序的静态 findings。
spec-sessions
入口：/spec:sessions / $spec-sessions
text
开始 sessions research
|
v
解析用户问题和时间 / 分支 / cwd / 主题范围
|
v
盘点 Claude Code 与 Codex session 文件
|
v
筛选候选 session 并抽取骨架、错误信号、决策节点
|
v
综合回答用户问题
|
+-- 证据不足
| |
| v
| 明确哪些 session 不可读、缺失或范围外
|
+-- 证据充分
|
v
输出时间线、尝试过的方案、结论和可复用上下文关键输出：历史会话研究摘要；不直接暴露 internal session-extract 原始流程。
spec-skill-audit
入口：/spec:skill-audit / $spec-skill-audit
text
开始 skill audit
|
v
读取目标 SKILL.md、关联 scripts / references、governance contracts、runtime copies
|
v
检查 trigger 精度、边界、输入输出契约、渐进披露、安全和可维护性
|
v
对 spec-first 仓库额外检查 source/runtime governance 和 drift
|
+-- 发现治理风险
| |
| v
| 输出高置信 findings、影响范围和修复建议
|
+-- 未发现阻断问题
|
v
输出 no findings、残余风险和建议测试关键输出：skill 审计 findings、治理边界问题、runtime drift 风险。
spec-slack-research
入口：/spec:slack-research / $spec-slack-research
text
开始 Slack research
|
v
解析主题、组织上下文问题、时间范围和相关项目
|
v
搜索 Slack 讨论并筛选高价值 thread
|
v
抽取决策、约束、争议、负责人、时间线和未决事项
|
+-- 结果噪音高或权限不足
| |
| v
| 标注 evidence limitation
|
+-- 结果可用
|
v
输出研究摘要，不返回原始消息列表
|
v
作为 brainstorm / plan / review 的组织上下文关键输出：Slack 组织上下文 digest、决策线索、证据限制。
spec-release-notes
入口：/spec:release-notes / $spec-release-notes
text
开始 release notes 查询
|
v
读取用户问题、当前版本、CHANGELOG / release artifacts
|
v
定位相关版本、skill 名称或时间范围
|
+-- 问的是最新变化
| |
| v
| 汇总最近 release 的用户可见变化
|
+-- 问的是某个 skill / 版本
|
v
引用对应版本事实并解释变化影响
|
v
输出带版本标注的简洁答案关键输出：带版本依据的 release 摘要或指定问题答案。
spec-optimize
入口：/spec:optimize / $spec-optimize
text
开始 optimize
|
v
确认可度量目标、hard gates、judge 标准和测试预算
|
v
建立 measurement scaffold
|
v
并行或串行运行多个实验候选
|
v
对每个候选运行指标、质量门和回归检查
|
+-- 没有改进
| |
| v
| 记录失败实验和下一轮假设
|
+-- 找到改进
|
v
保留最优改动，回滚低质量实验
|
v
输出指标变化、最终方案和复现命令关键输出：度量结果、实验记录、保留方案、验证命令。
spec-polish-beta
入口：/spec:polish-beta / $spec-polish-beta
text
开始 polish beta
|
v
启动或连接 dev server
|
v
用浏览器打开目标页面并采集桌面 / 移动视图证据
|
v
检查布局、文案溢出、交互状态、视觉层级、可访问性和截图差异
|
+-- 页面不可运行
| |
| v
| 输出启动失败、路由失败或资源失败原因
|
+-- 页面可运行
|
v
做小步 UI / UX polish
|
v
重新截图和验证
|
v
输出视觉改动、验证视口和剩余人工确认项关键输出：浏览器复查结果、UI polish diff、截图或视觉验证说明。
读图原则
blocked表示当前 workflow 不应继续写入下游事实，需要先修复输入或环境。degraded表示可以继续，但必须说明证据限制，并用 bounded direct reads 或人工确认补足。confirmed才能作为硬约束；observed、suggested、imported和unknown只能作为软上下文。write-tasks是 standalone handoff skill，不是/spec:*或$spec-*command-backed workflow。