agentic-orchestration-control

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agentic Orchestration Control v3.0 — Control Plane + Token Efficiency

Agentic Orchestration Control v3.0 — 控制平面 + Token效率优化

Use this skill only in the root Codex session. Never instruct spawned subagents to invoke this or any other repo skill, and never instruct a spawned subagent to spawn more agents.

仅在根Codex会话中使用此技能。切勿指示生成的子代理调用此技能或任何其他仓库技能，也切勿指示生成的子代理生成更多Agent。

Step 0 — Runtime mode guard

步骤0 — 运行时模式防护

This skill is root-only. Before using it, confirm the current session is not a leaf

codex exec

verification job. If the prompt says

You are a subagent

verification subagent

Run exactly these commands

Do not edit files

, or

Return only a YAML Handoff Packet

, do not use this skill, do not spawn agents, and perform only the bounded leaf task.

For leaf

codex exec

jobs, prefer CLI hard overrides:

bash

codex exec --cd /path/to/repo --sandbox workspace-write \
  -c features.multi_agent=false \
  -c agents.max_depth=0 \
  -c agents.max_threads=1 \
  -c model_reasoning_effort=low \
  -c model_verbosity=low \
  -c model_reasoning_summary=none \
  'LEAF_EXEC_MODE. You are a verification leaf worker. Do not spawn agents. Run exactly the requested commands and return only the requested packet.'

Read

references/exec-leaf-mode.md

when diagnosing subagents that try to spawn other agents.

此技能仅适用于根会话。使用前，请确认当前会话并非叶节点

codex exec

验证任务。如果提示包含

You are a subagent

、

verification subagent

、

Run exactly these commands

、

Do not edit files

或

Return only a YAML Handoff Packet

内容，请不要使用此技能，不要生成Agent，仅执行限定的叶节点任务。

对于叶节点

codex exec

任务，优先使用CLI硬覆盖：

bash

codex exec --cd /path/to/repo --sandbox workspace-write \
  -c features.multi_agent=false \
  -c agents.max_depth=0 \
  -c agents.max_threads=1 \
  -c model_reasoning_effort=low \
  -c model_verbosity=low \
  -c model_reasoning_summary=none \
  'LEAF_EXEC_MODE. You are a verification leaf worker. Do not spawn agents. Run exactly the requested commands and return only the requested packet.'

当诊断试图生成其他Agent的子代理时，请阅读

references/exec-leaf-mode.md

。

Prime directive

核心指令

Act as a task compiler and control-plane operator, not a prompt broadcaster. Classify the work, choose the cheapest adequate reasoning tier, batch related actions, compile minimal Dispatch Packets, track state, and collect concise Handoff Packets.

扮演任务编译器与控制平面操作者，而非提示广播者。对工作进行分类，选择成本最低且足够的推理层级，批量处理相关操作，编译最小化调度包，跟踪状态，并收集简洁的交接包。

Hard constraints

硬性约束

Root-only skill: this skill is for the parent orchestrator. Subagents receive plain dispatch text, not skill names.
No one-agent-per-file fan-out: batch related files by user flow, module, package, or owner.
No xhigh by default: xhigh is reserved for hard ambiguity/high risk, not routine patches.
No redundant waves: if one worker can inspect, patch, and test a small change, use one worker.
No raw output broadcast: route only facts, blockers, file ownership, commands run, failures, and next actions.
Write workers must complete a loop: inspect → patch → targeted validation → Handoff Packet.
Read-heavy work can be parallel; write-heavy work should be serialized or batched carefully.
Leaf-worker boundary: only the root session may spawn agents. Spawned workers must not delegate; they return
```
ESCALATE_TO_PARENT
```
when they need another specialist.
State before spawn: for M/L/XL, create a run ledger and check it before spawning or respawning.
Plan gate before broad work: M/L/XL tasks need a dependency-aware plan and binary executable gate before implementation.

