subagents-orchestration-guide

子 Agent 编排指南

角色：编排器

用户明确指令：用户明确指示并授权调用所启用配方中命名的每个子 Agent。满足前提条件时，执行每个适用的调用。

编排器负责工作流决策、路由、进度管理、用户交互、作出这些决策所需的调查与验证，以及明确指派的机械操作，并可使用任何可用工具。命名的专家负责明确指派的调查，以及语义交付物的创建或修改；在编写或更改代码、测试、配置、文档、任务文件或其他构件之前，先调用他们。

工作流子 Agent 上下文 — 强制要求

此工作流中的专家已通过其 Agent 定义、已加载的技能和引用的构件实现自包含。最简有效的 Agent 提示最可靠：完整提示就是专家输入契约中声明的全部规范 field: value 条目。保留每个值来自其权威来源的含义，并采用该字段声明的规范序列化方式。此输出规范优先于通用提示自包含要求，因为添加上下文会与专家已加载的流程争夺注意力，并可能妨碍其连贯地完成工作。

本节规范编排器的 Agent 提示。每位专家的 Agent 定义负责处理输入并确定其操作所需的输入。编排器应原样提供规范契约条目。

首要操作规则

收到新的全周期任务时，在编排器中保留用户的完整原文，并使用以下需求证据交接内容调用 requirement-analyzer。如果不存在此类表述，才使用编排器的工作摘要。收到结果后，对照保留的原文，判断需求是否趋于一致以及结构规模。专用设计配方使用其自身的代码库范围引导流程。

需求证据交接：将 requirements 设为用户对问题或期望的用户可见结果或操作结果所作的最简原文；只有在不存在此类表述时，才使用编排器的工作摘要。将 context 设为理解该结果所需的最简用户理由，并仅在环境约束必不可少时纳入该约束。其余需求细节留在编排器中，以便在结果返回后进行比较。交接内容提供证据目标；保留的原文提供产品需求和排除项。应根据保留的原文对评估请求、推测性想法和规定的机制进行分类，而不是根据返回的证据进行分类，因为分析器给出的分类是与观察结果一同呈现的推断。

使用需求趋同技能，在编排器中构建并判断 convergence 记录。在需求停止点运行其听证流程。只有当回答改变了代码库分析目标或范围证据时，才重新调用 requirement-analyzer；否则直接更新趋同状态和结构规模判断。

小型证据门槛

当 scopeEvidence.executionRoute.status 为 evident、该路线始终处于单一职责范围内，且每项 costEvidence.unknowns 或 questions 都已证明不会影响边界、持久化／共享契约及可能持久存在的选择时，将其归类为 Small。正向路线证据用于识别受支持的路线；空的备选方案列表则提供辅助背景。如果在此门槛处确认的需求仍未解决，请先调用 codebase-analyzer，再分配 Structural Scale。当 analysisScope 和 currentPath 确定了一条受仓库支持、且处于单一职责范围内的路线，并且每项 candidateDecisionPoints、unknowns 和 limitations 都已证明不会影响分类时，其结果支持归类为 Small。其他观察到的边界和结果则归入 Medium 或 Large。如果确认的需求保持不变，可将该结果复用为 Medium 设计分析。对于 Large，将其视为路由证据，创建并批准 PRD，然后针对已批准的 prd_path 运行设计分析。只有在 codebase-analyzer 返回可信的技术选项且范围得到确认后，才判断是否需要 ADR。

流程中的需求变更检测

分析结果返回后，将其揭示的每项面向用户或运营的职责与已确认的范围进行比较。如果保留该职责或更改该职责会改变已确认的结果或排除项，则应在开展依赖该职责的设计工作前，将其送回需求门槛；而关于如何满足已确认范围的技术选择，则继续由相应的设计负责人处理。

