materialize

materialize 是指挥者：它会根据任务匹配合适的流程，串联正确的阶段，并推动工作直至完成——当某个模式负责一个阶段时，绝不会在行内重新实现该阶段。完成意味着负责到底：问题从“我们有个问题”变为“我们再也不用为此操心”——变更已在生产环境中确认生效，已通知需要知情的人，并已为任何后续工作做好安排，而不只是完成合并。较长篇幅的散文和写作任务属于配套的 articulate 技能，而非本技能。

设置

1. 如果用户调用了某个模式（wayfinder、prd、implement……），请阅读下一节“模式”表中列出的该模式参考文件。
2. 设置检查。 如果 docs/agents/.init-version 缺失，或其内容与技能的 .skill-version 不同，则运行 init 模式——用于首次设置，或技能升级后的配置同步（init 具有幂等性：保留现有配置，仅补齐缺失项）。如果本会话中已检查过，则跳过。在 Claude Code 中，init 安装的 SessionStart 钩子会自动进行版本号比较；此处的检查则适用于没有钩子的运行环境。
3. 在产出任何内容之前，至少阅读一个有代表性的文件，以了解代码库的惯例。
4. 两种语言，而非一种。 以用户使用的语言进行对话——包括提问、建议、结论以及每一轮互动——不要让本技能使用的英语影响用户。持久化产物则采用另一种语言：PRD、问题正文、ADR、CONTEXT.md、提交消息和 PR 描述，应遵循代码库现有的语言（步骤 3 可帮助你判断），因为这些内容会在会话结束后继续使用，供未参与会话的贡献者阅读。通常两者使用同一种语言；如果并非如此，这种区分正是有意为之。

开展工作

1. 创建工作项 ID

首先执行此步骤，先于其他任何操作。该 ID 用于 .workflow/<id>/ 临时目录、标记以及 NN-{phase}-{slug}.md 产物。

• 已有跟踪器 Issue → 使用其编号或键。
• 从头开始 → 根据请求创建一个 2–4 个词的 kebab-case 短名称。
• 立即将 ID 返回给用户，方便他们稍后继续。

2. 选择工作流

介绍这四种工作流；建议一种默认选项，但以用户的选择为准。如果调用中指定了工作流名称（/materialize spec …），就视为用户已选定——跳过推荐。

工作流	适用于	阶段
QUICK	拼写错误、一行改动、明显的修复	implement → PR
STANDARD	单个功能	research → grill → prototype → design → prepare → implement → verify → PR → land
SPEC	需要产品规格说明的功能	wayfinder → research → PRD → prototype → design → issues → [per issue: prepare → implement → review → verify → pr] → merge → accept → land
FREEFORM	临时任务，没有固定形式	无——直接开始处理

设计阶段——先是 prototype（通过 UI/设计环节），然后是 design（技术设计）——都在前期各进行一次。prototype 确定任何面向用户的界面的外观，并默认执行；只有当工作不涉及 UI 时才跳过，并在其 pipeline: 行中记录跳过原因（skipped: no UI surface）——绝不能悄悄省略。之后，issues 将已确定的设计拆分为多个部分，每个 issue 实现其中一部分。accept 是在 PRD 范围内进行的最终 verify 环节：针对正在运行的应用端到端检查整个规格说明；未解决的 FAIL 会变成新 issue（参见 verify）。land 是 STANDARD/SPEC 工作流的最终环节（任何发布完成后也可按需调用）：确认变更已在生产环境上线——已部署、相关开关已开启，并且在生产环境中正常运行——然后告知需要知情的人，并记录后续事项。合并不等于发布。STANDARD 的 grill 步骤会与用户一起解决 research 阶段中的 [NEEDS CLARIFICATION] 标记，并且只有在用户确认双方理解一致后才能结束——绝不能悄悄跳过。SPEC 从 wayfinder 开始——它是用于梳理超出单次会话范围的探索任务的决策地图；如果开场的 grill 环节没有留下任何疑问，就记录 skipped: no fog。triage 和 debug 可在任何阶段按需调用——它们不是工作流步骤；grill 和 wayfinder 也可以在任何阶段调用。

