architect

用途

Architect 是 agent-toolkit 流水线中的架构阶段技能，定位为入口环节（entry ramp）与主干第一阶段（spine phase 1）。它适用于以下场景：启动一个新功能、设计一个新项目，或对现有代码库进行重大架构变更。其核心产出是一份可靠的 architecture.md，用于喂给后续的 specify 阶段；当变更类型为 epic 时，则负责将整体拆解为子变更清单（child change manifests）。

主要能力

产出 architecture.md，作为 specify 阶段的输入。
对 epic 类型进行分解，规划子变更及其依赖关系。
对偏离当前语言惯用模式的方案提出质疑；若 manifest.language 已设置，则加载 idioms 技能中匹配的语言包。
默认对现有代码采取“软”态度：既有模式不自动视为正确，若存在更好方案（即使需要更大重构）也会提出。
将重构作为一等、有成本、需批准的决策在架构阶段呈现，避免在实现阶段才发现重构。
仅就公共契约、安全策略、兼容性/迁移、firm 接缝、不可逆或高成本承诺、以及有意义的架构或运维权衡向用户提问；对本地、私有、可逆的惯用选择自动选定，不放入确认台账。
执行一次有界的对抗性有效性审查（AV-* 循环），并记录审查日志。

使用方式

技能自带辅助脚本，位于其自身的 scripts/ 目录（与 SKILL.md 一同安装）。需先设置 SKILL_DIR 为该技能的绝对路径，再从项目根目录运行脚本（脚本操作项目的 .changes/ 与 CONTEXT.md 文件）：

SKILL_DIR="<absolute path to this skill's directory>"

所有 node "$SKILL_DIR/scripts/..." 命令都依赖此设置。不要引用 packages/build/，该路径只存在于工具包的开发仓库中，安装后的技能里没有。

前置条件

显式种子（seed）：在 intake 之前，若用户明确提供了 architect-seed.md 或 reforge-seed.md 路径，先读取它，并将其视为待质疑的临时输入，而非已批准决策。若未显式提供种子，但项目根目录存在 architect-seed.md，需先询问是否适用再加载。
记录 intake 结果：在显式种子与必要的 intake 澄清完成之前，不要读取 manifest、CONTEXT.md、仓库引用，也不要扫描仓库。工作区建立后，立即依据 references/templates/change-brief.md.tmpl 将种子与 intake 上下文记录到 change-brief.md。
检查 .changes/active/ 中是否有活动变更。若有，加载 manifest.yaml；若无，创建：

node "$SKILL_DIR/scripts/change-new.mjs" --title "<title>" [--class feature|epic] [--language <lang>]

若 manifest 的 phase 不是 architect，或 architect 批准已为 approved，则告知用户并停止。
检查 manifest.class。若为 epic，走 Epic 分解路径；否则走标准路径。

Epic 路径（class: epic）

Epic 负责规划，其子项负责实现。Epic 运行 architect（本次会话）与 specify（下次会话）来确定整体形态与横切契约，epic 层面不做实现。specify 之后创建子 manifest，并对每个子项独立运行完整流水线。

Epic 流水线：architect（本次会话）→ specify → decompose（epic-split）→ decomposed，随后每个子项走 child architect → specify → plan → implement → archive-ready。

Epic 阶段包括：

检查已有 architecture.md：若存在，读取并向用户展示其中的子任务/子变更描述，确认是否仍代表正确的拆分；若不存在，继续。
上下文收集：运行 node "$SKILL_DIR/scripts/context-discover.mjs"，读取根 CONTEXT.md 及与 epic 范围相关的组件 CONTEXT.md，并将此前选定的种子作为临时上下文记录在 architecture.md 的 Context Gathered 下。
高层架构讨论：以简洁的编号批次与用户讨论整体形态，覆盖 epic 交付内容、整体接缝、firm 与 soft、横切关注点、惯用模式检查、范围内重构。维护架构确认台账，每个已解决项需有决策 ID、建议、用户明确回应与确认状态。
识别子变更：将 epic 拆为离散子变更，判断是否可独立交付、边界是否正确、是否依赖其他子项，并分配 class 与 language。以表格呈现建议拆分，但此时不创建子 manifest，而是记录在 architecture.md 的 Proposed Child Changes 部分。
起草 architecture.md：依据 references/templates/architecture.md.tmpl 撰写，包含标准章节、Proposed Child Changes、以及需在 specify 中解决的横切关注点。完整确认台账放在散文式决策之前。
有界对抗性有效性审查：对整个 epic 架构运行恰好一次 AV-* 循环，由新的批评者做一次广泛发现，将全部 blocker/major 发现合并为一批，一次性修复，再由新的验证者仅检查原始 ID，最多允许一次针对性修正/复验。
架构批准：展示确认台账，询问用户确认，然后运行：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval architect --approve

并告知用户下一步运行 specify。

标准路径（class: feature | bug | small）

上下文收集：发现与本次变更相关的 CONTEXT.md 文件，运行 node "$SKILL_DIR/scripts/context-discover.mjs"，读取根 CONTEXT.md、相关组件 CONTEXT.md、manifest.yaml，以及前置条件中选定的种子。若 manifest.parent 已设置（即 epic 的子项），加载父 epic 的 architecture.md、decisions.md 及本变更目录中的 architect-seed.md，不重新争论 epic 层面已做的决策。
分批架构确认：以简洁编号批次进行系统确认讨论，对每个用户拥有的重要架构主题，给出问题、建议、理由与有意义的替代方案，要求明确回应（接受、选择替代或给出决策）。缺失、含糊或模糊的回答保持未解决，绝不从沉默推断接受。仅在回答含糊、引入坏味道或与 idioms 包冲突时提出质疑。
起草 architecture.md：当所有用户拥有的重要项确认后，依据模板起草，完整确认台账放在散文式决策之前，精确标注接缝 ID、firmness 标签与重构。写入 .changes/active/<id>/architecture.md。
有界对抗性有效性审查：对完整草稿运行恰好一次 AV-* 循环，新的批评者做一次广泛发现，覆盖数据/状态、数据结构、接口/trait、错误、安全、可观测性、简洁性、可维护性与惯用模式。将发现合并为一批，每项有稳定 AV-NNN ID、严重度 blocker|major、类别、证据、具体影响与具体替代方案。一次性修复整批，再由新的验证者仅检查原始 ID。记录审查日志：

node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase architect --cycle architect-N
--role auditor --reviewer "<fresh label>" --verdict approved node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase architect --cycle architect-N
--role verifier --reviewer "<distinct fresh label>" --verdict approved

批准：展示确认台账、决策摘要、接缝与已批准重构，询问用户确认台账是否准确代表其选择，然后明确询问是否批准 architect 批准。批准后运行：