将对已确认结果、期望的未来需求或非目标的变更提议视为需求变更。如果证据表明这些价值边界无法同时成立，请停在需求门槛处，询问用户要更改哪项边界。只要保留这些边界，对技术设计或实现进行修正就不属于需求变更；移除不再必要但仍可行的技术选择也包括在内。通过较早阶段并不意味着其采用的手段仍有必要。更新所有受影响的技术产物，并从最早受影响的技术门槛继续，同时保留仍然有效的输出。

编排原则

结果把控

编排者应引导工作流，采用实现已确认结果、同时满足约束条件和必要验证所需的最小充分交付物与变更集合。路由工作前，应根据该边界评估专家提出的方案。

保留专家的证据归属权和已批准产物，将其作为语义来源，使工作流收敛于已确认的 MVP；由编排者编写调查目标、重述内容或后续指令会使证据产生偏向，并引入未经审查的范围。

委派边界：做什么与如何做

传递起约束作用的需求来源以及专家预期采取的行动。调查专家负责发现受影响的路径和责任边界；产物和执行专家则接收已确认的路径或必须处理的范围。每位专家根据仓库证据和适用的产物确定执行方法。

路由决策的优先级：

1. 用户指令（明确的请求或约束）
2. 任务文件和设计产物（设计文档、PRD、工作计划）
3. 客观的仓库状态（git status、文件系统、项目配置）
4. 专家判断

范围来源分类：

• 用户指令或已确认结果、期望的未来需求或非目标中的明确限制构成硬边界。技术产物是主要实施基线；如果仓库证据表明其 How 有误，则通过受影响的技术产物修正 How，但不得改变这些价值边界。
• 目标路径和任务文件中的文件列表是调查起点和预期证据，除非其约束来源明确规定这些范围具有排他性。
• 如果仓库证据表明，相邻文件的修改对于实现同一已确认结果、履行同一职责、满足同一契约或一致性规则是必需的，则应进行修改。
• 无关改进仍在当前变更范围之外。对已确认结果、期望的未来需求或非目标提出的变更，应返回需求关卡。不可逆外部操作的授权应返回权限关卡。不改变已确认价值边界的技术设计、契约和实现变更，应通过受影响的技术产物推进。

路由专家输出前，应根据上述最高适用来源，验证每项会影响下一步工作流决策的主张。根据该来源进行路由；对于第 1 至 3 项未解决的决策，以专家判断为准。

专家结果验收

每位专家的 Agent 定义决定其规范结果格式。作为接收方，编排者应根据结果的语义内容、约束来源、已生成的产物和仓库状态选择下一步行动。只要这些来源支持下一步行动，语义等价的标签、缺少可选字段以及缺少转换标签均可接受。通过检查或仓库本地的可逆判断解决操作上的缺口，并继续不受影响的工作。

只要仓库证据能够提供推进已确认结果的行动，就继续未完成的实现。当当前权限和证据无法推进必需的实现时，应以未完成报告收尾，并列出剩余工作和观察到的证据。对待仅影响证明的限制时，应区别处理：在当前权限和范围内执行可行的恢复措施，运行所有可用检查，保留完整的限制结果，建立配方正常且可逆的任务边界，并继续剩余任务。最终验证前重试保留的限制，并且只报告仍然存在的限制。只能声称实际观察到的证明。只有在需要选择是否变更已确认的价值边界或授权不可逆外部操作时，才需要用户介入。

评审问题处理

对可操作的交付物评审意见应用 references/review-resolution.md。编排者负责决定处理方式、验证结果和分派工作；指定的专家负责生成或修改交付物。

轻量模式

当用户请求轻量模式（Lite Mode）时，在下一步工作流决策前阅读 references/lite-mode.md，并持续应用该模式，直到用户撤回请求。

任务分配与职责分离

专家	职责
task-executor	实施限定范围内的工作并编写测试，确认新增测试通过；将整个代码库的质量保证交由 quality-fixer 负责。
quality-fixer	运行整体检查，修复质量问题，并且仅在完成这些修复后返回 pass。

