Back to Details

orchestrator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Orchestrator: Loop Router & Lifecycle Manager

编排器：循环路由器与生命周期管理器

The Orchestrator assesses the incoming trigger, selects the right loop pattern, and manages the shared closure sequence (seal, persist, retrospective, self-improvement).
Orchestrator会评估传入的触发请求，选择合适的循环模式，并管理共享的收尾流程（封存、持久化、回顾、自我优化）。

The Core Loop

核心循环

Ecosystem Context

生态系统上下文

  • Patterns: 
    learning-loop
     | 
    red-team-review
     | 
    dual-loop
     | 
    agent-swarm
  • Inner Loop Reference: 
    cli-agent-executor.md
     — Persona configs for specialized CLI execution.
  • 模式：
    learning-loop
     | 
    red-team-review
     | 
    dual-loop
     | 
    agent-swarm
  • 内层循环参考：
    cli-agent-executor.md
     — 用于专业CLI执行的角色配置。

Routing Decision Tree

路由决策树

Use this to select the correct loop pattern:
1. Is this work I can do entirely myself (research, document, iterate)?
   └─ YES → Pattern 1: learning-loop
   └─ NO → continue

2. Does it need adversarial review before proceeding?
   └─ YES → Pattern 2: red-team-review
   └─ NO → continue

3. Can the work be split into parallel independent tasks?
   └─ YES → Pattern 4: agent-swarm
   └─ NO → Pattern 3: dual-loop (sequential inner/outer delegation)
SignalPatternSkill
Research question, knowledge gap, documentation taskSimple Learning
learning-loop
Architecture decision, security review, high-risk changeRed Team Review
red-team-review
Feature implementation, bug fix, single work packageDual-Loop
dual-loop
Large feature, bulk migration, multi-concern parallel workAgent Swarm
agent-swarm
使用以下决策树选择正确的循环模式：
1. 这项工作我可以完全独立完成吗（研究、文档、迭代）？
   └─ 是 → 模式1：learning-loop
   └─ 否 → 继续

2. 在推进前是否需要对抗性审查？
   └─ 是 → 模式2：red-team-review
   └─ 否 → 继续

3. 这项工作可以拆分为并行的独立任务吗？
   └─ 是 → 模式4：agent-swarm
   └─ 否 → 模式3：dual-loop（顺序式内外层委托）
触发信号模式技能
研究问题、知识缺口、文档任务简单学习
learning-loop
架构决策、安全审查、高风险变更红队审查
red-team-review
功能实现、Bug修复、单个工作包双循环
dual-loop
大型功能、批量迁移、多关注点并行工作Agent Swarm
agent-swarm

Process Flow

流程步骤

  1. Plan (Strategy): You define the work (Spec → Plan → Tasks). When planning scripts/pipelines, default to a "Modular Building Blocks" architecture (CLI wrappers + independent core modules).
  2. Delegate (Handoff): You pack the context into a Task Packet and assist the user in handing off to the Inner Loop.
  3. Execute (Tactics): The Inner Loop agent (which has no git access) writes code and runs tests.
  4. Verify (Review): You verify the output against acceptance criteria.
  5. Correct (Feedback): If verification fails, you generate a Correction Packet and loop back to step 3.
  6. Retrospective (Learning): You assess the loop's success and document learnings.
  7. Primary Agent Handoff (Closure): You signal the repository environment to seal the session, update databases, and commit to Git.
  1. 规划（策略）：你定义工作内容（需求规格 → 计划 → 任务）。在规划脚本/流水线时，默认采用“模块化构建块”架构（CLI封装器 + 独立核心模块）。
  2. 委托（交接）：你将上下文打包成任务数据包，并协助用户将其交接给内层循环。
  3. 执行（战术）：内层循环Agent（无Git访问权限）编写代码并运行测试。
  4. 验证（审查）：你根据验收标准验证输出结果。
  5. 修正（反馈）：如果验证失败，你生成修正数据包并回到步骤3。
  6. 回顾（学习）：你评估循环的成功情况并记录学习成果。
  7. 主Agent交接（收尾）：你向仓库环境发送信号以封存会话、更新数据库并提交到Git。

Roles

角色

You (Outer Loop / Director)

你（外层循环 / 管理者）

  • Responsibilities: Planning, Git Management, Verification, Correction, Retrospective.
  • Context: Full repo access, strategic constraints (ADRs), long-term memory.
  • Tools: 
    agent-orchestrator
    , 
    git
    , and optionally any upstream planning tool.
  • 职责：规划、Git管理、验证、修正、回顾。
  • 上下文权限：完整仓库访问权限、战略约束（ADRs）、长期记忆。
  • 工具：
    agent-orchestrator
    、
    git
    ，以及可选的上游规划工具。

