工作流总览
Spec-First 面向研发团队，不把 AI coding 当成一次性聊天，而是把代码库事实、provider readiness / candidate evidence、需求、计划、任务、实现、评审和知识沉淀串成一条可审计链路。
本页不是命令手册，而是全局地图。读完后，你应该能判断当前任务缺哪一层输入，以及应该从哪个 workflow 进入，而不是每次从第一步开始。
核心主轴是：
text
Codebase -> Spec -> Plan -> Tasks -> Code -> Review -> KnowledgeProvider evidence、Graphify、CodeGraph、Slack、sessions、release notes 和 project guidance 都是支路证据，不是主链路的必经阶段。这不是强制每次都跑满的线性流程。小修可以从 Code 直接进入 Review；复杂 feature 通常从 Spec 和 Plan 开始；历史上下文和外部研究会在需要时作为证据支路进入主链路。
Governed Loop
主链路不是硬状态机，而是一组可以从当前缺口切入的研发层。
01Codebaserepo files, tests, project guidance
02Graphfacts, impact, provider status
03Specactors, flows, requirements
04Planapproach, files, risks
05Taskswaves, ownership, stop_if
06Codediff, tests, evidence
07Reviewfindings, gates, risks
08Knowledgesolutions feed next cycle
Knowledge 回流到下一次 Codebase / Spec / Review；provider evidence 或外部研究不可用时显式降级，不伪装成完整证据。
研发闭环总图
text
+----------------------------------------------------------------------------+
| Codebase |
| repo files / tests / package scripts / AGENTS.md / CLAUDE.md / guidance |
+----------------------------------------------------------------------------+
|
| runtime-setup / provider evidence / project guidance
v
+----------------------------------------------------------------------------+
| Provider Evidence |
| provider readiness / bounded direct reads / explicit limitations |
+----------------------------------------------------------------------------+
|
| ideate / brainstorm / doc-review
v
+----------------------------------------------------------------------------+
| Spec |
| problem frame / actors / flows / requirements / acceptance examples |
+----------------------------------------------------------------------------+
|
| plan / doc-review
v
+----------------------------------------------------------------------------+
| Plan |
| approach / boundaries / files / risks / test scenarios / sequencing |
+----------------------------------------------------------------------------+
|
| write-tasks when plan is large enough
v
+----------------------------------------------------------------------------+
| Tasks |
| task pack / dependencies / waves / file ownership / stop_if / test_focus |
+----------------------------------------------------------------------------+
|
| work / debug / optimize / polish
v
+----------------------------------------------------------------------------+
| Code |
| implementation diff / tests / build output / browser or CLI evidence |
+----------------------------------------------------------------------------+
|
| code-review / app-consistency-audit
v
+----------------------------------------------------------------------------+
| Review |
| persona findings / safe fixes / residual risks / release readiness |
+----------------------------------------------------------------------------+
|
| compound / compound-refresh / sessions
v
+----------------------------------------------------------------------------+
| Knowledge |
| docs/solutions / refreshed learnings / release notes / future context |
+----------------------------------------------------------------------------+每一层解决什么问题
| 研发层 | 主要问题 | 典型入口 | 主要产物 |
|---|---|---|---|
| Codebase | 当前 repo 到底是什么、有哪些约束、哪些文件和命令可信 | spec-runtime-setup | runtime capabilities、项目说明、setup facts |
| Provider Evidence | provider readiness 是否完成，是否需要降级到 direct reads | spec-runtime-setup、CodeGraph / Graphify provider pack | setup facts、readiness 状态、candidate evidence |
| Spec | 要解决什么、谁受影响、什么算成功 | spec-ideate、spec-brainstorm、spec-prd、spec-doc-review | docs/brainstorms/*-requirements.md、open questions |
| Plan | 怎么做、边界在哪里、哪些文件和测试会受影响 | spec-plan、spec-doc-review | docs/plans/*-plan.md |
| Tasks | 大计划是否需要可交接任务包、能否并行、何时停止 | spec-write-tasks | docs/tasks/*-tasks.md |
| Code | 按计划实现、调试失败、优化指标或打磨 UI | spec-work、spec-debug、spec-optimize、spec-polish、spec-dogfood | diff、测试结果、截图或运行证据 |
| Review | 在合并前发现逻辑、测试、安全、性能、契约和文档问题 | spec-code-review、spec-doc-review、spec-app-consistency-audit | review findings、safe_auto fixes、residual risks |
| Knowledge | 把已解决的问题变成下次可复用的团队知识 | spec-compound、spec-compound-refresh | docs/solutions/*、刷新后的 learning docs |
六层 Harness 视角
最新工程资料把这条链路进一步拆成六层 harness，适合用来判断一项新能力是否应该进入 spec-first 主路径：
| Harness 层 | 判断问题 | 典型官网入口 |
|---|---|---|
| Context | 是否给 AI 正确上下文，而不是无限上下文 | Provider Evidence、Project Guidance |
| Execution | 是否让执行过程可跟踪、可交接 | Plan 指南、Work 指南 |
| Evidence | 结论能否回到源码、diff、测试或日志 | Code Review 指南、Debug 指南 |
| Evaluation | 有没有记录本次改动是否真的变好 | Verification 与发布质量见深入解析 |
| Governance | source/runtime、权限、dispatch 和 provider 边界是否清晰 | 运行模型、深入解析地图 |
| Knowledge | 经验是否进入下一次循环 | Compound 指南、记忆与知识沉淀 |
入口治理
using-spec-first 是入口治理 meta skill。它不是公开 workflow，也不是 spec-* 命令。它的职责是在 substantial work 前判断当前任务应该进入哪个公开入口。
text
用户请求
|
v
using-spec-first 判断意图、风险和当前上下文
|
+-- 环境 / runtime / MCP 未就绪 -------> spec-runtime-setup
|
+-- runtime / provider evidence 问题 ---> spec-runtime-setup
|
+-- 需求还不清楚 ----------------------> spec-brainstorm
|
+-- 存量系统增量需要 PRD-grade WHAT ---> spec-prd
|
+-- 方向选择或想法生成 ----------------> spec-ideate
|
+-- HOW 不清楚 ------------------------> spec-plan
|
+-- 计划很大，需要任务交接 ------------> spec-write-tasks
|
+-- 可执行工作 ------------------------> spec-work / spec-debug
|
+-- 需要质量评审 ----------------------> spec-code-review / spec-doc-review
|
+-- 已解决问题需要沉淀 ----------------> spec-compound入口治理的关键不是“每次从第一步开始”，而是把任务送到当前最缺的研发层：缺事实先补事实，缺需求先补需求，缺计划先计划，已有计划就执行，已有 diff 就评审。
主链路中的 skill 节点
| 阶段 | Skill 节点 | 调用决策 | Agent 专家能力如何进入 |
|---|---|---|---|
| Codebase | spec-runtime-setup | 第一次接入项目、MCP/helper 或 provider readiness 缺失、host runtime 不可信 | 主要使用 deterministic scripts 和本地检查，不默认调 persona agents |
| Provider Evidence | CodeGraph / Graphify provider pack | 完整 setup 默认验证；需要额外候选证据时由下游读取，异常时显式降级 | 调用 provider CLI/MCP，不把 agents 当事实来源；provider degraded 会显式进入下游上下文 |
| Spec | spec-ideate | 用户要想法、方向、改进点或外部启发 | 可借助 web / issue / repo / best-practices research agents 做外部和代码库 grounding |
| Spec | spec-brainstorm | WHAT 不清楚、需求边界未定、存在多个合理产品方向 | 可用 spec-spec-flow-analyzer、product、design、research 类 agent 辅助识别用户流和风险 |
| Spec | spec-prd | 已有系统增量、粗糙 PRD 或产品笔记需要写成 plan 可消费的 PRD-grade requirements | 先读当前系统证据、领域术语和已有 context / glossary / ADR；必要时用 repo/product/research 视角校准 current-state claims |
| Spec / Plan | spec-doc-review | requirements、plan 或 task pack 需要语义审查 | 固定启用 coherence、feasibility；按文档信号增加 product、design、security、scope、adversarial personas |
| Plan | spec-plan | WHAT 已基本清楚，需要 HOW、文件边界、测试场景和顺序 | 先读 codebase、项目说明和 provider evidence（若可用）；需要深挖时使用 repo、history、framework docs、best practices 等研究 agents |
| Tasks | spec-write-tasks | 计划足够大，直接执行会增加上下文负担或并行风险 | 不改变计划范围；用文件边界、依赖和验证面决定 task cards / waves |
| Code | spec-work | 已有计划、任务包或清晰实现目标 | 根据任务规模选择 inline、serial 或 parallel 执行；Codex 可用 worker / explorer 子任务，但最终集成由 orchestrator 负责 |
| Code | spec-debug | 存在失败、bug、测试错误或异常行为 | 可用 repo、history、testing、correctness、specialist agents 辅助定位，但必须以复现和验证收口 |
| Code | spec-optimize | 目标可度量，需要多方案实验比较 | 可以并行实验候选；是否保留改动由 hard gates、judge 标准和回归结果决定 |
| Code | spec-polish | 浏览器可见 UI 需要启动页面、截图和迭代打磨 | 可结合 figma-design-sync、visual review 能力，必须用浏览器证据验证 |
| Code / Review | spec-dogfood | 分支/PR 在 review 或 shipping 前需要自主浏览器 dogfood | 按 diff 映射受影响用户流，驱动 agent-browser 走查、修小故障、记录人工决策阻塞并写报告 |
| Review | spec-code-review | 已有 diff、PR 或合并前质量检查 | 总是启用 correctness、testing、maintainability、project guidance、agent-native、learnings；按 diff 文件选择 security、performance、API、migration、reliability、stack reviewers |
| Review | spec-app-consistency-audit | 移动 App 需要 PRD、Figma、本地 source、路由、架构、analytics、i18n 一致性审查 | 使用专项审查规则包，不替代真机、模拟器或 QA |
| Knowledge | spec-compound | 最近刚解决一个问题，需要沉淀复用知识 | Full 模式会调 Context Analyzer、Solution Extractor、Related Docs Finder、可选 session historian |
| Knowledge | spec-compound-refresh | docs/solutions/ 过期、重复、冲突或需要合并 | 读取当前 codebase 验证 learning 是否漂移，更新、合并、替换或删除 stale docs |
Agent 调度原则
Spec-First 的 agents 不是菜单式全量启动，而是由 workflow 根据证据选择：
spec-code-review按 diff 文件、变更规模和风险域选择 reviewer persona。spec-doc-review按文档类型、需求数量、架构决策、安全边界和设计信号选择 reviewer persona。spec-work按任务规模、依赖关系、文件重叠和宿主隔离能力决定 inline、serial subagents 或 parallel subagents。spec-compound只在 Full 模式中并行调研究型子任务，并且只有 orchestrator 写最终文档。spec-ideate、spec-plan和spec-debug倾向把 research agents 当作 evidence providers，而不是让它们替代最终判断。
降级与停止规则
Graph、project guidance、sessions、Slack 和外部研究都可能 unavailable、stale、blocked 或 degraded。Spec-First 的规则是显式降级，而不是假装证据完整：
text
fact available and trusted
|
v
作为硬约束或强证据使用
fact missing / stale / degraded
|
v
标注 limitation
|
v
改用 bounded direct reads、人工确认或返回上游 workflow当缺失信息会改变产品范围、技术契约、文件边界或验证标准时，workflow 应停止并回到 spec-brainstorm、spec-plan 或用户确认；当信息只影响实现细节，可以作为 implementation-time unknown 进入 spec-work 的 stop_if 或验证清单。
阅读下一步
- Workflow 命令总览：17 个公开 workflow 的执行流程图
- Skills 参考：所有 skill 详情页索引与节点决策表
- 完整示例：把这条链路用一个真实需求跑一遍
- 运行模型：CLI、runtime 资产、control-plane facts 的边界