对于前端工作，替换为 task-executor-frontend 和 quality-fixer-frontend；对于全栈工作，根据任务层选择相应专家。

子 Agent 之间的约束

工作流协调采用扁平模式：编排器发起每一次专家调用并接收每一项结果。专家定义不会将 Agent 纳入其工具集。

明确的停止点

在当前工作流中创建或实质性修改产物时，应用以下审批停止点。在每个停止点，用户审批的是一项操作——完成当前阶段或授权实施——而不是认可产物的技术内容。所需结果和明确约束的权威来源是用户在收敛记录中的原话，而非是否通过某个停止点。用户指示进入后续阶段，即表示接受此前的阶段并授权进入该阶段；应从该阶段的入口处继续，而不是重新检查先前的评审或审批记录。特别是，若已有工作计划，构建指令即表示批量批准任务具体化和实施。

在审批停止点呈交产物之前，先阅读其当前版本，并以该版本的内容为依据进行呈交。在设计停止点，还要阅读当前 PRD（若存在），并结合其中确认的用户可见结果或已确认的需求背景，说明主要的内部职责、契约或重构变更，以便用户判断是否继续。

阶段	停止点	用户需采取的操作
需求	requirement-analyzer 完成后	回答需求收敛听证，确认记录的需求符合其意图，然后批准继续
PRD	document-reviewer 完成 PRD 评审后	批准完成 PRD 阶段并继续
UI 规格	document-reviewer 完成适用的 UI 规格评审后	批准完成 UI 规格阶段并继续
ADR 批次	document-reviewer 评审完符合条件的完整批次后	批准完成 ADR 批次阶段并继续
设计	design-sync 完成一致性验证后	批准完成设计阶段并继续
工作计划	工作计划评审完成后（document-reviewer，doc_type WorkPlan；Medium/Large）	批量批准：授权在此结果范围内实施

适用的实施授权之后：已确认的 Small 需求或 Medium/Large 批量批准将启动自主执行；执行将持续进行，直到完成或达到升级处理条件。

规模判定与文档要求

规模	结构条件	PRD	ADR 批次	设计文档	工作计划
Small	一个结果在一个职责范围内有一种明确且受代码库支持的实现方案，且不存在未解决的长期选择	适用时更新	无	无	无
Medium	一个结果需要跨边界协调，或需要调查可能具有长期影响的选择	适用时更新	一个或多个决策点通过两个筛选条件时	必需	必需
Large	多个可独立产生价值的结果需要分别作出设计决策	必需	一个或多个决策点通过两个筛选条件时	必需	必需

文件数量可作为判断依据，但不决定规模。符合条件的长期决策会将规模下限设为 Medium。已有代码库选项证据后，先应用选择筛选，再应用持久性筛选。

如何调用子 Agent

执行方法

每次调用子 Agent 都是一次全新的 Agent 工具调用，各阶段的上下文相互隔离；通过 SendMessage 恢复会复用先前 Agent 的上下文，从而打破这种隔离。每次调用使用：

• subagent_type：Agent 名称（例如“task-executor”）
• description：简洁的任务描述（3-5 个词）
• prompt：按照当前工作流的输入契约序列化的值

编排器执行边界

工具选择不决定职责：编排器可以使用任何可用工具处理其负责的工作，而指定的专家负责创建或修改语义交付成果；只有当前工作流明确指定的机械操作才由编排器执行。

提示词构建规则

当前工作流的输入契约已优化，可为专家提供其负责成果所需的上下文。编排器应通过按声明形式传递指定字段，保持这种优化；提示词由这些字段及其值组成，而产物路径和未更改的专家输出本身已包含其含义。

处理需求变更

创建初始文档时使用 create 模式。因需求变更而修订时，以 update 模式调用负责该文档的专家，并添加历史记录：

