Back to Details

dual-loop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dual-Loop (Inner/Outer Agent Delegation)

双循环（内环/外环Agent委派）

This skill defines the orchestration pattern for the Dual-Loop Agent Architecture. The Outer Loop (the directing agent) uses this protocol to organize work, delegate execution to an Inner Loop (the coding/tactical agent), and rigorously verify the results before merging.
This architecture is entirely framework-agnostic and can be utilized by any AI agent pairing (e.g., Antigravity directing Claude Code, or an OpenHands agent directing a specialized CLI sub-agent).
本Skill定义了双循环Agent架构的编排模式。Outer Loop（外环）（指挥Agent）通过本协议组织工作，将执行任务委派给Inner Loop（内环）（编码/战术Agent），并在合并前严格验证结果。
该架构完全与框架无关，可用于任意AI Agent配对（例如Antigravity指挥Claude Code，或OpenHands Agent指挥专用CLI子Agent）。

CRITICAL: Anti-Simulation Rules

关键：反模拟规则

YOU MUST ACTUALLY PERFORM THE VALIDATIONS LISTED BELOW. Describing what you "would do" or marking a step complete without actually doing the verification is a PROTOCOL VIOLATION.
你必须实际执行以下列出的验证操作。 描述你“会做什么”或未实际执行验证就标记步骤完成属于协议违规。

Architecture Overview

架构概述

mermaid
flowchart LR
    subgraph Outer["Outer Loop (Strategy & Protocol)"]
        Scout[Scout & Plan] --> Spec[Define Tasks]
        Spec --> Packet[Generate Strategy Packet]
        Verify[Verify Result] -->|Pass| Commit[Seal & Commit]
        Verify -->|Fail| Correct[Generate Correction Packet]
    end

    subgraph Inner["Inner Loop (Execution)"]
        Receive[Read Packet] --> Execute[Write Code & Run Tests]
        Execute -->|No Git| Done[Signal Done]
    end

    Packet -->|Handoff| Receive
    Done -->|Completion| Verify
    Correct -->|Delta Fix| Receive
Reference: Architecture Diagram
mermaid
flowchart LR
    subgraph Outer["Outer Loop (Strategy & Protocol)"]
        Scout[Scout & Plan] --> Spec[Define Tasks]
        Spec --> Packet[Generate Strategy Packet]
        Verify[Verify Result] -->|Pass| Commit[Seal & Commit]
        Verify -->|Fail| Correct[Generate Correction Packet]
    end

    subgraph Inner["Inner Loop (Execution)"]
        Receive[Read Packet] --> Execute[Write Code & Run Tests]
        Execute -->|No Git| Done[Signal Done]
    end

    Packet -->|Handoff| Receive
    Done -->|Completion| Verify
    Correct -->|Delta Fix| Receive
参考：架构图

The Workflow Loop

工作流循环

Step 1: The Plan (Outer Loop)

步骤1：规划（外环）

  1. Orientation: The Outer Loop agent reads the project requirements or goals.
  2. Decomposition: Break the goal down into distinct Work Packages (WPs) or sub-tasks.
  3. Verification: Confirm that the tasks are atomic, testable, and do not overlap.
  1. 定位：外环Agent读取项目需求或目标。
  2. 分解：将目标拆分为不同的工作包（WP）或子任务。
  3. 验证：确认任务具备原子性、可测试性且无重叠。

Step 2: Prepare Execution Environment

步骤2：准备执行环境

  1. Isolation: Ensure a safe workspace exists for the Inner Loop. Workspace creation (e.g., worktrees, branching, ephemeral containers) is strictly a delegated responsibility of the Orchestrator or external tooling. The Dual-Loop just receives the environment.
  2. Update State: Mark the current Work Package as "In Progress" in whatever task-tracking system the project uses.
  1. 隔离：确保内环拥有安全的工作空间。工作空间的创建（如git工作树、分支、临时容器）严格由编排器或外部工具负责。双循环模式仅在已提供的环境中运行。
  2. 更新状态：在项目使用的任务跟踪系统中将当前工作包标记为“进行中”。

Step 3: Generate Strategy Packet (Outer Loop)

步骤3：生成策略包（外环）

  1. Write a tightly scoped markdown document (the "Strategy Packet") specifically for the Inner Loop.
  2. Requirements for the Packet:
    • The exact goal.
    • A Pre-Execution Workflow Commitment Diagram (an ASCII box) mapping out the steps the Inner Loop must take.
    • Only the specific file paths the sub-agent needs to care about.
    • Strict "NO GIT" constraints (the Inner Loop must not commit).
    • If generating scripts/pipelines, instruct the Inner Loop to use the "Modular Building Blocks" architecture (split convenience CLI wrappers from core Python APIs).
    • Clear Acceptance Criteria.
  3. Save the packet (e.g., 
    handoffs/task_packet_001.md
    ).
  1. 为内环编写一份范围严格的Markdown文档（即“Strategy Packet（策略包）”）。
  2. 策略包要求：
    • 明确的目标。
    • 一份预执行工作流承诺图（ASCII框图），列出内环必须执行的步骤。
    • 仅包含子Agent需要关注的特定文件路径。
    • 严格的“禁止Git操作”约束（内环不得执行提交操作）。
    • 若生成脚本/流水线，需指示内环采用“模块化构建块”架构（将便捷CLI包装器与核心Python API分离）。
    • 清晰的验收标准。
  3. 保存策略包（例如：
    handoffs/task_packet_001.md
    ）。

Step 4: Hand-off (The Bridge)

步骤4：交接（桥梁环节）

