factory-architect

factory-architect

在工厂运行中——请先阅读

当设置了 ADLC_RUN_ID 时，工作流引擎会在无人值守的情况下运行此步骤，之后会有一个关卡。请严格执行以下操作：

1. 开始： bash {REPO_ROOT}/.agents/skills/factory-mission/scripts/bash/run-branch.sh —— 在 Windows 上使用 pwsh {REPO_ROOT}/.agents/skills/factory-mission/scripts/powershell/run-branch.ps1（每个辅助脚本在 scripts/powershell/ 下都有对应的 PowerShell 版本；在 Windows 上请使用它，而不是 bash 版本）
2. 运行 DAG 为该问题解析出的生命周期步骤。每个会更改文件的步骤完成后：使用 commit-step.sh，并传入该步骤写入、移动或删除的所有路径。
3. 返回前，务必： 运行 open-mr.sh，然后在 ADLC_STEP_OUTPUT 中写入一行 conclusion。无论结果如何都要这样做，即使没有任何更改。
4. 绝不要请求批准或等待答复。此步骤之后引擎会设置关卡以供批准；在此处提问会导致步骤结束且没有任何内容发布。

只有此编排器会提交、推送并创建 MR，且只能通过这些辅助脚本执行；architect-* 技能绝不执行这些操作。详情请参阅：运行分支、步骤提交与草稿 MR。

---

此技能的作用

factory-architect 编排架构决策生命周期。它协调各个架构相关技能（architect-init、architect-specify、architect-clarify、architect-implement、architect-analyze），以维护项目根目录下统一的 AD.md。

它作为Kind-A DAG 编排器运行，遵循 factory-mission/references/executor.md 中的共享执行器引擎契约。

---

何时使用

• 你想端到端地搭建、完善或分析项目的系统级设计与决策（ADR）。
• 你想验证架构观点是否符合 Rozanski & Woods 方法论。

不应使用的情况：

• 定义产品需求（请改用 factory-product）。
• 执行功能级软件开发（请改用 factory-mission）。

---

生命周期 DAG 与步骤解析

factory-architect 实现了一个固定的命名技能 DAG（fixed 步骤解析）：

绿地项目路线（空项目时的默认路线）

1. specify（generate 阶段）→ 调用 architect-specify，协作整理 ADR 草案并存入 .adlc/drafts/adr/。
2. clarify⭐（clarify 阶段）→ 调用 architect-clarify，执行交互式质量检查，并将 ADR 标记为 Accepted（人工签核关卡）。
3. implement（build 阶段）→ 调用 architect-implement，将已接受的 ADR 汇编到 AD.md（按子系统划分），并将其移至 docs/adlc/memory/adr/。
4. analyze（analyze 阶段）→ 调用 architect-analyze，验证 AD/ADR 的一致性，并输出按严重程度排序的报告。

存量项目路线（代码已存在但没有 ADR 时的默认路线）

1. init（generate 阶段）→ 调用 architect-init，从现有架构中逆向工程生成 ADR 草案。
2. clarify⭐ → implement → analyze（与绿地项目路线相同）。

刷新路线（AD.md 和记忆库 ADR 均已存在时的默认路线）

1. analyze（analyze 阶段）→ 首先运行 architect-analyze，以检测偏差。
2. clarify⭐ → implement → analyze（偏差修正周期）。

---

共享执行器覆盖项

factory-architect 按如下方式覆盖共享执行器引擎原语：

1. 发布目标：固定为 local。输出写入 docs/adlc/memory/adr/ 和 docs/adlc/architect/AD.md。如果集成了跟踪器，还会发布一条 tracker 完成摘要评论。
2. 输出类型：各步骤使用以下 output_type 赋值：
   • specify/init → draft（ADR 草稿保留在 .adlc/drafts/adr/，不发布到评论总线）
   • clarify⭐ → decision（已接受/已拒绝的 ADR 列表发布到评论总线）
   • implement → artifact-ref（发布 AD.md 路径引用，内容保留在磁盘上）
   • analyze → findings（按严重性排序的一致性报告发布到评论总线）
3. 修正循环：如果 analyze 返回 CRITICAL 或 HIGH 一致性错误，执行器会路由回 clarify，并在 reads_from 中添加 analyze 标记。clarify 从 PR/MR/issue 评论总线（或本地回退来源）读取调查结果。此循环受 max_corrections 限制（默认值为 2）；如果超出限制，编排器会暂停以供人工审核。
4. 监督默认值：hybrid。在 clarify⭐（用于 ADR 审批）和最终的 AD.md 审核阶段，强制设置人工审批关卡。
5. 预检：开始 Phase 0 前，验证工作区中已安装 architect-* 生命周期技能。

---

运行分支、分步提交和草稿 MR

需要： factory-mission 技能（提供运行辅助脚本）：adlc-cli skills add tikalk/adlc-team-skills --skill factory-mission

在工厂运行中（由工作流引擎设置 ADLC_RUN_ID），由此编排器且仅由此编排器提交并推送运行分支、创建草稿 MR；绝不由 architect-* 生命周期技能执行。始终通过以下三个辅助脚本完成：

1. 第一步之前： bash {REPO_ROOT}/.agents/skills/factory-mission/scripts/bash/run-branch.sh — 在项目根目录检出 factory/intent/<repo>-<iid>（来自 ADLC_ISSUE_REF），复用现有分支或从 origin 继续。此分支与其他意图通道以及重新调度的运行共用。
2. 每一步之后（specify/init、clarify、implement、analyze 修复）： bash {REPO_ROOT}/.agents/skills/factory-mission/scripts/bash/commit-step.sh --orchestrator factory-architect --step <step> --output-type <draft|decision|artifact-ref|findings> --summary "<one line, no issue text>" --records <IDs> -- <paths the step wrote> 传入该步骤写入、移动或删除的每个路径（也包括已提升草稿的旧路径；辅助脚本也会提交允许列表内的删除），且只传入生命周期写入允许列表中的路径（.adlc/drafts/adr/、docs/adlc/memory/adr/、docs/adlc/architect/AD.md、docs/adlc/architect/views/）。脚本会输出 sha: <sha> 或 sha: none；将该 sha 写入步骤的总线标记（总线传递的是指针，而非内容）。绝不要暂存 .adlc/workflows/**。
3. 返回之前，始终执行： bash {REPO_ROOT}/.agents/skills/factory-mission/scripts/bash/open-mr.sh — 仅推送运行分支，查找或创建一个草稿 MR（使用合并提交，不 squash；里程碑和受派人按 MR 归属决策设置），并将 mr_url 写入 ADLC_STEP_OUTPUT，供引擎的门禁关联（context.link）。无论结果如何，都要调用此脚本——即使没有任何提交（sha: none，仅执行 analyze）：如果运行分支上没有提交，脚本就不会创建 MR，门禁会显示没有可供审查的内容。同时，在同一个 JSON 对象中写入一行 conclusion（遵循门禁的意图结论规则）。 在工厂运行中，此步骤之后引擎的门禁就是审批：不要自行请求审批（不要问“是否批准 implement？”）——完成议题所需的步骤，运行 open-mr.sh，说明结论并返回。

在工厂运行之外，除非用户选择启用（在 .adlc/init-options.json 中设置 adlc.commit_steps: true，或向此技能传入 --commit 并由你转交给 commit-step.sh），否则这些辅助脚本不执行任何操作；没有 ADLC_RUN_ID 时，run-branch.sh 和 open-mr.sh 绝不会执行操作。辅助脚本非零退出（拒绝路径、缺少提交者身份、跟踪器范围问题）会中止运行——请报告错误，不要绕过。