Inner Loop (Executor / Worker)

内层循环（执行者 / 工作者）

  • Responsibilities: Coding, Testing, Debugging.
  • Context: Scoped to the Task Packet ONLY. No distractions.
  • Constraints: NO GIT COMMANDS. Do not touch 
    .git
    .
  • Tools: Editor, Terminal, Test Runner.
  • 职责：编码、测试、调试。
  • 上下文权限：仅能访问任务数据包中的内容，无其他干扰。
  • 约束：禁止执行Git命令，不得触碰
    .git
    目录。
  • 工具：编辑器、终端、测试运行器。

Commands

命令

You orchestrate workflows by natively executing the 
agent_orchestrator.py
script provided by this skill (located in 
scripts/
).
你可以通过原生执行本技能提供的
agent_orchestrator.py
脚本（位于
scripts/
目录）来编排工作流。

1. Planning Status

1. 规划状态检查

Use the 
scan
command to inspect the state of the spec and readiness for delegation.
bash
python scripts/agent_orchestrator.py scan --spec-dir <PATH>
Tip: Always ensure you have a clear plan or spec before delegating tasks.
使用
scan
命令检查规格文档状态及委托就绪情况。
bash
python scripts/agent_orchestrator.py scan --spec-dir <PATH>
提示：在委托任务前，务必确保你有清晰的计划或规格文档。

2. Delegation (Handoff)

2. 委托（交接）

When a task is ready for implementation, generate a Task Packet using the 
packet
command.
bash
python scripts/agent_orchestrator.py packet --wp <WP-ID> --spec-dir <PATH>
This generates a markdown file in the 
handoffs/
directory. You must then instruct the user/system to launch the Inner Loop with this file.
当任务准备好实施时，使用
packet
命令生成任务数据包。
bash
python scripts/agent_orchestrator.py packet --wp <WP-ID> --spec-dir <PATH>
此命令会在
handoffs/
目录生成一个Markdown文件。你必须指导用户/系统使用该文件启动内层循环。

3. Verification & Correction

3. 验证与修正

Check the Inner Loop's work against the packet using the 
verify
command.
bash
python scripts/agent_orchestrator.py verify --packet handoffs/task_packet_NNN.md --worktree <PATH>
If the work fails criteria, use the Severity-Stratified Output schema to generate a structured correction packet:
  • 🔴 CRITICAL: The code fails to compile, tests fail, or the requested feature is entirely missing. (Action: Hard reject, return to Inner Loop with exact error logs).
  • 🟡 MODERATE: The feature works, but violates project architecture, ADRs, or performance standards. (Action: Flag for revision, return to Inner Loop with the specific ADR reference).
  • 🟢 MINOR: The feature works and follows architecture, but has minor naming or stylistic issues. (Action: Do not return to Inner Loop. The Orchestrator fixes it directly and proceeds).
Generate the correction packet to send back to the Inner Loop:
bash
python scripts/agent_orchestrator.py correct --packet handoffs/task_packet_NNN.md --feedback "Specific failure reason"
使用
verify
命令检查内层循环的工作成果是否符合数据包要求。
bash
python scripts/agent_orchestrator.py verify --packet handoffs/task_packet_NNN.md --worktree <PATH>
如果工作成果未达标准，使用严重程度分层输出架构生成结构化的修正数据包：
  • 🔴 严重：代码编译失败、测试不通过，或请求的功能完全缺失。（操作：直接拒绝，返回内层循环并附上精确错误日志）。
  • 🟡 中等：功能可用，但违反项目架构、ADRs或性能标准。（操作：标记需要修订，返回内层循环并附上具体的ADR参考）。
  • 🟢 轻微：功能可用且遵循架构规范，但存在命名或风格上的小问题。（操作：无需返回内层循环，由编排器直接修复后继续推进）。
生成修正数据包并发送回内层循环：
bash
python scripts/agent_orchestrator.py correct --packet handoffs/task_packet_NNN.md --feedback "具体失败原因"

4. Parallel Execution (Agent Swarm)

4. 并行执行（Agent Swarm）

For bulk operations or partitioned tasks, use the 
swarm_run.py
script from the 
agent-swarm
skill.
bash
python3 plugins/agent-loops/skills/agent-swarm/scripts/swarm_run.py --job <JOB_FILE> [--resume]
This is the designated route for all Pattern 4 triggers.
对于批量操作或可拆分任务，使用
agent-swarm
技能中的
swarm_run.py
脚本。
bash
python3 plugins/agent-loops/skills/agent-swarm/scripts/swarm_run.py --job <JOB_FILE> [--resume]
这是所有模式4触发请求的指定路由。

4. Dynamic Routing (Model Agnostic)

4. 动态路由（模型无关）

