loop-architect

Loop Architect

面向 Kiro CLI 的循环设计教练。通过访谈了解你的需求，依据内置的最佳实践评分标准评审设计，接入跨模型评审者或裁判，以 ASCII 流程预览展示循环，并生成可移植的产物，可立即通过 /goal 运行，也可稍后使用 Python 运行器运行。

基于 Kevin Simback 在 MIT License 下发布的 Looper。 由 ft.ia.br 为 Kiro CLI 改编。

为什么要有它

Kiro CLI 提供 /goal（带自我验证功能的自主循环）和子 Agent（带评审循环的并行流水线）。它们负责执行循环。Loop Architect 则帮助你设计值得执行的循环——包含经过指导的目标、类型化验证、跨模型关卡和明确的终止保护措施。

	/goal	子 Agent 流水线	Loop Architect
阶段	执行	执行	设计（飞行前）
指导你的目标	否	否	是
类型化验证	否	否	是（程序化／裁判／人工）
评审模型	同一模型	可配置	默认使用不同模型
可移植产物	否	否	loop.yaml + 已解析的规范
运行循环	是	是	是，通过移交运行

工作流

1. 根据用户输入解析目标路径。默认值：./loop-architect-output。如果目标路径中已有 loop.yaml，则视为编辑／恢复。

2. 仅在进入相应阶段时加载相关评分标准：

   • 目标阶段：references/goal-rubric.md
   • 验证阶段：references/verification-rubric.md
   • 评审团阶段：references/council-rubric.md
   • 控制阶段：references/control-rubric.md
   • 模型检测：references/model-detection.md

3. 分七个阶段进行访谈：目标、验证、宿主模型、评审团、关卡／控制、确认流程预览、生成／运行选项。在控制阶段，讨论执行边界、隔离、无进展信号、状态和运行日志记录。

4. 接受每个阶段的内容前先进行评审。优先提供具体替代方案，而不是含糊的警告。推动不够明确的目标补充结果、范围、上下文和完成状态。推动不够充分的验证优先采用程序化检查，其次是裁判评分标准，最后是人工签核。

5. 明确区分评审者和裁判的职责。评审者撰写意见，裁判返回结构化裁定。revise_until_clean 必须将某个裁判成员或 human 指定为 verdict_source。

6. 要求设置多种终止保护措施：max_iterations、每个关卡的修订次数上限、无进展停止条件，以及预算上限或明确的人工停止点。

7. 在选择任何跨供应商评审团成员之前，说明哪些上下文会离开用户的设备、由哪个 CLI 接收、适用哪些脱敏 glob，以及两种执行路径都需要在首次发送前征得同意。

8. 显示 ASCII 流程预览，并在最终生成前征求确认。

9. 在目标路径中生成以下文件：

   • loop.yaml
   • loop.resolved.json
   • LOOP.md
   • RUN_IN_SESSION.md
   • run-loop.py
   • loop-workspace/
   • README.md

10. 写入 loop.yaml 后，进行编译：

    python3 ~/.kiro/skills/loop-architect/scripts/looper.py compile \
      <target>/loop.yaml \
      --out <target>/loop.resolved.json \
      --render <target>/LOOP.md \
      --session-prompt <target>/RUN_IN_SESSION.md
    

11. 询问用户是否要立即运行循环。如果是：

    • 简易路径：直接按照 RUN_IN_SESSION.md 执行，或根据 definition_of_done 提供一行 /goal 命令建议。
    • 子 Agent 路径：如果评审团使用的模型具备 review_loop 能力，则可提议通过具有原生评审循环的子 Agent 流水线执行。
    • 外部路径：说明可使用 run-loop.py 在稍后或当前会话之外运行。

执行路径

路径 1：/goal（最简单）

当循环流程直接明了，且宿主是当前 Kiro 会话时：

/goal --max 12 <definition_of_done from loop.yaml>

这会使用 Kiro 原生的自我验证循环。没有跨模型审查，但速度快且无需配置。

路径 2：子 Agent 审查流水线（推荐）

当需要跨模型审查员，且宿主具备 subagent 能力时：

Implement the loop following RUN_IN_SESSION.md. Use a subagent as reviewer
with trigger "NEEDS_CHANGES" and max 3 iterations per gate.

这会利用 Kiro 原生的 loop_to 机制来处理计划和交付关卡。

路径 3：外部 Python 运行器（高级）

python3 ./loop-architect-output/run-loop.py

适用于定时运行、CI 集成，或需要严格控制预算的场景。

文件规则

• 对所有模型调用，使用 argv 数组，绝不使用 shell 命令字符串。
• 不要将 API 密钥、令牌或凭据写入任何生成的文件。
• 默认脱敏匹配模式：.env、.env.*、secrets/**、**/*.key。
• 保持 loop.yaml 易于阅读并附有注释。
• 将 RUN_IN_SESSION.md 作为默认／简易的执行交接文档。
• 除非用户要求编辑，否则原样复制 templates/run-loop.py。

辅助脚本

检测模型 CLI：

python3 ~/.kiro/skills/loop-architect/scripts/looper.py detect-models --write

注册自定义 CLI：

python3 ~/.kiro/skills/loop-architect/scripts/looper.py register-model <id> \
  --invoke kiro-cli chat --trust-all-tools -p --authed

编译并渲染：

python3 ~/.kiro/skills/loop-architect/scripts/looper.py compile <target>/loop.yaml \
  --out <target>/loop.resolved.json \
  --render <target>/LOOP.md \
  --session-prompt <target>/RUN_IN_SESSION.md

确认流程预览

+--------------------------------+
| 1. Goal + context              |
|    read sources                |
+--------------------------------+
              |
              v
+--------------------------------+
| 2. Draft plan.md               |
|    state -> state.json         |
+--------------------------------+
              |
              v
+--------------------------------+
| 3. Plan gate                   |
|    verdict: reviewer-1         |
+--------------------------------+
  | needs work -> revise <= 3 -> step 2
  | pass
              v
+--------------------------------+
| 4. Write delivery-N.md         |
|    log -> run-log.md           |
+--------------------------------+
              |
              v
+--------------------------------+
| 5. Delivery gate               |
|    verdict: reviewer-1         |
+--------------------------------+
  | needs work -> revise <= 3 -> step 4
  | pass
              v
+--------------------------------+
| 6. Final output                |
|    all gates clean             |
+--------------------------------+

Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0

生成检查清单

• 目标有明确的结果、范围边界、上下文来源和完成状态。
• 验证标准的类型为 programmatic、judge 或 human。
• 至少有一项标准不完全依赖主观感受。
• 每个 revise_until_clean 关卡都有有效的 verdict_source。
• 每次外部调用都是带有超时设置的 argv 数组。
• 跨供应商的外发数据范围明确、经过脱敏，并需征得同意。
• loop_control 设置了迭代次数、修订次数、无进展次数和预算上限。
• 明确说明执行边界和隔离方式。
• 可观测性部分列出 run-log.md 和 state.json 的路径。
• 编译后的产物（loop.resolved.json、LOOP.md、RUN_IN_SESSION.md） 在交接前通过验证。