Ask Matt

你不需要记住每个 skill，所以直接问。

Flow 是穿过 skills 的一条路径。大多数路径沿着一条 main flow 前进，两个 on-ramps 会并入它。其他内容要么是 standalone，要么是在下层运行的 vocabulary layer。

The main flow: idea -> ship

这是大多数工作的路线：你有一个想法，并希望把它构建出来。

1. /grill-with-docs - 通过访谈打磨想法。在 working directory 中工作时从这里开始：它是 stateful 的，会把学到的内容保存在 CONTEXT.md 和 ADRs 中。（没有 working directory？直接调用 /grilling，见 Standalone。grill-with-docs 是会留下文档痕迹的版本，只要有 repo 可记录，它就是更好的那个。）

2. 分支 - 这是 multi-session build 吗？

   • 是 -> /to-spec，把 thread 固化为 openspec/changes/<change-name>/proposal.md 与 delta specs；再运行 /to-plan <change-name>，补齐 design 和 tracer-bullet tasks；用 /implement <change-name> 按 tasks 实现、中断可续做，以统一提交和 /code-review 收尾。
   • 否 -> 在当前 context window 里直接运行 /implement。

   无论哪种方式，/implement 都会在内部驱动 /tdd 构建每个 task slice：一次一个 red-green slice，边做边勾选；全部任务完成后统一提交一次，再由 /code-review 对提交的 diff 做 Standards + Spec 双轴 review。只想在没有完整 spec 的情况下 test-first 构建一个具体 behavior 时，单独用 /tdd；想按固定点 review branch 或 PR 时，单独用 /code-review。

Context hygiene

步骤 1 到 /to-spec 完成 proposal 与 delta specs 要留在 同一个未中断的 context window 中；不要 compact 或 clear，这样行为契约才能建立在同一组思考之上。两者落盘后，后续 OpenSpec artifacts 可以从文件恢复 context。

限制来自 smart zone：在该窗口（最新模型大约 150k tokens）内，模型还能保持敏锐推理。如果 session 在 /to-plan 前接近这个区间，不要硬撑降级状态；在最近的 phase boundary 用 /compact，然后继续（见 Phase boundaries）。

On-ramps

起点会生成工作，然后并入 main flow。

• Something's broken -> /diagnosing-bugs。用于难处理的问题：第一眼看不出的 bug、间歇性 flake、夹在两个 known-good states 之间的 regression。它在拥有 tight feedback loop 前拒绝空想，也就是一个已经能在 这个 bug 上变红的命令；然后用 regression test 修复。如果复盘发现真正问题是没有好 seam 能锁住 bug，它会把后续交给 /improve-codebase-architecture。

• 巨大而模糊的 effort——greenfield project 或巨大 feature build，一个 session 装不下 -> /wayfinder，这是这里认知负担最重的 flow。当从当前位置到 destination 的路还看不见时，它在 docs/wayfinding/ 下绘制 decision records 的 shared map，逐个解决，产出 decisions, not deliverables，直到 fog 被推开、路径清晰。/grill-with-docs 用于一个 session 能装下的想法，wayfinder 用于装不下的想法；它更慢、更密集，所以只应留给确实如此的 effort，绝不要用于范围明确的 feature。

  Map 清晰后，它会 hand off，而不是 build：先进入 /to-spec，把 map 中相互链接的 decisions 收束成 OpenSpec proposal 与 delta specs，再由 /to-plan 完成 planning。让 map 直接循环进入 /implement 会跳过这次收束并丢掉相互链接的细节；只有当 effort 后来发现确实很小时，才直接进入 /implement。

Codebase health

这不是 feature work，而是维护。

• /improve-codebase-architecture - 有空时运行，保持 codebase 适合 agents 操作。它会暴露 deepening opportunities；选择其中一个会生成一个 idea，可以带入 main flow 的 /grill-with-docs。它负责找候选项；/codebase-design（见下文）是你设计已选候选项时使用的工作台。