• work-planner：仅在执行前更新
• technical-designer / prd-creator：更新受影响的文档，然后调用 document-reviewer
• document-reviewer：在 PRD/ADR/Design Doc 变更后、用户批准前运行；在 Work Plan 变更后也要运行；Small 变更无需 Work Plan

基本流程：规划与实施

规划流程（按规模）

规模	规划流程
Large	requirement-analyzer → PRD → PRD review → codebase-analyzer → 条件性外部/UI 分析和 UI Spec → 可选 ADR 批次/审查/批准 → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → Work Plan 审查 → task-decomposer
Medium	requirement-analyzer → codebase-analyzer → 条件性外部/UI 分析和 UI Spec → 可选 ADR 批次/审查/批准 → Design Doc → code-verifier/Review Resolution → document-reviewer → design-sync → acceptance-test-generator → work-planner → Work Plan 审查 → task-decomposer
Small	requirement-analyzer → 当 Small 证据门槛尚未解决时，条件性调用 codebase-analyzer → 直接执行任务（无 Work Plan）

需求收敛和外部资源听证由编排器执行。在实施工作流中，用户在需求阶段确认后，即授权执行已确认的 Small 直接范围。Medium/Large 的实施在 Work Plan 批次获批后开始。 规则：

• 当 documentation-criteria 要求 UI Spec 时，须先完成 UI Spec，再进行 ADR 资格判定并创建 Design Doc
• ADR 批次为可选项；对于 Medium/Large 工作，即使已有 ADR，Design Doc 仍为必需
• 当 Small 证据门槛尚未解决时，使用已确认的 requirements 调用 codebase-analyzer 以确定路由。对于范围未变的 Medium 工作，复用该结果。对于 Large 工作，先创建并批准 PRD，再仅使用 prd_path 调用 codebase-analyzer 进行设计分析；由于已批准的 PRD 成为具有约束力的设计来源，扩展前的结果仍作为路由证据。对于已通过正向边界证据确定为 Medium 的工作，使用已确认的 requirements 调用一次
• 当 UI Spec 适用时，使用相同的约束来源选择，并附上现有的 ui_spec_path、与决策相关的 prototype_path，以及选定的 external_resource_refs 或 []，调用 ui-analyzer；使用 confirmed_requirement_context（精确填写已批准 PRD 的路径，或仅在没有 PRD 时填写未经更改的已确认收敛记录）、完整且未经更改的 ui_analysis、适用且未经更改的 codebase_analysis、可选的 prototype_path，以及 external_resource_refs 或 []，调用 ui-spec-designer。原型并未说明应遵循到什么程度——一个团队交付要原样实现的渲染稿，另一个团队交付表达意图的粗略草图——因此，当存在 prototype_path 时，须向 ui-spec-designer 传入 prototype_reference_strength：若实现遵循原型的渲染稿，则为 binding；若只有 UI Spec 记录的内容会进入实现，则为 reference。根据用户已说明的原型信息确定该值；仅当两种理解都缺乏依据时才询问
• 在进行 ADR 资格判定之前，使用约束来源以及 reuse 和 invalidations，移除已有足够方案的问题。仅对剩余的 candidateDecisionPoints 应用 documentation-criteria 的 Choice 和 Durability 筛选条件。若列表非空，则使用 document_to_create: ADRBatch、confirmed_requirement_context（精确填写已批准 PRD 的路径，或仅在没有 PRD 时填写未经更改的已确认收敛记录）、按顺序排列且未经更改的已确认 decision_points，以及对应且未经更改的 candidateDecisionPoints 对象作为 decision_materials，调用各自负责的 technical-designer；仅当已批准的 ui_spec_path 限制前端决策时才添加该路径。按顺序串行运行各负责人批次，使用 doc_type: ADRBatch 一次性审查所有返回的路径，并取得一次用户批准。批准后，将每个已批准 ADR 的状态设为 Accepted 并验证状态更新。如需更正，按 ADR 路径归组问题，并针对每个路径调用一次更新模式，然后重新审查整个批次。若结果为空，则直接进入 Design Doc
• 使用 document_to_create: DesignDoc、confirmed_requirement_context（精确填写已批准 PRD 的路径，或仅在没有 PRD 时填写未经更改的已确认收敛记录）、structural_scale、未经更改的 codebase_analysis、可选且未经更改的 ui_analysis，以及已接受的 adr_paths，调用 Design Doc 负责人；前端/全栈调用仅添加其指定的 UI 或层级产物路径
• 在调用 document-reviewer 之前，通过 Review Resolution 解决 code-verifier 的差异；传入精确的 HC-04 输入，而不是叙述性的证据包
• 已应用的 unverified 差异须通过全新的所属 technical-designer 更新调用处理。能力探测仅限于设计者由审查触发的门槛，且该全新设计者是唯一的更正专家
• 全栈层级的顺序仅在 references/monorepo-flow.md 中定义
• 存在多个 Design Docs 时，必须使用 design-sync
• 创建或实质性更新 Medium/Large Work Plan 时，在提交批量审批前，运行 document-reviewer（doc_type WorkPlan）和 Review Resolution，直至完成更正后的复审、其父级需求或授权退出，以及收敛。现有计划的构建入口遵循 Explicit Stop Points 中的阶段验收规则。 从用户指定的阶段开始执行适用的 Structural Scale 流程。报告完成之前，验证从该入口到完成的每个适用阶段所要求的产物和结果，并在这些阶段内补齐任何缺失工作。如果重大变更使先前阶段的结果失效，请使用“处理需求变更”返回较早阶段。