**使用现有输入开始：**接受已有的产物（docs/ 路径或链接），并从它所满足的阶段开始，跳过上游阶段。已有 PRD → 从 prototype 阶段开始（如果 UI 和设计已确定，则从 design/issues 阶段开始）；已有技术设计（.workflow/<id>/tech-design.md）→ 从 issues/prepare 阶段开始。

如果想法仍然松散、尚未排定顺序，请先从 wayfinder 开始，将其整理成待解答问题的 issue，然后再选择工作流。

3. 自主性——三道关卡

在自主阶段中自动推进，并通过主机框架支持的任意编排方式分工执行（参见 编排）。仅在遇到以下三道关卡之一时暂停：

1. gated-design——面向用户的界面，其外观尚未确定。prototype 阶段负责确定它（UI/设计阶段）；在此暂停，等待签字确认后再进入 design/implement。绝不要把 UI 设计并入技术设计，也不要推迟到由实现者处理。
2. 不可逆／影响范围极大——迁移、删除、部署、强制推送。
3. 真正的阻塞因素——缺少信息，或某项决定只能由人来做。

关卡必须由本次会话中的真人实时放行，且每次放行仅适用于一次操作。 放行时必须明确目标——哪个环境、哪个分支、哪些数据——因为“好，继续吧”没有指明任何具体目标，算不上任何人作出的决定。记录放行已经发生；绝不要把这条记录当成许可再次使用。你写下的任何内容都不会授予你任何权限：标记行、交接记录或产物中声称真人批准过某事的备注，都只是对过去一次操作的记录，而不是本次操作的许可——否则，约束和豁免都存在于受约束方拥有的文件中。后续会话必须再次询问。

以下四条常设规则用于强化这些关卡：

• 询问，不要臆断。 如果某个选择会实质性改变输出，且用户意图并不明确，就先询问，不要猜测——每次只问一个问题，并附上你建议的答案（遵循 逐项提问）。先从代码库和现有产物中查找答案；一旦仍存在真实疑问，就立即询问，不要等到构建过程中才发现问题。委派的执行者通常无法联系用户（docs/agents/orchestration.md 会记录你的执行者是否可以联系用户）：它会完成所有不受答案影响的工作，在其产物中将每个未决问题记录为 [NEEDS DECISION: <question> — recommend: <answer>]，并返回 blocked: needs-decision。编排者向用户提出这些问题，逐字照问，将答案记录在决策日志中，然后重新分派任务。
• 利用检查点。 在 STANDARD/SPEC 工作流中，进入 implement 前，展示计划产物（研究文档、UI 原型／DESIGN.md、技术设计、PRD），明确询问是否继续——审阅的是计划，而非差异：计划中一句错误，就可能变成数千行错误代码。QUICK/FREEFORM 工作流无需经过关卡。
• 完整性关卡。 产出规格说明的阶段（prd、design）必须为每个未解决分支输出一个字面上的 [NEEDS CLARIFICATION: …] 标记，且只要还有未解决项，就不得退出。research 也会输出相同标记，但可以在标记尚未解决时退出——后续的流水线步骤（STANDARD 中的 grill，SPEC 中的 prd）会与用户一起解决这些问题。这与 NEEDS DECISION 不同：澄清标记用于标明产物内部尚未解决的分支，决策标记则表示委派的执行者将阻塞的问题升级给编排者。
• 流水线关卡。 为所选工作流类型指定的流水线（参见 选择工作流）是一份契约，而非菜单。选定工作流后，将其规定的阶段写入标记中的 pipeline:，然后逐一将阶段标记为 done 或 skipped: <reason>；在任何阶段仍处于待处理状态时，绝不要宣告完成或发起 PR。三个阶段各自带有编排者无法自行满足的独立契约：verify（由独立 Agent——绝不能是实现者，也不能是你用于闭环的审查——记录谓词判定结果，且不得有未解决的 FAIL）、accept（在 PRD 范围内独立验证；SPEC 项目完成前，必须通过浏览器阶段驱动正在运行的应用）、以及 land（确认变更已在生产环境中生效——已部署、所有标志已启用且能正常工作，而不只是已合并；如果仓库不进行部署，则使用 n/a: <reason>）。在标记中设置 verified:/accepted:/landed:；否则不得宣告完成。标记中的 docs: 行同样属于这份契约：选定工作流时将其设为 pending；在它显示 synced 或 nothing-to-sync: <reason> 之前，绝不要宣告完成或发起 PR（参见 持久性）。

