工作流总览
Spec-First 面向研发团队，不把 AI coding 当成一次性聊天，而是把代码库事实、图谱上下文、需求、计划、任务、实现、评审和知识沉淀串成一条可审计链路。
核心主轴是：
text
Codebase -> Graph -> Spec -> Plan -> Tasks -> Code -> Review -> Knowledge这不是强制每次都跑满的线性流程。小修可以从 Code 直接进入 Review；复杂 feature 通常从 Spec 和 Plan 开始；历史上下文、Slack、standards、sessions、release notes 会在需要时作为证据支路进入主链路。
研发闭环总图
text
+----------------------------------------------------------------------------+
| Codebase |
| repo files / tests / package scripts / AGENTS.md / CLAUDE.md / standards |
+----------------------------------------------------------------------------+
|
| mcp-setup / graph-bootstrap / standards
v
+----------------------------------------------------------------------------+
| Graph |
| graph facts / impact facts / provider status / bounded direct reads |
+----------------------------------------------------------------------------+
|
| 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-mcp-setup、spec-standards、spec-sessions | runtime capabilities、project standards、历史会话摘要 |
| Graph | AI 在改动前是否知道依赖、影响面和 degraded 状态 | spec-graph-bootstrap、GitNexus / code-review-graph provider | graph facts、impact facts、provider status |
| Spec | 要解决什么、谁受影响、什么算成功 | spec-ideate、spec-brainstorm、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-work-beta、spec-debug、spec-optimize、spec-polish-beta | diff、测试结果、截图或运行证据 |
| Review | 在合并前发现逻辑、测试、安全、性能、契约和文档问题 | spec-code-review、spec-doc-review、spec-app-consistency-audit、spec-skill-audit | review findings、safe_auto fixes、residual risks |
| Knowledge | 把已解决的问题变成下次可复用的团队知识 | spec-compound、spec-compound-refresh、spec-release-notes | docs/solutions/*、刷新后的 learning docs、版本摘要 |
入口治理
using-spec-first 是入口治理 meta skill。它不是公开 workflow，也不是 /spec:* 或 $spec-* 命令。它的职责是在 substantial work 前判断当前任务应该进入哪个公开入口。
text
用户请求
|
v
using-spec-first 判断意图、风险和当前上下文
|
+-- 环境 / runtime / MCP 未就绪 -------> spec-mcp-setup
|
+-- graph readiness 或 impact facts ---> spec-graph-bootstrap
|
+-- 项目规范或 glue baseline ----------> spec-standards
|
+-- 需求还不清楚 ----------------------> spec-brainstorm
|
+-- 方向选择或想法生成 ----------------> 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-mcp-setup | 第一次接入项目、MCP 或 graph provider 缺失、host runtime 不可信 | 主要使用 deterministic scripts 和本地检查，不默认调 persona agents |
| Codebase | spec-standards | brownfield 项目需要项目规范、glue capability baseline 或团队规范导入 | 可读取 repo facts 和 graph facts，输出候选规范；专家评审通常在 spec-doc-review 或 spec-code-review 中发生 |
| Graph | spec-graph-bootstrap | setup facts 可用后，需要把 provider 状态编译成下游可消费事实 | 调用 graph 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 / Plan | spec-doc-review | requirements、plan 或 task pack 需要语义审查 | 固定启用 coherence、feasibility；按文档信号增加 product、design、security、scope、adversarial personas |
| Plan | spec-plan | WHAT 已基本清楚，需要 HOW、文件边界、测试场景和顺序 | 先读 codebase / standards / graph；需要深挖时使用 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-work-beta | 用户明确要 Codex delegation beta 或外部 delegate 支持 | 在 spec-work 基础上引入更强的外部 delegate 协作，仍受文件边界和验证门约束 |
| Code | spec-debug | 存在失败、bug、测试错误或异常行为 | 可用 repo、history、testing、correctness、specialist agents 辅助定位，但必须以复现和验证收口 |
| Code | spec-optimize | 目标可度量，需要多方案实验比较 | 可以并行实验候选；是否保留改动由 hard gates、judge 标准和回归结果决定 |
| Code | spec-polish-beta | 浏览器可见 UI 需要启动页面、截图和迭代打磨 | 可结合 design iterator、Figma sync、visual review 能力，必须用浏览器证据验证 |
| Review | spec-code-review | 已有 diff、PR 或合并前质量检查 | 总是启用 correctness、testing、maintainability、project standards、agent-native、learnings；按 diff 文件选择 security、performance、API、migration、reliability、stack reviewers |
| Review | spec-app-consistency-audit | 移动 App 需要 PRD、Figma、本地 source、路由、架构、analytics、i18n 一致性审查 | 使用专项审查规则包，不替代真机、模拟器或 QA |
| Review | spec-skill-audit | 审查 spec-first skills、runtime drift、dual-host governance 或 skill 质量 | 使用 skill / agent-native / prompt-workflow 视角，输出 audit 报告而非直接改 source |
| Knowledge | spec-compound | 最近刚解决一个问题，需要沉淀复用知识 | Full 模式会调 Context Analyzer、Solution Extractor、Related Docs Finder、可选 session historian |
| Knowledge | spec-compound-refresh | docs/solutions/ 过期、重复、冲突或需要合并 | 读取当前 codebase 验证 learning 是否漂移，更新、合并、替换或删除 stale docs |
| Knowledge | spec-sessions | 需要检索过去 Claude Code / Codex 会话 | 调 session inventory / extract internal skills，返回研究摘要，不暴露 internal-only 入口 |
| Knowledge | spec-slack-research | 用户明确要 Slack 组织上下文 | 调 Slack researcher，输出解释型 digest 而不是原始消息列表 |
| Knowledge | spec-release-notes | 需要了解 spec-first 近期变化或某个 skill 的版本变化 | 读取 release/changelog 事实，输出带版本依据的摘要 |
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、standards、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 命令总览：21 个公开命令的执行流程图
- Skills 参考：所有 skill 详情页索引与节点决策表
- 完整示例：把这条链路用一个真实需求跑一遍
- 运行模型：CLI、runtime 资产、control-plane facts 的边界