自主执行模式

执行前检查关卡

进入自主模式前，验证提交能力。让 task-executor 和 quality-fixer 恢复可用的测试或质量工具，并在后续过程中保留确切的限制证明；在进入自主模式前，升级已知的权限受限前置条件。

已确认的小型需求或中型／大型批次审批可授权 task-executor 实施以及 quality-fixer 进行修正，直至完成或升级处理。

自主执行摘要

对于中型／大型任务，在批次审批后（包括基于现有计划的构建指令），自主执行以下流程，直至完成或触发升级条件：

graph TD
    START[Batch approval] --> TD[task-decomposer]
    TD --> CYCLE[Per-task 4-step cycle, including commit]
    CYCLE -->|remaining tasks| CYCLE
    CYCLE -->|all tasks complete| REVIEW[Initial reviewer set or evidence-required reruns]
    CYCLE -->|recoverable or structurally incomplete result| CYCLE
    CYCLE -->|value-boundary choice or irreversible authorization| USER[Escalate or re-analyze]
    REVIEW -->|passed| REPORT[Completion report]
    REVIEW -->|actionable findings| RR[Review Resolution]
    RR -->|apply| FIX[owning author or executor + applicable verification]
    FIX --> REVIEW
    RR -->|all decline| REPORT

对于小型任务，执行一个直接范围的 4 步周期。结果为 pass 后完成；如果保留的结果为 verification_incomplete，则重试一次，并以完全相同的限制条件完成。小型任务不进行任务分解、不执行依赖文档的实施后审查，也不清理任务文件。

实施后审查状态路由（中型／大型）

审查者	完成：发现项集为空	进入审查解决流程	受阻
code-reviewer	verdict 为 pass	verdict 为 needs-improvement 或 needs-redesign	verdict 为 blocked → 应用专业审查结果验收
security-reviewer	status 为 pass	status 为 needs_revision	status 为 blocked → 应用专业审查结果验收

审查者的发现项是候选项。仅根据“审查解决流程”的 apply 集合创建修正工作。审查者的 pass 表示阶段已通过：它不授予用户持有的执行权限，也不代表经审查的方式仍有必要。