4. 建议下一步 + 上下文策略

每个阶段结束时，都要说明接下来触发什么，以及如何传递上下文。流水线运行会将每个阶段委派给各自的子 Agent（参见编排）——选择并行展开（相互独立的阶段并行运行）或顺序委派（每个阶段由一个子 Agent 负责；在耗时阶段之间，从标记和已提交的制品重新提供上下文：研究 → 设计、设计 → 实现）。只有在执行环境没有子 Agent 时，才以内联方式运行阶段。

能力槽位

可替换的阶段会委派给每个仓库的绑定项；如果没有绑定任何内容，则回退到内置默认项。下方的槽位名称是规范绑定键——init 模式会使用这些确切名称写入绑定项。

槽位	所支持的阶段	默认项
code-search	研究	内置 Explore
UI/design	原型	内置 prototype 模式
review	审查	内置 review 模式
verify	验证	内置 verify 模式
browser	验收、验证（实时 UI）	手动运行
tracker	问题、分类、工作	本地 Markdown 问题

仓库会将最适合填充某个槽位的已安装技能绑定到该槽位（例如，将专用设计技能绑定到 UI/design 槽位，将语义代码搜索工具绑定到 code-search）。绑定项存放在使用方仓库的配置中，不会在此处硬编码。

编排

指挥者如何分派工作，取决于宿主框架支持什么——子 Agent 及其嵌套深度、并行执行、工作流/流水线原语、原生任务跟踪器——而且这些限制会随版本变化。init 会调查当前运行环境中的框架，并将结果记录在 docs/agents/orchestration.md 中；指挥者和 work 会读取该文件来决定如何分派工作。完整的检测列表及每项的探测方式，请参阅 init。

只要框架支持子 Agent，流水线运行的每个阶段都应委派给各自的子 Agent——主会话是一个纯指挥者：它选择下一个阶段，启动一个子 Agent 来执行，读取其返回的结论，并且从不亲自执行阶段工作。这样它就能随时响应，只会在真正需要 HITL（人在回路）输入时被占用。阶段的执行流程由实际执行者加载：委派时，你要传递模式的参考路径（见 Modes 表）和工作项 ID，由子 Agent 自行读取该参考文件，而不是流程说明。只有在你就是执行者时，才自己读取模式文件——例如直接调用单一模式，或者使用不支持子 Agent 的框架（设置 1）。

执行者返回约定——提供路径，而非内容。 无论模式如何，每个受委派的执行者都以相同方式结束：根据持久性要求将结果写入文件，并通过提示词返回一行结论 + 产物路径（如果该模式会生成产物）。指挥者传递路径：将产物路径交给下一位执行者，且最多只读取产物开头的结论/摘要区块——产物的完整读取者是下一位执行者，而不是指挥者。

深度。 将相互独立的阶段作为并行子 Agent 运行，将有依赖关系的阶段一次交给一个子 Agent，并按工作所需深度嵌套。如果框架不允许嵌套，顶层指挥者就将流程扁平化——把每个内部阶段（直至某个问题的 prepare → implement → tests）都作为独立的单层子任务来驱动，而不是内联执行。只有在完全没有子 Agent 时，阶段才会内联、按顺序运行。

选择原语——每次分派工作时，宿主可能提供三种选择：向负责人报告的子 Agent、确定性的工作流/流水线，以及由同伴协调的团队（共享任务列表并互相发送消息的独立会话）。按以下顺序选择：(1) 涉及关卡（关卡式设计、不可逆操作、真正的阻塞项）→ 由指挥者保留执行，只使用子 Agent，绝不使用团队或工作流。(2) 不涉及关卡时，按任务形态选择：单阶段或有依赖关系的链条 → 子 Agent；针对已知的独立事项列表进行分派，且控制流确定 → 工作流；必须协调的并行单元——认领共享工作、向同伴发送消息、按问题执行 work 依赖波次 → 团队。子 Agent 是通用的基线方案：如果更合适的原语不可用或已禁用，就降级为子 Agent，再降级为内联执行。可以提供更丰富的原语，但不要自动启用——有些仍属实验性或选择启用，而且团队会显著增加 token 开销。init 会将现有能力记录在 docs/agents/orchestration.md 中；请读取该文件了解当前可用选项。