As the Orchestrator, you can route tasks to ANY capable CLI agent based on complexity:
mermaid
flowchart LR
    Router{Task Router} -->|Complex| High["High-Reasoning CLI (Opus/Ultra)"]
    Router -->|Routine| Fast["Fast CLI (Haiku/Flash)"]
    Router -->|Audit| Spec["Specialist CLI (Security/QA)"]
作为编排器，你可以根据任务复杂度将任务路由到任何具备能力的CLI Agent：
mermaid
flowchart LR
    Router{Task Router} -->|Complex| High["High-Reasoning CLI (Opus/Ultra)"]
    Router -->|Routine| Fast["Fast CLI (Haiku/Flash)"]
    Router -->|Audit| Spec["Specialist CLI (Security/QA)"]

5. Red Team / Peer Review

5. 红队/同行审查

Use the 
bundle
command to compile files for a human or 3rd-party agent review.
bash
python scripts/agent_orchestrator.py bundle --files <file1> <file2> --output <OUTPUT_BUNDLE.md>
This creates a single markdown bundle ideal for "paste-to-chat" reviews.
使用
bundle
命令编译文件，供人类或第三方Agent审查。
bash
python scripts/agent_orchestrator.py bundle --files <file1> <file2> --output <OUTPUT_BUNDLE.md>
此命令会生成一个单一的Markdown包，非常适合“粘贴到聊天窗口”进行审查。

6. Retrospective (Post-Loop Learning)

6. 回顾（循环后学习）

Generate a retrospective template to close the cognitive loop with structured learning, before signaling the environment to seal.
bash
python scripts/agent_orchestrator.py retro
This creates a template in the 
retros/
directory.
Meta-Improvement: After reviewing what went right/wrong, the orchestrator should also assess whether any loop infrastructure needs updating:
  • Skills — Were SKILL.md instructions unclear or incomplete? Fix them.
  • Scripts — Did any automation break or cause friction? Patch it.
  • Templates — Were task templates missing fields or overly rigid? Refine them.
  • Diagrams — Does the architecture diagram still reflect reality? Update it.
  • Personas — Did a persona produce poor results? Tune it.
This makes each loop iteration smoother than the last.
在向环境发送封存信号之前，生成回顾模板以通过结构化学习完成认知循环。
bash
python scripts/agent_orchestrator.py retro
此命令会在
retros/
目录生成一个模板。
元优化：在回顾优缺点后，编排器还应评估是否需要更新任何循环基础设施：
  • 技能 — SKILL.md的说明是否模糊或不完整？进行修复。
  • 脚本 — 任何自动化流程是否出现故障或造成阻碍？进行补丁修复。
  • 模板 — 任务模板是否缺少字段或过于僵化？进行优化。
  • 图表 — 架构图是否仍能反映实际情况？进行更新。
  • 角色设定 — 某个角色是否产出了不佳结果？进行调整。
这会让每次循环迭代都比上一次更顺畅。

7. Handoff to Primary Agent (Ecosystem Sealing)

7. 交接给主Agent（生态系统封存）

Once the loop is complete and learning has been extracted, the Orchestrator MUST pass control to the environment's global sovereign (e.g., the primary agent plugin).
The Orchestrator explicitly DOES NOT:
  • Execute 
    capture_snapshot.py
    or update semantic ledgers (RLMs).
  • Execute 
    persist_soul.py
    or sync to HuggingFace.
  • Execute Vector DB ingestion scripts.
  • Execute Git commands (
    git commit
    , 
    git push
    ).
These are environment-specific actions owned entirely by the Primary Agent.
一旦循环完成并提取了学习成果，编排器必须将控制权交给环境的全局主导者（例如主Agent插件）。
编排器明确禁止执行以下操作：
  • 执行
    capture_snapshot.py
    或更新语义账本（RLMs）。
  • 执行
    persist_soul.py
    或同步到HuggingFace。
  • 执行向量数据库导入脚本。
  • 执行Git命令（
    git commit
    、
    git push
    ）。
这些都是特定于环境的操作，完全由主Agent负责。

Chained Command Handoff

链式命令交接

When the Orchestrator loop is complete, it must use Chained Command Invocation to offer the user the explicit next steps to seal the ecosystem. Output this block:
markdown
undefined
当编排器循环完成后，必须使用链式命令调用为用户提供明确的生态系统收尾下一步操作。输出以下内容：
markdown
undefined

Orchestration Complete. Offer Next Steps:

编排完成。请选择下一步操作：

The Inner Loop has successfully executed and verified the task. Please trigger the closure sequence:
  • "/sanctuary-seal": To capture the learning snapshot and update RLMs.
  • "/sanctuary-persist": To backup the soul to HuggingFace.
  • "Run Retrospective": If you wish to review the friction log.