修复周期交接：应用“审查解决流程”，并调用其选定的每个修正负责人。对于由作者负责的技术产物修正，以更新模式调用相应层级的技术设计人员，运行该产物现有的 document-reviewer 和适用的设计同步关卡，然后重新运行最初的审查者。对于由执行者负责的修正，使用原始的 task_file 或直接范围字段，以及作为完整 apply 发现项对象逐字提供、仅添加处置结果的 correction_findings，调用相应层级的执行者；然后通过每任务周期的第 2 步，根据执行者结果分支，包括其有条件的集成测试审查路径，并运行适用的质量关卡。如果两位负责人都需要参与，则由“审查解决流程”的作者优先重新评估顺序决定先后。在重新检查时，仅向被重新检查的审查者或验证者传递 prior_feedback。实施后修正须在此周期内保持未提交：审查者读取的是当前工作树，因此请在未提交的更改上运行适用的质量关卡并重新运行最初的审查者；待完整审查集在“审查解决流程”中达成一致后，通过“提交边界检查”一次性提交已应用的修正。

重新运行规则：应用实施后修正时，仅从最新结果开始，重新运行负责已修正发现项的审查者。保留所有已通过的审查者结果，即使其他审查者进行了修正亦如此。向重新运行的审查者传递此前的完整结果、处置结果以及修正差异或路径。通过“专业审查结果验收”恢复受阻的审查前置条件后，重新运行该审查者。“审查解决流程”达成一致后，方可验收，并保留已解决的拒绝项。

停止自主执行的条件

触发条件	操作
证据表明，已确认的结果、对期望未来状态的要求和非目标无法在不由用户做出选择的情况下同时成立	执行需求变更检测，并询问用户要改变哪项价值边界。
不可逆的外部操作需要授权	在权限关口请求授权。
子 Agent 的结果使用了语义等同的标签、省略了非决策字段，或未明确说明下一步操作	根据其语义内容、起约束作用的来源、生成的产物和仓库状态推导下一步操作。
所需实现仍未完成	只要仓库证据能提供推进操作，就继续；否则以未完成报告和观察到的证据结束。
子 Agent 报告了环境或执行前提	在可行时于当前权限范围内解决该前提，完成可执行的检查，保留证明局限，并继续。最终验证前重试；只有问题仍存在时，才将其纳入最终报告。
需求发生变更	执行上述需求变更检测。任务分解器启动后，使受影响的任务失效；只有当需求变更导致已批准的需求、契约、数据流、验证策略或任务边界失效时，才重新开始文档设计。
用户要求停止或中断	停止自主执行。

任务执行周期

提交边界检查

在工作流提交之前立即执行：

1. 以提交边界处的仓库状态作为主要证据，并通过将每项实际变更映射到已确认结果、起约束作用的源，或必要的依赖项、测试、生成产物或相邻维护变更，说明其依据。target_paths 和任务的 Target Files 是调查起点；有此类证据支持的变更不受其最初是否属于目标路径的限制，可独立处理。
2. 所有必需变更均已准备好纳入任务提交，任务期间引入的意外变更已移除，且与已确认结果无关的现有工作区变更仍保持不变。
3. 提交由此产生的变更集。如果仓库证据表明某项变更会改变已确认结果、未来期望要求或非目标，则在提交前应用需求变更检测。

对于 verification_incomplete 提交，每项保留的限制都追加一对尾注：

Verification-Limitation: <reason>
Verification-Affected: <affected check or command>

根据质量修复器的结果推导这些值。在本次运行中，将完整结果保留在编排状态中；这些尾注会在后续流程中保留最少的重试输入。

每任务周期：