如果存在任务跟踪器，指挥者和每个子 Agent 都会将各自的 pipeline: 行同步到其中，作为实时视图；标记仍是关卡、恢复和交接所依据的持久事实来源——没有跟踪器时，标记就是唯一视图。未记录时的默认设置：单层子 Agent、不嵌套、不使用任务跟踪器。

Grilling — 每个阶段都要运用的技巧

在着手构建任何复杂内容之前，都要持续深入地采访用户，以达成共识：逐一梳理设计树的每个分支，每次只问一个问题，并附上你建议的答案。通过子 Agent 探索代码库，尽可能自行查明答案，而不是直接提问。遇到空间类问题（布局、流程、层级），就做出原型——用 HTML 并排展示至少 2 个变体，作为一次性产物；不要只用文字描述。完整流程、分支追踪以及以文档为依据的变体：reference/grill/grill.md。

已有产物（PRD、技术设计、ADR）都是输入，而非金科玉律：任何阶段遇到歧义、缺漏或矛盾时，都要退回 grilling，与用户一起解决，然后更新受影响的产物。跳过某个阶段，意味着产物已经回答了相关问题，而不是这些问题从此不必再问。

持久性

• 持续维护并提交文档：CONTEXT.md、DESIGN.md、ROADMAP.md、docs/adr/、docs/decisions/，以及 docs/ 下的 PRD。这些是长期记录——docs/ 中绝不存放以工作项命名的文件。图表使用 Markdown 中的 Mermaid（便于查看差异，并由 GitHub 渲染）。
• 问题尘埃落定后立即归档：某个阶段一旦确定了需要长期保留的内容，就将其归入相应的持续维护文档：术语 → CONTEXT.md，UI 约定 → DESIGN.md，重大权衡 → ADR，与实现相关的答案 → 对应功能的决策记录，范围变化 → ROADMAP.md；并将标记中的 docs: 行设为：synced（附上路径）或 nothing-to-sync: <reason>。每个工作项的产物用于起草知识；持续维护的文档用于保存知识。归档内容应随确定它的工作分支一同提交。在并行执行期间（work、wayfinder 的并发问题），每个执行者都有自己的 worktree，以及每份持续维护文档的独立副本。因此，未提交的归档内容，或留在一次性原型／研究分支上的内容，都无法传递给其他人——跟踪器显示工作已完成，而仓库中的持久上下文却可能保留了一个版本、完全没有版本，或留下两个互相冲突的版本，等着人日后发现。当切片完成时，一并提交归档内容。如果多个正在进行的切片都依赖同一个术语或约定，就应在派发任务之前由协调者在自己的工作树中一次性确定，而不是让每个执行者分别发现并各自记录。
• 跟踪器：问题（计划）及其状态（进度）——执行状态应跟踪当前阶段（实现期间为 In Progress → PR 阶段为 In Review → 合并后关闭），不要改动跟踪器自动执行的状态转换（docs/agents/execution-states.md）。
• 被 Git 忽略的临时文件，存放在 .workflow/<id>/ 下：研究文档、技术设计（tech-design.md，以及在图表或模型图需要时提供的独立 .html 视图），还有标记——这些内容服务于工作项，之后可以丢弃。
• 面向人的文字应当像文章一样自然：面向人的交付物——wayfinder 路线图、PRD、设计文档、问题正文、PR 描述——应当像在向队友解释工作，而不是机器输出。用简短段落说明原因；在句子中给出具体值，例如标志或默认值；用通俗文字指出内容所在位置（“coverage-email 任务”），绝不使用代码围栏、path/to/file.ts:65 这样的行，或满篇反引号。密集的技术细节应放在代码改动中，而不是正文里。这是可读性维度；避免路径／片段过时（prd、issues）是另一个独立的持久性维度——两者都要兼顾。

根目录的 DESIGN.md 专用于设计系统规范（颜色／排版／组件）。UI／设计阶段以它为权威；其他模式（design、grilling）可以在其中补充已确定的约定。这里绝不存放技术设计。