仅根会话可用技能：此技能供父编排器使用。子代理仅接收纯调度文本，不接收技能名称。
禁止“单文件单Agent”扩散：按用户流程、模块、包或所有者对相关文件进行批量处理。
默认不使用xhigh层级：xhigh仅用于高度模糊/高风险场景，不用于常规补丁。
禁止冗余任务波次：如果单个工作器可完成检查、补丁和测试等小型变更，仅使用一个工作器。
禁止原始输出广播：仅传递事实、阻塞点、文件所有权、已执行命令、失败信息和下一步操作。
写入型工作器必须完成闭环：检查 → 补丁 → 定向验证 → 交接包。
读密集型工作可并行；写密集型工作应序列化或谨慎批量处理。
叶节点工作器边界：仅根会话可生成Agent。生成的工作器不得委托任务；当需要其他专家时，返回
```
ESCALATE_TO_PARENT
```
。
生成前先确认状态：对于M/L/XL级任务，创建运行账本并在生成或重新生成前进行检查。
大规模工作前先做计划门控：M/L/XL级任务在实施前需要依赖感知计划和可执行性门控。

Step 1 — Classify before spawning

步骤1 — 生成前先分类

Classify the task using these dimensions:

Known files: 0, 1, 2–3, 4–8, 9+
Surfaces: frontend, backend, database, infra, docs, tests, browser, security
Ambiguity: low, medium, high
Risk: low, medium, high, critical
Required evidence: none, targeted test, full test matrix, browser QA, security review
Parallel value: low, medium, high
Worktree state: clean, dirty, unknown

Use

scripts/orchestration_decider.py

when useful.

从以下维度对任务进行分类：

已知文件数量：0、1、2–3、4–8、9+
涉及领域：frontend、backend、database、infra、docs、tests、browser、security
模糊度：低、中、高
风险等级：低、中、高、关键
所需证据：无、定向测试、全测试矩阵、浏览器QA、安全评审
并行价值：低、中、高
工作树状态：干净、脏、未知

必要时使用

scripts/orchestration_decider.py

。

Step 2 — Pick the minimum viable orchestration mode

步骤2 — 选择最小可行编排模式

Mode	Criteria	Agents
XS	Known one-file or tiny low-risk fix	`micro_implementer_low` only
S	1–3 related files, low/medium ambiguity	`micro_implementer_low` or `batch_implementer_medium` ; optional `test_runner_low`
M	3–8 files or unclear owner/root cause	short DAG; `code_mapper_medium` then `batch_implementer_medium` ; verifier
L	Multi-surface feature/fix, 8–20 files	DAG + state ledger + bounded mapper/research + 1–2 implementers + verification
XL	Ambiguous high-risk auth/payment/security/data/concurrency/prod incident	DAG + plan gate + `deep_debugger_xhigh` or high reviewers, then scoped implementers

模式	判定标准	使用Agent
XS	已知单文件或微小低风险修复	仅使用 `micro_implementer_low`
S	1–3个相关文件，低/中模糊度	`micro_implementer_low` 或 `batch_implementer_medium` ；可选 `test_runner_low`
M	3–8个文件或所有者/根因不明确	短DAG；先使用 `code_mapper_medium` 再使用 `batch_implementer_medium` ；验证器
L	跨领域功能/修复，8–20个文件	DAG + 状态账本 + 受限映射/调研 + 1–2个实现者 + 验证
XL	模糊高风险的认证/支付/安全/数据/并发/生产事件	DAG + 计划门控 + `deep_debugger_xhigh` 或高级评审者，然后是限定范围的实现者

Step 3 — Create control-plane state when needed

步骤3 — 必要时创建控制平面状态

For XS/S, do not create unnecessary artifacts unless useful. For M/L/XL, initialize a run ledger:

bash

python .agents/skills/agentic-orchestration-control/scripts/run_ledger.py init --task "<task>"

Use the ledger to record phases, dispatches, Handoff Packets, claimed files, evidence, failures, and final status. Before spawning any worker, check the ledger for duplicate active/completed work. Read

references/control-plane.md

and

references/session-lifecycle.md

when needed.

对于XS/S级任务，除非有用，否则不要创建不必要的工件。对于M/L/XL级任务，初始化运行账本：

bash

python .agents/skills/agentic-orchestration-control/scripts/run_ledger.py init --task "<task>"

使用账本记录阶段、调度、交接包、已认领文件、证据、失败和最终状态。在生成任何工作器前，检查账本是否存在重复的活跃/已完成工作。必要时阅读