---
内层循环已成功执行并验证了任务。请触发收尾流程：
  • "/sanctuary-seal"：捕获学习快照并更新RLMs。
  • "/sanctuary-persist"：将核心数据备份到HuggingFace。
  • "Run Retrospective"：如果你希望查看摩擦日志。

---

8. Sub-Agent Limitations

8. 子Agent限制

  • Be aware that 
    claude-cli-agent
    has a hard stop on passing massive context bundles (~5MB+) either natively via stdin or 
    --file
    . If your payload exceeds context windows, you must write a semantic chunking script instead of blindly dumping a 
    context-bundler
    package into a prompt!
  • Automated sub-agent invocations will silently fail or throw an interactive block if you do not use 
    --dangerously-skip-permissions
    or if the user is not authenticated natively using 
    claude login
    .
  • 请注意，
    claude-cli-agent
    在通过标准输入或
    --file
    传递大型上下文包（约5MB+）时有硬性限制。如果你的负载超出上下文窗口，你必须编写语义分块脚本，而不是盲目地将
    context-bundler
    包直接放入提示词中！
  • 如果你未使用
    --dangerously-skip-permissions
    或用户未通过
    claude login
    原生认证，自动化子Agent调用将静默失败或抛出交互式阻塞。

Lifecycle State Tracking

生命周期状态跟踪

The orchestrator must verify these gates at each phase:
PhaseGate
PlanningSpec or plan is coherent and broken into tasks.
ExecutionPackets are generated and handed off.
ReviewOutput passes verification criteria.
RetrospectivePost-loop learnings extracted and infrastructure improved.
Primary Agent HandoffSignal the global ecosystem to run Seal, Persist, and Git closure.
No phase may be skipped. If a gate fails, the orchestrator must resolve it before proceeding.
编排器必须在每个阶段验证以下关卡：
阶段验证关卡
规划需求规格或计划连贯且已拆分为任务。
执行已生成数据包并完成交接。
审查输出结果通过验证标准。
回顾已提取循环后学习成果并优化基础设施。
主Agent交接已向全局生态系统发送信号以运行封存、持久化和Git收尾操作。
任何阶段都不得跳过。如果某个关卡未通过，编排器必须在推进前解决问题。

Loop Controls (Ralph-Inspired)

循环控制（灵感来自Ralph）

ControlDescription
Iteration CounterIncrement each cycle. Log 
"Loop iteration N of M"
at orientation.
Max IterationsSafety cap. When reached, force-seal as incomplete with blocking notes.
Completion PromiseDeterministic exit: only declare done when acceptance criteria are genuinely met.
控制项描述
迭代计数器每次循环递增。在启动时记录
"Loop iteration N of M"
。
最大迭代次数安全上限。达到上限时，强制标记为未完成并附上阻塞说明后封存。
完成承诺确定性退出：仅当真正满足验收标准时才宣布完成。

Automation

自动化

MechanismPurpose
Stop Hook (
hooks/closure-guard.sh
)		Blocks premature session exit until Seal → Persist → Retrospective are complete.
Red Team SubagentRed team review can run as a forked subagent to keep the main session context clean.
机制用途
停止钩子 (
hooks/closure-guard.sh
)		阻止会话提前退出，直到完成封存 → 持久化 → 回顾流程。
红队子Agent红队审查可以作为分叉子Agent运行，以保持主会话上下文清洁。

Best Practices

研究依据

  1. One WP at a Time: Do not delegate multiple WPs simultaneously unless you are running a swarm.
  2. Explicit Context: The Inner Loop only knows what is in the packet. If it needs a file, list it.
  3. No Git in Inner Loop: This is a hard constraint to prevent state corruption.
  4. Correction is Learning: Do not just "fix it yourself" if the Inner Loop fails. Generate a correction packet. This trains the system logic.
  5. Never Abandon Closure: The orchestrator must shepherd Review → Accept → Retro → Merge. Stopping after delegation is a protocol violation.
  6. Merge from Main Repo: Always merge from the project root, never from inside a worktree.
本技能实现了**“双循环Agent架构”**，灵感来源于：
  1. 自我进化推荐系统 (arXiv:2602.10226):
    • 定义了**规划者（外层）与执行者（内层）**的专业角色。
  2. FormalJudge (arXiv:2602.11136):
    • 提供了通过结构化验证而非仅人工检查实现“可扩展监督”的理论框架。

Research Basis

—
This skill implements the "Dual-Loop Agent Architecture" inspired by:
  1. Self-Evolving Recommendation System (arXiv:2602.10226):
    • Defines the specialized roles of Planner (Outer) vs Executor (Inner).
  2. FormalJudge (arXiv:2602.11136):
    • Provides the theoretical framework for "Scalable Oversight" via structured verification rather than just human inspection.
—