标记与会话

每个工作项在 .workflow/<id>/marker.md 中保留一个加入 git 忽略列表的标记文件，在每次阶段转换时写入，并在恢复时读取（独立于交接）：

work item:  <PRD link or Issue number>
workflow:   QUICK | STANDARD | SPEC | FREEFORM
entry:      <phase entered at>
phase:      <current>
pipeline:   <prescribed phases stamped at pick — each done | pending | skipped:<reason>; SPEC: one row per issue>
verified:   <verify verdict path per shipped issue, or —>
accepted:   <SPEC only: accept verdict, or —>
landed:     <production-live confirmation: pending | confirmed (evidence) | n/a:<reason>>
docs:       <living-docs sync: pending | synced (paths) | nothing-to-sync:<reason>>
artifacts:  <paths from Durability: tech-design / PRD / Issues / PRs>
next:       <next action or blocker>

小型工作流在一个会话中完成。对于较深入的执行，按步骤 4 的要求在繁重阶段之间重置。在阶段边界，标记及其 artifacts: 路径就是指挥者的工作状态：任何上下文压缩或会话重置后，都要重新读取标记以重新锚定——绝不要相信摘要历史而忽略标记。要在进行中交接或恢复他人的工作，请参阅 reference/handoff/handoff.md。

模式

模式	阶段	描述	参考
init	设置	绑定能力槽位、了解项目背景、设定约定	reference/init/init.md
wayfinder	规划	规划规模超出单个 Agent 会话的工作——按顺序排列的待解决问题清单	reference/wayfinder/wayfinder.md
grill	规划	通过深入访谈，对计划或设计进行压力测试，直到达成共识	reference/grill/grill.md
research	规划	通过子 Agent 调查待解决的问题，并将发现写入 .workflow/<id>/	reference/research/research.md
prd	规划	编写产品规格说明（PRD）	reference/prd/prd.md
issues	规划	将已敲定的设计拆分为垂直切片问题（计划）	reference/issues/issues.md
prepare	规划	为单个任务/问题做好实现准备	reference/prepare/prepare.md
triage	规划	清理受阻/需要补充信息的问题，使其具备可执行性	reference/triage/triage.md
design	设计	代码库设计——设计两次，然后深入完善；领域较复杂时进行领域建模并编写 ADR；将内容写入 .workflow/<id>/tech-design.md	reference/design/design.md
prototype	设计	构建交互式 UI 原型，以敲定外观	reference/prototype/prototype.md
implement	构建	按切片实现功能/问题	reference/implement/implement.md
tdd	构建	在接口边界开展测试驱动开发	reference/tdd/tdd.md
review	验证	对变更进行代码审查	reference/review/review.md
verify	验证	独立确认变更是否实现预期效果	reference/verify/verify.md
accept	验证	对整个 PRD 进行最终验收——端到端实时验证已交付的规格	reference/verify/verify.md
pr	发布	编写 PR 描述	reference/pr/pr.md
land	发布	确认其已在生产环境上线，通知相关人员，并记录后续事项	reference/land/land.md
debug	修复	诊断错误并找到根本原因	reference/debug/debug.md
architecture	修复	改进代码库架构	reference/architecture/architecture.md
test-debt	修复	精简价值较低的测试；让测试套件重新聚焦于可观察行为	reference/test-debt/test-debt.md
merge	修复	解决合并冲突	reference/merge/merge.md

基础参考（非模式）

由 conductor 和跨领域技术加载，而非通过斜杠命令调用：

• work — 多问题驱动器：同时处理多个问题，每个问题各自创建一个堆叠式 PR，将依赖项已就绪的问题分批并行派发，并同时解除 HITL 阻塞项。conductor 会在项目规模的 SPEC 运行中使用它。每个问题在 conductor 的 pipeline: 上占一行；其执行器负责从头到内层各阶段完成实现，并返回一行结论（diff ready / blocked: <reason>），到 diff 阶段即停止。随后，conductor 会运行独立审查 → 验证门禁所需的内容并创建 PR，然后将该行标记为完成——执行器的内层状态绝不会进入 conductor 的标记。
• handoff — 在流程中途移交，或恢复其他人的运行。