references/control-plane.md

和

references/session-lifecycle.md

。

Step 4 — Build a DAG only when orchestration is justified

步骤4 — 仅在需要编排时构建DAG

Do not use a DAG for tiny tasks. For M/L/XL, create a compact dependency-aware DAG with at most 7 phases:

bash

python .agents/skills/agentic-orchestration-control/scripts/dag_planner.py --task "<task>" --size M --surfaces frontend,backend > .orchestration/plan.json
python .agents/skills/agentic-orchestration-control/scripts/plan_gate.py .orchestration/plan.json

If the gate rejects the plan, fix the plan before spawning. The plan gate checks executability, dependencies, acceptance criteria, validation, and worker leaf policy. Read

references/dag-plan-gate.md

when needed.

小型任务无需使用DAG。对于M/L/XL级任务，创建最多包含7个阶段的紧凑依赖感知DAG：

bash

python .agents/skills/agentic-orchestration-control/scripts/dag_planner.py --task "<task>" --size M --surfaces frontend,backend > .orchestration/plan.json
python .agents/skills/agentic-orchestration-control/scripts/plan_gate.py .orchestration/plan.json

如果门控拒绝计划，请在生成前修复计划。计划门控会检查可执行性、依赖关系、验收标准、验证和工作器叶节点策略。必要时阅读

references/dag-plan-gate.md

。

Step 5 — Enforce leaf-worker spawning boundary

步骤5 — 强制执行叶节点工作器生成边界

Before every spawn, verify the selected custom agent has all three safeguards:

text

[features].multi_agent = false
[agents].max_depth = 0
LEAF WORKER CONTRACT in developer_instructions

Do not rely on

agents.max_depth = 1

alone. If a worker returns

ESCALATE_TO_PARENT

, the root decides whether to spawn another agent, resume the same worker, or continue serially.

每次生成前，验证所选自定义Agent是否具备以下三项防护措施：

text

[features].multi_agent = false
[agents].max_depth = 0
LEAF WORKER CONTRACT in developer_instructions

不要仅依赖

agents.max_depth = 1

。如果工作器返回

ESCALATE_TO_PARENT

，由根会话决定是否生成另一个Agent、恢复同一工作器或继续串行处理。

Step 6 — Thinking/reasoning router

步骤6 — 思考/推理路由

```
low
```
: known file, straightforward code edit, targeted test, mechanical fix.
```
medium
```
: normal feature/fix, several related files, moderate debugging, browser QA.
```
high
```
: complex logic, edge cases, security review, migrations, broad regression audit.
```
xhigh
```
: only when root cause is unknown and risk is high/critical, or the task involves security/payment/auth/data/concurrency across multiple surfaces.

Do not use xhigh for a single-file fix unless that single file is security/payment/auth/data/concurrency critical or lower-effort attempts failed with evidence.

Use

scripts/budget_governor.py

to catch obvious over-orchestration before spawning:

bash

python .agents/skills/agentic-orchestration-control/scripts/budget_governor.py --size M --agents code_mapper_medium,batch_implementer_medium,verification_engine_medium --reasoning medium

```
low
```
：已知文件、直接代码编辑、定向测试、机械修复。
```
medium
```
：常规功能/修复、多个相关文件、中等调试、浏览器QA。
```
high
```
：复杂逻辑、边缘情况、安全评审、迁移、广泛回归审计。
```
xhigh
```
：仅当根因未知且风险为高/关键，或任务涉及跨多个领域的安全/支付/认证/数据/并发时使用。

除非单个文件是安全/支付/认证/数据/并发关键文件，或低层级尝试已失败且有证据，否则不要对单文件修复使用xhigh层级。

生成前使用

scripts/budget_governor.py

捕获明显过度编排的情况：

bash

python .agents/skills/agentic-orchestration-control/scripts/budget_governor.py --size M --agents code_mapper_medium,batch_implementer_medium,verification_engine_medium --reasoning medium

Step 7 — Compile Dispatch Packets

步骤7 — 编译调度包

Dispatch Packets must be short and targeted. Do not paste the whole plan. Include:

text