The Outer Loop invokes the Inner Loop. Depending on the environment, this is either done by spawning a sub-process (e.g., 
claude "Read handoffs/task_packet_001.md"
), calling an API, or asking the Human User to switch terminals.
外环调用内环。根据环境不同，可通过启动子进程（例如：
claude "Read handoffs/task_packet_001.md"
）、调用API或请求用户切换终端来完成。

Step 5: Execute (Inner Loop)

步骤5：执行（内环）

The Inner Loop agent:
  1. Reads the packet.
  2. Writes the code.
  3. Runs the tests.
  4. Signals "Done" when the Acceptance Criteria are met (or if it gets fundamentally stuck).
Constraint: The Inner Loop MUST NOT run version control commands.
内环Agent需完成以下操作：
  1. 读取策略包。
  2. 编写代码。
  3. 运行测试。
  4. 当满足验收标准（或遇到无法解决的问题时），发送“完成”信号。
约束：内环不得执行版本控制命令。

Step 6: Verify (Outer Loop)

步骤6：验证（外环）

Once the Inner Loop signals completion, the Outer Loop must verify the results:
  1. Delta Check: Inspect the changes (e.g., via diff tools or system state checks) to see what the Inner Loop actually altered.
  2. Test Check: Run the test suite mechanically to ensure nothing broke.
  3. Lint Check: Validate the syntax.
内环发出完成信号后，外环必须验证结果：
  1. 差异检查：检查变更内容（例如通过diff工具或系统状态检查），确认内环实际修改的内容。
  2. 测试检查：自动运行测试套件，确保未引入故障。
  3. 语法检查：验证语法合规性。

On Verification PASS:

验证通过时：

  1. The Outer Loop accepts the changes.
  2. The task tracker is updated to "Done".
  1. 外环接受变更。
  2. 任务跟踪系统更新为“已完成”。

On Verification FAIL:

验证失败时：

  1. The Outer Loop generates a Correction Packet using the strict Severity-Stratified Output Schema:
    • 🔴 CRITICAL: The code fails to compile, tests fail, or the requested feature is entirely missing.
    • 🟡 MODERATE: The feature works, but violates project architecture, ADRs, or performance standards.
    • 🟢 MINOR: The feature works and follows architecture, but has minor naming or stylistic issues.
  2. The Outer Loop loops back to Step 4, handing the Correction Packet to the Inner Loop.
  1. 外环使用严格的严重程度分层输出 schema生成Correction Packet（修正包）：
    • 🔴 严重：代码编译失败、测试不通过，或请求的功能完全缺失。
    • 🟡 中等：功能可用，但违反项目架构、ADR或性能标准。
    • 🟢 轻微：功能可用且符合架构要求，但存在命名或风格上的小问题。
  2. 外环回到步骤4，将修正包交给内环。

Step 7: Completion & Handoff

步骤7：完成与交接

Once all Work Packages are verified, the Dual-Loop pattern is complete. The Outer Loop terminates and returns control to the global lifecycle manager (Orchestrator) for Retrospectives and ecosystem sealing.
所有工作包验证通过后，双循环模式执行完成。外环终止运行，并将控制权交还给全局生命周期管理器（编排器），以便进行回顾和生态系统收尾。

Task Lane Management

任务泳道管理

Throughout the process, the Outer Loop must maintain discipline over task states. If you are operating this loop, you must ensure you or the task tracker accurately reflects:
  1. Backlog -> Doing (When Strategy Packet is generated)
  2. Doing -> Review (When Inner Loop signals completion)
  3. Review -> Done (When Outer Loop verifies and commits)
  4. Review -> Doing (If verification fails and a Correction Packet is sent)
在整个过程中，外环必须严格管理任务状态。如果你负责运行此循环，必须确保你或任务跟踪系统准确反映以下状态转换：
  1. 待办 -> 进行中（生成策略包时）
  2. 进行中 -> 审核中（内环发出完成信号时）
  3. 审核中 -> 已完成（外环验证并提交时）
  4. 审核中 -> 进行中（验证失败并发送修正包时）

Workspace Isolation

工作空间隔离

Dual-Loop (Agent-Loops) does not manage workspaces. It receives an isolated directory or execution context from the Orchestrator and runs the loop inside it. Workspace creation (e.g., git worktrees, branches) is a delegated responsibility of the Orchestrator or the global system environment.
双循环（Agent循环）不管理工作空间。 它从编排器接收隔离的目录或执行上下文，并在其中运行循环。工作空间的创建（如git工作树、分支）由编排器或全局系统环境负责。

Fallback: In-Place Execution

Fallback：原地执行

If an isolated workspace cannot be provided:
  1. The Inner Loop codes directly in the main directory.
  2. The Outer Loop must log this lack of isolation in a friction log for the handoff to the Orchestrator.
  3. All other constraints (no system manipulation from Inner Loop out of scope, verification gate, correction packets) still apply.
若无法提供隔离工作空间：
  1. 内环直接在主目录中编码。
  2. 外环必须在摩擦日志中记录缺乏隔离的情况，以便交接给编排器。
  3. 所有其他约束（内环不得操作超出范围的系统、验证关卡、修正包）仍然适用。

Fundamental Constraints

核心约束

  • No Protocol Crossing: The Inner Loop manages tacticals (code compilation, tests). The Outer Loop manages strategy (git, architecture decisions, human interactions).
  • Isolation: Strategy Packets must be minimal. Do not send the Inner Loop thousands of lines of conversation history. Give it exactly what it needs to execute the specific Work Package.
  • 禁止跨协议操作：内环负责战术层面（代码编译、测试）。外环负责战略层面（git操作、架构决策、人机交互）。
  • 最小化原则：策略包必须精简。不得向内环发送数千行的对话历史。仅提供执行特定工作包所需的精准信息。