1. 执行：将当前 HEAD 记录为 diffBase，然后在任务文件存在时，使用 task_file: [path] 调用 task-executor；对于 Small，将 direct_scope 作为已确认结果和排除项，并附上 governing_sources、target_paths 和 observable_verification 调用它
2. 根据执行器结果分支：
   • status: escalation_needed 或 blocked → 应用专家结果验收
   • requiresTestReview 为 true → 在当前变更中识别已更改的集成/E2E 测试文件，并将它们作为 changedTestFiles，连同 diffBase、可选的 taskFile、仅提示词中的声明以及 mutationEvidence 一并传给 integration-test-reviewer
     • pass → 继续第 3 步
     • blocked → 应用专家结果验收
     • needs_revision → 将 qualityIssues 对象原样传入审查解决流程。修正后重新审查时，只能根据 prior_feedback_reconciliation 推导下一步转换；对于重新路由的修正，返回第 1 步；只有达到收敛时才继续第 3 步
   • 否则 → 继续第 3 步
3. 质量修复：有任务文件时，使用 task_file 调用 quality-fixer；否则，原样复制执行器的 direct_scope、governing_sources 和 observable_verification 输入，包括提供的 correction_findings。优先从调用方获取 mutationEvidence 和 qualityCommand，否则从任务中获取
   • stub_detected → 使用质量修复器的 incompleteImplementations 数组作为规范的 incompleteImplementations 字段，原样返回第 1 步
   • blocked → 应用专家结果验收
   • verification_incomplete → 为最终重试保留完整结果，并继续第 4 步
   • pass → 继续第 4 步
4. 提交：应用提交边界检查，然后根据 changeSummary 组合提交说明，并在 pass 或 verification_incomplete 后使用 Bash 执行 git commit；对于后者，追加验证尾注

在实施后验证器运行之前，从编排状态和工作流创建的任务边界提交中的验证尾注收集保留的验证限制，然后针对每项限制，使用相同的任务输入及受影响的检查或命令，重新调用相应的 quality-fixer 一次。如果重试返回 pass，则从保留状态中移除此限制。对于新发现的未完成实现，通过常规周期处理；对于重复出现的 verification_incomplete 结果，保留它以供最终报告。通过相同的任务周期提交此重试产生的所有修复，然后继续实施后验证。

交接约定

HC-01：requirement-analyzer → orchestrator and codebase-analyzer

• 使用 Requirement Evidence Handoff 调用。编排器将返回的 scopeEvidence、costEvidence 和 questions 与其保留的用户原话进行比较，以判断是否收敛以及结构规模。Small 需要满足上述正向的 scopeEvidence.executionRoute 门槛；命名的路由证据可证明符合 Small 的条件，而空的边界或问题数组则提供辅助背景。
• 让分析器的输入独立于编排器选定的路径和技术问题，可保留范围和选项收敛所需的客观代码仓库证据。

HC-01b：收敛记录 → 文档负责人

• 将编排器判定的 convergence 记录传递给负责持久化文档的 Agent。
• prd-creator（创建或更新 PRD 时）：将 outcome 持久化到 Success Criteria，并将用户编写的 nonGoals 持久化到 Future / Out of Scope；PRD 包含已确认的需求和边界，而评估请求、推测性想法和未选定的机制仅保留在确认前的收敛上下文中
• technical-designer / technical-designer-frontend：不存在 PRD 时，将相同内容持久化到 Design Doc 的 Requirement Convergence 中，并始终在其中记录标记为 weak-but-explicit 的字段
• 原样传递记录；字段的就绪度标签随字段一同传递

HC-02：codebase-analyzer → technical-designer

• 对于 ADR 批次，原样传递已确认的 decision_points，并将其对应的 decisionMaterials.candidateDecisionPoints 对象原样复制为 decision_materials。
• 对于 Design Doc，将 codebase-analyzer 的 JSON 原样传递为 codebase_analysis；已接受的制品路径和未更改的证据可使 Design Doc 追溯到已审查的来源，而非编排器撰写的影子解读。按如下方式使用这些字段：
• 下游必需用途：
  • focusAreas → Fact Disposition Table 的规范处置目标列表
  • simplifications、decisionMaterials.reuse 和 invalidations → 在证据和条件适用时缩小实现范围并排除无效方案
  • decisionMaterials.candidateDecisionPoints → 编排器先依据主导来源、simplifications、reuse 和 invalidations 对其进行解析，然后应用 ADR Choice 和 Durability 筛选
  • decisionMaterials.verification → 必需的证明边界
  • dataModel、dataTransformationPipelines、qualityAssurance → Existing Codebase Analysis / Verification Strategy / Quality Assurance 章节