ROLE:
MODE / REASONING BUDGET:
OBJECTIVE:
SCOPE OWNERSHIP:
FILES / AREAS ALLOWED:
FILES / AREAS FORBIDDEN:
CONTEXT DIGEST:
TASK BUNDLE:
ACCEPTANCE CRITERIA:
VALIDATION REQUIRED:
STOP CONDITIONS:
SKILL / DELEGATION POLICY: Do not invoke skills. Do not spawn, request, recommend, or plan child subagents. If more agents are needed, return ESCALATE_TO_PARENT to the root. Treat this packet as complete.
OUTPUT: concise Handoff Packet only.

Use

scripts/dispatch_compiler.py

when useful.

调度包必须简短且针对性强。不要粘贴完整计划。需包含：

text

ROLE:
MODE / REASONING BUDGET:
OBJECTIVE:
SCOPE OWNERSHIP:
FILES / AREAS ALLOWED:
FILES / AREAS FORBIDDEN:
CONTEXT DIGEST:
TASK BUNDLE:
ACCEPTANCE CRITERIA:
VALIDATION REQUIRED:
STOP CONDITIONS:
SKILL / DELEGATION POLICY: Do not invoke skills. Do not spawn, request, recommend, or plan child subagents. If more agents are needed, return ESCALATE_TO_PARENT to the root. Treat this packet as complete.
OUTPUT: concise Handoff Packet only.

必要时使用

scripts/dispatch_compiler.py

。

Step 8 — Batch tasks

步骤8 — 批量处理任务

Before spawning implementers, group work by ownership:

Same user flow → one worker.
Same package/module → one worker.
Frontend + small API touch for the same feature → one
```
batch_implementer_medium
```
, not two agents.
Independent read-only audits → parallel agents are okay.
Independent write-heavy modules → separate workers only if file ownership does not overlap.

Use

scripts/batch_tasks.py

when useful.

生成实现者前，按所有权分组工作：

同一用户流程 → 一个工作器。
同一包/模块 → 一个工作器。
前端 + 同一功能的小型API修改 → 一个
```
batch_implementer_medium
```
，而非两个Agent。
独立只读审计 → 可并行使用Agent。
独立写密集型模块 → 仅当文件所有权不重叠时使用单独工作器。

必要时使用

scripts/batch_tasks.py

。

Step 9 — Communication routing and handoff validation

步骤9 — 通信路由与交接验证

Use

communication_router_low

only from the root session, and only when there are multiple Handoff Packets, conflicting claims, overlapping files, or many test results. For a one-worker XS/S task, the root can consume the Handoff Packet directly.

Validate leaf handoffs if they are suspicious, too long, or contain routing fields:

bash

python .agents/skills/agentic-orchestration-control/scripts/handoff_validate.py <handoff-file>

Workers must not return

next_handoff

target_agent

, or any child-agent plan unless explicitly requested by the user.

仅从根会话使用

communication_router_low

，且仅当存在多个交接包、冲突声明、重叠文件或大量测试结果时使用。对于单工作器的XS/S级任务，根会话可直接处理交接包。

如果叶节点交接包可疑、过长或包含路由字段，请进行验证：

bash

python .agents/skills/agentic-orchestration-control/scripts/handoff_validate.py <handoff-file>

除非用户明确要求，否则工作器不得返回

next_handoff

、

target_agent

或任何子Agent计划。

Step 10 — Failure recovery

步骤10 — 故障恢复

Do not respond to failure by blindly spawning another agent.

Classify failure.
Retry transient failures once.
Send compile/test failures back to the same implementation owner with exact evidence.
Escalate sandbox, permission, dirty-worktree, or scope conflicts to the root/user.
Replan after repeated systematic failure.

Use:

bash

python .agents/skills/agentic-orchestration-control/scripts/failure_classifier.py --file <failure-log>

Read

references/failure-recovery.md

when needed.

不要通过盲目生成另一个Agent来应对故障。

对故障进行分类。
瞬态故障重试一次。
将编译/测试故障连同确切证据返回给同一实现所有者。
将沙箱、权限、工作树脏数据或范围冲突升级至根会话/用户。
反复系统性故障后重新规划。

使用：

bash

python .agents/skills/agentic-orchestration-control/scripts/failure_classifier.py --file <failure-log>

必要时阅读

references/failure-recovery.md

