完整示例

下面用一个具体需求走完一次端到端 workflow 链路。示例统一使用当前 spec-* 入口；Claude Code /spec:* 与 Codex $spec-* 属于兼容别名。

场景：为 CLI 增加首次使用引导

这是一个典型的中小型功能：用户群明确（首次使用者）、需求边界相对清晰、改动跨多个产物（文档 + CLI 输出 + 测试）。用它走完一次 spec-first 链路恰好能覆盖所有阶段。

步骤 0：准备运行环境与 provider evidence

第一次使用、换宿主、升级后或 MCP/helper 环境变化时，先在终端里完成 CLI 与宿主初始化：

spec-first doctor
spec-first init

重启当前宿主后，在宿主会话里准备 required harness runtime：

spec-runtime-setup

runtime-setup 会安装并验证 required MCP servers、agent-browser 等 helpers、CodeGraph / Graphify baseline，并写入 .spec-first/config/。Provider 输出仍只是候选证据；默认 source truth 仍是 bounded direct source reads、rg、ast-grep、git diff、测试日志和用户证据。

如果项目是 brownfield 或团队协作场景，先确认 AGENTS.md、CLAUDE.md、docs/contracts/**、README、测试和已有 solution docs 是否足够说明项目规范；不足时先补文档或在 brainstorm/plan 中明确假设。

步骤 1：Ideate（可选）

如果你只有一句模糊想法，先用 ideate 发散候选：

spec-ideate "改善 CLI 首次使用体验"

ideate 会基于 repo facts、graph、项目说明和外部线索给出候选方向，并按价值/风险/复杂度排序。产物写入：

docs/ideation/2026-05-07-cli-onboarding-ideation.md

如果你已经知道要做什么，可以跳过这一步，直接进入 brainstorm。

步骤 2：Brainstorm 形成需求 brief

spec-brainstorm "改善 CLI 首次使用引导：spec-first init 后给出明确下一步"

brainstorm 通过对话收敛：

• 谁是用户：第一次安装 spec-first 的开发者
• 关键问题：init 后用户不知道接下来该跑 spec-runtime-setup，还是直接进入 brainstorm
• 关键流程：init → 重启宿主 → 第一次进入会话 → 看到下一步指引
• 范围边界：本轮只改 init 输出与文档；不改宿主入口治理逻辑
• 验收样例：init 末尾输出包含具体下一步命令、对应宿主语法

产物：

docs/brainstorms/2026-05-07-001-cli-onboarding-requirements.md

可选：用 spec-doc-review 对 requirements 做语义审查，确保 actors、key flows、scope 清楚。

步骤 3：Plan 落到实施单元

spec-plan

plan 把需求转成可执行单元：

• U1：在 src/cli/commands/init.js 的成功输出里加下一步指引段
• U2：根据宿主 runtime 状态显示下一步入口与 preview 边界
• U3：更新 README.md 与官网 installation.md 同步引导文字
• U4：补充 init 输出测试

产物：

docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md

如果计划较大或需要并行执行，可以再用 standalone spec-write-tasks skill 把 plan 编译成 task pack：

docs/tasks/2026-05-07-001-feat-cli-onboarding-tasks.md

spec-write-tasks 不是 spec-* workflow command；它是 standalone handoff skill，保持 plan 为单一真源。

步骤 4：Work 执行最小可验证改动

spec-work docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md

work 阶段读取计划、相关源码与测试，按单元顺序执行：

• 修改 src/cli/commands/init.js 添加下一步指引输出
• 修改 README / installation 同步文档
• 添加单元测试
• 运行测试 → 验证通过
• 同步在 CHANGELOG.md 加一条记录（项目铁律）

如果中途遇到 bug，可以切到 debug：

spec-debug "init 在 windows powershell 下输出乱码"

debug 会先复现、定位根因，再决定是否进入修复。

步骤 5：Review

合并前对 diff 做代码评审：

spec-code-review

code-review 会调度 6 类 always-on personas（correctness / testing / maintainability / project-standards / agent-native / learnings-researcher），并按 diff 触发条件 reviewer（security / performance / API contract / migration / reliability / CLI / stack-specific）。

产物：

• findings.json（结构化问题）
• safe_auto fixes（安全的自动修复）
• residual risks（遗留风险与建议）

如果评审对象是需求/计划/任务包：

spec-doc-review docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md

doc-review 调度 always-on coherence + feasibility，并按文档信号启用 product / design / security / scope / adversarial reviewers。

步骤 6：Compound 沉淀经验

当问题被稳定解决、值得复用时：

spec-compound

compound 会并行 Context Analyzer / Solution Extractor / Related Docs Finder（必要时加 Session Historian），写入：

docs/solutions/<category>/cli-onboarding-2026-05-07.md

下一次 AI Coding 时 spec-learnings-researcher 会自动检索并把相关历史经验带入 reviewer 视野。

产物总览

走完整条链路后，仓库里会留下：

docs/ideation/2026-05-07-cli-onboarding-ideation.md
docs/brainstorms/2026-05-07-001-cli-onboarding-requirements.md
docs/plans/2026-05-07-001-feat-cli-onboarding-plan.md
docs/tasks/2026-05-07-001-feat-cli-onboarding-tasks.md          # 可选
docs/solutions/cli/onboarding-2026-05-07.md                     # compound 后
git commits（带 spec_id）
.spec-first/config/*                                            # 本机 control-plane
.spec-first/config/*                                            # 本机 runtime setup facts

下次类似需求出现时，AI 不再从零开始：它会读到上一次的 requirements、plan、solution，并自动把过往经验作为评审与设计输入。

关键边界回顾

类型	位置	是否提交
长期协作文档	docs/brainstorms/ docs/plans/ docs/tasks/ docs/solutions/ docs/ideation/	通常提交
Generated runtime	.claude/ .codex/ .agents/skills/ .cursor/ .kiro/ .qoder/	不提交（init 自动加 .gitignore）
Control-plane facts	.spec-first/config/ .spec-first/workspace/ .spec-first/sessions/	不提交，本机重建
Provider evidence	.codegraph/、graphify-out/（当前）、.graphify/（legacy）、.spec-first/providers/	不提交，由完整 setup 或显式子集修复本机重建

更详细的产物分类与 Git 策略见 产物目录与 Git 边界。

阅读下一步

• Workflow 命令总览：17 个公开 workflow 的执行流程图
• Skills 参考：每个 skill 的契约式信息
• Compound 指南：本示例最后一步的深入说明
• 产物目录与 Git 边界：哪些产物提交、哪些不提交