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)

Signal	Pattern	Skill
Research question, knowledge gap, documentation task	Simple Learning	`learning-loop`
Architecture decision, security review, high-risk change	Red Team Review	`red-team-review`
Feature implementation, bug fix, single work package	Dual-Loop	`dual-loop`
Large feature, bulk migration, multi-concern parallel work	Agent 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

流程步骤

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).
Delegate (Handoff): You pack the context into a Task Packet and assist the user in handing off to the Inner Loop.
Execute (Tactics): The Inner Loop agent (which has no git access) writes code and runs tests.
Verify (Review): You verify the output against acceptance criteria.
Correct (Feedback): If verification fails, you generate a Correction Packet and loop back to step 3.
Retrospective (Learning): You assess the loop's success and document learnings.
Primary Agent Handoff (Closure): You signal the repository environment to seal the session, update databases, and commit to Git.

规划（策略）：你定义工作内容（需求规格 → 计划 → 任务）。在规划脚本/流水线时，默认采用“模块化构建块”架构（CLI封装器 + 独立核心模块）。
委托（交接）：你将上下文打包成任务数据包，并协助用户将其交接给内层循环。
执行（战术）：内层循环Agent（无Git访问权限）编写代码并运行测试。
验证（审查）：你根据验收标准验证输出结果。
修正（反馈）：如果验证失败，你生成修正数据包并回到步骤3。
回顾（学习）：你评估循环的成功情况并记录学习成果。
主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:

Phase	Gate
Planning	Spec or plan is coherent and broken into tasks.
Execution	Packets are generated and handed off.
Review	Output passes verification criteria.
Retrospective	Post-loop learnings extracted and infrastructure improved.
Primary Agent Handoff	Signal 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）

Control	Description
Iteration Counter	Increment each cycle. Log `"Loop iteration N of M"` at orientation.
Max Iterations	Safety cap. When reached, force-seal as incomplete with blocking notes.
Completion Promise	Deterministic exit: only declare done when acceptance criteria are genuinely met.

控制项	描述
迭代计数器	每次循环递增。在启动时记录 `"Loop iteration N of M"` 。
最大迭代次数	安全上限。达到上限时，强制标记为未完成并附上阻塞说明后封存。
完成承诺	确定性退出：仅当真正满足验收标准时才宣布完成。

Automation

自动化

Mechanism	Purpose
Stop Hook ( `hooks/closure-guard.sh` )	Blocks premature session exit until Seal → Persist → Retrospective are complete.
Red Team Subagent	Red team review can run as a forked subagent to keep the main session context clean.

机制	用途
停止钩子 ( `hooks/closure-guard.sh` )	阻止会话提前退出，直到完成封存 → 持久化 → 回顾流程。
红队子Agent	红队审查可以作为分叉子Agent运行，以保持主会话上下文清洁。

Best Practices

研究依据

One WP at a Time: Do not delegate multiple WPs simultaneously unless you are running a swarm.
Explicit Context: The Inner Loop only knows what is in the packet. If it needs a file, list it.
No Git in Inner Loop: This is a hard constraint to prevent state corruption.
Correction is Learning: Do not just "fix it yourself" if the Inner Loop fails. Generate a correction packet. This trains the system logic.
Never Abandon Closure: The orchestrator must shepherd Review → Accept → Retro → Merge. Stopping after delegation is a protocol violation.
Merge from Main Repo: Always merge from the project root, never from inside a worktree.

本技能实现了**“双循环Agent架构”**，灵感来源于：

自我进化推荐系统 (arXiv:2602.10226):
- 定义了**规划者（外层）与执行者（内层）**的专业角色。
FormalJudge (arXiv:2602.11136):
- 提供了通过结构化验证而非仅人工检查实现“可扩展监督”的理论框架。

Research Basis

—

This skill implements the "Dual-Loop Agent Architecture" inspired by:

Self-Evolving Recommendation System (arXiv:2602.10226):
- Defines the specialized roles of Planner (Outer) vs Executor (Inner).
FormalJudge (arXiv:2602.11136):
- Provides the theoretical framework for "Scalable Oversight" via structured verification rather than just human inspection.

—