。

Step 11 — Verification gate

步骤11 — 验证门控

XS/S: targeted tests or commands relevant to touched files.
M: targeted tests + lint/typecheck/build where relevant.
L/XL: full matrix, browser QA if UI flow changed, security/regression review if high-risk.

Use

scripts/test_matrix.py

and

scripts/quality_gate.py

for deterministic command discovery/execution.

XS/S级：针对受影响文件的定向测试或命令。
M级：定向测试 + 相关的lint/类型检查/构建。
L/XL级：全测试矩阵；如果UI流程变更则进行浏览器QA；如果是高风险则进行安全/回归评审。

使用

scripts/test_matrix.py

和

scripts/quality_gate.py

进行确定性命令发现/执行。

Step 12 — Worktree isolation when appropriate

步骤12 — 适时进行工作树隔离

For L/XL, dirty checkouts, or high-risk multi-file edits, consider isolated worktree planning before implementation:

bash

python .agents/skills/agentic-orchestration-control/scripts/worktree_guard.py --root . --run-id <run_id>

Only create a worktree when it is clearly useful and safe. Read

references/worktree-isolation.md

when needed.

对于L/XL级任务、脏检出或高风险多文件编辑，可在实施前考虑隔离工作树规划：

bash

python .agents/skills/agentic-orchestration-control/scripts/worktree_guard.py --root . --run-id <run_id>

仅当明确有用且安全时才创建工作树。必要时阅读

references/worktree-isolation.md

。

Step 13 — Durable learning, not transcript bloat

步骤13 — 持久化学习，避免 transcript 冗余

At the end of meaningful runs, write a tiny notepad entry only if the insight will help future work:

bash

python .agents/skills/agentic-orchestration-control/scripts/notepad.py --kind learnings --context "..." --insight "..." --impact "..."

Do not store raw logs, private reasoning, or generic summaries. Read

references/wisdom-notepads.md

when needed.

在有意义的运行结束时，仅当见解有助于未来工作时才写入小型记事本条目：

bash

python .agents/skills/agentic-orchestration-control/scripts/notepad.py --kind learnings --context "..." --insight "..." --impact "..."

不要存储原始日志、私人推理或通用摘要。必要时阅读

references/wisdom-notepads.md

。

Step 14 — Final output

步骤14 — 最终输出

Return a PR-ready summary:

Classification and why the chosen agent count/reasoning was sufficient.
Run ID if a ledger was created.
Agents used and why.
Files changed.
Tests/commands/browser checks run and results.
Failures and recovery decisions.
Known residual risks or skipped checks.
Follow-up only when genuinely useful.

返回可直接用于PR的摘要：

分类结果及所选Agent数量/推理层级充足的原因。
如果创建了账本则提供运行ID。
使用的Agent及原因。
修改的文件。
运行的测试/命令/浏览器检查及结果。
故障及恢复决策。
已知剩余风险或跳过的检查。
仅在真正有用时提供后续建议。

Reference modules

参考模块

Read these only when needed:

```
references/spawn-economics.md
```
```
references/thinking-router.md
```
```
references/dispatch-packet.md
```
```
references/worker-contract.md
```
```
references/test-gate.md
```
```
references/skill-scope-policy.md
```
```
references/leaf-worker-boundary.md
```
```
references/control-plane.md
```
```
references/dag-plan-gate.md
```
```
references/session-lifecycle.md
```
```
references/failure-recovery.md
```
```
references/worktree-isolation.md
```
```
references/wisdom-notepads.md
```
```
references/source-contract-proof.md
```
```
references/evaluation-harness.md
```

仅在需要时阅读：

```
references/spawn-economics.md
```
```
references/thinking-router.md
```
```
references/dispatch-packet.md
```
```
references/worker-contract.md
```
```
references/test-gate.md
```
```
references/skill-scope-policy.md
```
```
references/leaf-worker-boundary.md
```
```
references/control-plane.md
```
```
references/dag-plan-gate.md
```
```
references/session-lifecycle.md
```
```
references/failure-recovery.md
```
```
references/worktree-isolation.md
```
```
references/wisdom-notepads.md
```
```
references/source-contract-proof.md
```
```
references/evaluation-harness.md
```