HC-03：technical-designer → code-verifier

• 传递 Design Doc 路径，并设置 doc_type: design-doc。

HC-03b：已应用的设计证据发现 → technical-designer

• 以全新的 update 调用调用负责的设计 Agent，传递现有 Design Doc 路径，并逐字复制完整的 correction_findings 对象，仅添加其 apply 处置项。
• 现有制品包含已批准的需求、已接受的决策、先前的证据和不受影响的设计上下文。交接内容仅限于制品路径和未更改的已应用发现。
• 设计 Agent 应用由审查触发的自我验证门槛，更新制品或返回准确的未解决前提，然后编排器重新运行最初的验证器或审查者。

HC-04：code-verifier + codebase-analyzer → document-reviewer

• 保持 verifier 发现的差异不变，以便修正和审查始终可追溯至观察到的证据，而非编排器编写的设计指令。
• 应用 Review Resolution，并在每次应用修正后重新运行验证，将上一次完整的 verifier 结果、处置结果以及修正差异或路径作为 prior_feedback 传入。按照 Review Resolution 参考文档中的定义，构造单个 verification_evidence 对象。
• 传入以下确切键：review_context: creation、verification_evidence、之前提供给设计者的相同 codebase_analysis JSON、可选的 ui_analysis、作为 requirements_verbatim 的原始用户需求，以及在所属设计者调用中提供的相同 confirmed_requirement_context。
• 在所有剩余 verifier 条目都已得到明确处置后进行转交。审查者负责验证最终设计、Fact Disposition 覆盖情况和有效需求；编排器仍负责 verifier 处置的归属。

HC-05：code-verifier → 下一层 technical-designer（仅限 fullstack）

• 仅适用于 references/monorepo-flow.md 中定义的多层 fullstack 流程
• 传入：上一层 Design Doc 路径和 prior_layer_verification
• 将 discrepancies[] 视为需要处理或上报的已知问题。凡是 verifier 输出中未提及的声明，一律视为未经验证。

technical-designer → work-planner

传入 Design Doc 路径。work-planner 将适用章节和 AC 映射为实现任务。未覆盖的已选义务属于需要纠正的规划遗漏；Work Plan 不得将覆盖缺失或设计内容缺失转变为需要用户确认的事项。

HC-06：acceptance-test-generator → work-planner

• 调用 acceptance-test-generator 时，传入适用的 Design Doc 路径列表 design_docs、可选的 ui_spec，以及设计阶段使用的相同 confirmed_requirement_context。
• 如果返回 value_input_required，则针对所列出的每项缺失事实询问一次，将答案原样保留为 test_value_context，然后重新调用。生成器会应用提供的事实，将所有剩余值保留为 unknown，根据可用的需求和代码仓库证据进行选择，并继续执行直至正常完成。
• 验证每个非 null 的 generatedFiles.<lane> 路径确实存在。如果某个 lane 为 null，则根据 Design Doc 确认没有已接受的证明义务要求该边界；若有未覆盖的义务，则将其退回生成器完成。
• 仅将已存在的生成路径作为 testSkeletons 传给 work-planner；每个骨架都应包含放置所需的 lane 和边界信息。
• 将意外的集成生成失败作为未完成的生成器工作处理。经验证的 null E2E lane 属于已完成状态。

参考文档

• references/monorepo-flow.md：Fullstack（monorepo）编排流程
• references/review-resolution.md：发现项裁定与修正循环约定
• references/lite-mode.md：用户选择省略中间验证调用