Vocabulary underneath

两个 model-invoked references 在其他 skills 下层运行，分别是自己词汇的 single source of truth。问题在于词语而不是流程时直接用它们；也可以让上面的 skills 自动拉起它们。

• /domain-modeling - 打磨项目的 domain language：挑战模糊术语、解决 overloaded word（例如一个 "account" 承担三件事）、把难以逆转的决策记录为 ADR。它是 /grill-with-docs 用来保持 CONTEXT.md glossary 干净的主动纪律。
• /codebase-design - deep-module vocabulary（module、interface、depth、seam、adapter、leverage、locality），用于设计 module 的 shape：把大量 behavior 放在 clean seam 上的小 interface 后面。/tdd 和 /improve-codebase-architecture 都使用这套语言。

Phase boundaries

phase 是 session 内的一段工作——grilling、implementation、QA。在它们之间的 boundary 处你有五个选项，而在这整张 map 中，选哪个是最模糊的决定：

• Continue - 原地不动。不花成本，也不丢失任何东西。
• /clear - 清空 context window，当这里的内容对接下来什么都不重要时。
• /handoff - 写一个便携 markdown 文件。范围很窄：只用于 new harness、new directory、colleague，或在 阶段中途 分叉一个 side task。它买到的是 portability。
• Subagent - 把 tightly-scoped task 送到它自己的 context window，并拿回一份报告。
• /compact - 压缩这个 context，并用 summary 播种 fresh session。它是 default，位于树的底部，而不是最先伸手可及的地方。

关于有序的树，阅读 PHASE-BOUNDARIES.md：五个问题、每个分支背后的推理，以及为什么 primary-source 成本让 Continue 成为第一个要排除的选项。在 boundary 处做决定；阶段中途，要么继续，要么把剩余的工作拆成 subagents。

Standalone

完全在 main flow 之外。

• /grilling - 访谈 primitive 本身：rounds、frontier，facts 是 agent 的工作，decisions 是你的。/grill-with-docs 是它的 stateful 命名入口，/wayfinder 和 /improve-codebase-architecture 都在内部运行它。不在 working directory 中工作时直接使用它——打磨一个计划、一个设计、一段文字，任何没有 repo 承载的东西；它是 stateless 的，不在本地保存任何内容，也不构建 CONTEXT.md。在 working directory 中则改用 /grill-with-docs：它运行同样的访谈并留下文档痕迹，因此严格来说是更好的选择。
• /resolving-merge-conflicts - hunk by hunk 处理进行中的 merge 或 rebase conflict，依据能追溯到每一侧 primary source 的 intent 来解决，而不是挑选行，然后完成操作。它从不运行 --abort。完全 standalone，不属于任何 flow：当你已身处 conflict 中时使用它。
• /research - 把阅读工作委托给 background agent：它对照 primary sources 调研问题，然后在 repo 中留下带引用的 Markdown 文件。你可以在它阅读时继续工作。产物应带入 /grill-with-docs 的 main flow；research 提供思考材料，但不取代思考。
• /wizard - 用于只有 human 能完成的步骤：provisioning infrastructure、设置 credentials 或 CI secrets、在陌生的第三方 dashboard 中点击操作、运行一次性 migration 或 cutover。它生成一个交互式 bash script，打开每个 URL、捕获每个值，并写入 .env 和 GitHub secrets——这样该过程就不再需要你每次向 agent 重新解释。它是 model-invoked 的，所以 agent 一遇到只有你能通过的墙就会伸手够它。如果 agent 自己能做，它就应该自己做；这个 skill 用于 human 真正在 loop 中的场景。
• /writing-for-agents - 编写 agents 消费的文档的 reference：skills、AGENTS.md、被指向的 docs。

Precondition

/setup-skills - 首次使用 flows 前初始化 spect CLI、agent instructions（AGENTS.md/CLAUDE.md）与 CONTEXT.md、ADRs、OpenSpec 脚手架。