# Agent Orchestration Skill > EXPLICIT ONLY. Use only when prompt contains `$agent-orchestration-skill`; root-only token-aware subagent orchestration with control-room events. - **Type:** Skill - **Install:** `agentstack add skill-zypherhq-agent-orchestration-skill-agent-orchestration-skill` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ZypherHQ](https://agentstack.voostack.com/s/zypherhq) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [ZypherHQ](https://github.com/ZypherHQ) - **Source:** https://github.com/ZypherHQ/agent-orchestration-skill/tree/main/skills/agent-orchestration-skill ## Install ```sh agentstack add skill-zypherhq-agent-orchestration-skill-agent-orchestration-skill ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Agent Orchestration Skill Use this skill only when the user prompt contains the exact literal `$agent-orchestration-skill`. Do not use this skill for ordinary coding, testing, audit, debugging, or subagent tasks when that literal invocation is absent. Use it only in the root Codex session. Never instruct spawned subagents to invoke this or any other repo skill, and never instruct spawned subagents to spawn more agents. This is a no nested delegation workflow. ## Step 0 — Runtime mode guard This skill is explicit-only and root-only. If the current user prompt does not contain `$agent-orchestration-skill`, stop using this skill and continue in normal mode. If the prompt says `You are a subagent`, `verification subagent`, `Run exactly these commands`, `Do not edit files`, `LEAF_EXEC_MODE`, or `Return only a YAML Handoff Packet`, do **not** use this skill, do **not** spawn agents, and perform only the bounded leaf task. ## Step 0.1 - Worker launch policy In an interactive Codex root session, the root orchestrator must use native Codex subagent spawning for workers. The expected transcript should look like: ```text Spawned ( ) ``` Do not launch mapper, implementer, verifier, reviewer, or any other orchestration worker through an external CLI process. Worker execution is native-spawn only. When spawning native workers, the root prompt must make the leaf boundary explicit: ```text LEAF_EXEC_MODE. You are a leaf worker. Do not spawn agents. Do not invoke skills. Use only the provided Dispatch Packet. Return the requested Handoff Packet. ``` Spawned workers are leaf workers. They must not spawn, request, recommend, coordinate, or plan child subagents. If a worker needs another worker, it must return `ESCALATE_TO_PARENT` with the blocker and let the root orchestrator decide. ## Step 0.2 - Immediate AOC run attachment When this skill is invoked in the root session, attach to AOC before docs lookup, Context Capsule creation, DAG planning, or worker spawning: ```bash aoc current --repo . --json ``` If no current run exists for the repo, initialize one immediately: ```bash aoc init --repo . --task "" --json ``` Store the selected `run_id` in root context and use it for every later event, capsule, dispatch, handoff, verification record, and final summary. Do not create a second run if `aoc current` already selected an active repo run. Emit a compact `skill_invoked` event after attach/init when a run ledger exists. `aoc current` is an active-run lookup, not a historical lookup. If the previous run has a terminal status or a `final_status`/`run_completed` event, start a new run with `aoc init` instead of appending fresh work to the old run. ## Prime directive Act as a **task compiler, context-preserving control-plane operator, and event-driven run supervisor**, not a prompt broadcaster. Classify the work, preserve the essential context, choose the cheapest adequate reasoning tier, batch related actions, compile minimal Dispatch Packets, track state, and collect concise Handoff Packets. The Context Capsule is persistent storage; a Dispatch Packet is only a small scoped slice for one worker. The capsule stays on disk; workers receive only the narrow slice they need. ## Command surface For normal project use, prefer the public CLI: ```bash npm install -g agentic-orchestration-control aoc --help aoc install-skill --strict aoc init --repo . --task "" aoc tui --repo . aoc gui --repo . ``` The direct `python3 "$AOC_SKILL_DIR/scripts/*.py"` examples below are low-level internal control-plane commands for the root skill operator. Use them only when the public `aoc` route does not expose the required operation. For internal helper scripts, resolve the globally installed skill directory first, before any direct `python3 "$AOC_SKILL_DIR/scripts/..."` call. This keeps commands working after `npm install -g agentic-orchestration-control`, even when the target repo does not contain a repo-local `skills/` copy: ```bash AOC_SKILL_DIR="${AOC_SKILL_DIR:-${CODEX_HOME:-$HOME/.codex}/skills/agent-orchestration-skill}" test -d "$AOC_SKILL_DIR/scripts" ``` ## Hard constraints 1. **Root-only skill:** subagents receive plain dispatch text, not skill names. 2. **Context never depends on memory alone:** store essential facts in a Context Capsule before multi-phase or multi-worker execution. 3. **No worker edits without Context Coverage:** a worker must read required files/areas and report coverage before changing code. 4. **No one-agent-per-file fan-out:** batch related files by user flow, module, package, or owner. 5. **No redundant waves:** if one worker can inspect, patch, and test a small change, use one worker. 6. **No raw output broadcast:** route only facts, blockers, file ownership, commands run, failures, and next actions. 7. **No full capsule broadcast:** keep the Context Capsule on disk and pass only a scoped slice to each worker. 8. **Dispatch budgets:** cap must-read files, facts, decisions, tests, and context text before spawning. If the packet is large, narrow the scope instead of spawning. 9. **Write workers must complete a loop:** context coverage → inspect → patch → targeted validation → Handoff Packet. 10. **Read-heavy work can be parallel; write-heavy work should be serialized or batched carefully.** 11. **Leaf-worker boundary:** only the root orchestrator session may spawn native Codex subagents. Workers return `ESCALATE_TO_PARENT` when they need help. 12. **Plan and budget gates before broad work:** medium/large tasks need a compact phase plan and budget check before implementation. 13. **Inspectable state:** when a run ledger exists, emit compact events so the control-room TUI can show sessions, worker lanes, gates, evidence, and memory without parsing raw logs. 14. **Native spawn only:** launch workers through native Codex subagent spawning. Do not shell out to external CLI processes for orchestration workers. 15. **Run lifecycle first:** attach/init the AOC run before any broad research, capsule, DAG, or worker spawn so the control room can show the whole run. 16. **No empty capsules for M/L/XL:** medium and larger runs must not create a Context Capsule with zero `must_read` entries. If ownership is unclear, first identify required files/areas, then create or update the capsule before dispatch. 17. **No xhigh for short read-only work:** read-only reviews, security reviews with a bounded focus, docs lookups, evidence checks, scouts, mappers, routers, and finalizers must not use `xhigh`. Use root synthesis or one focused `medium`/`high` reviewer. 18. **No non-action workers:** do not spawn a mapper/scout/docs researcher that only reads the same files the implementer must read. For cohesive implementation tasks, dispatch one implementer with context coverage instead. “Go deep” means stricter coverage and verification, not more agents. 19. **Map-only stays read-only:** if the user asks only to map, research, audit, inventory, or discover, spawn at most one read-only worker and do not add implementers/reviewers unless the user asks to proceed. 20. **No spawn before gates:** before the first native worker spawn, the root must run `orchestration_decider.py` and `budget_governor.py` using the intended worker IDs. Do not spawn a scout first and justify it afterward. 21. **Declared worker identities:** budget and dispatch must use stable native Codex worker IDs from the active environment. The package profiles in `subagents/*.toml` are defaults, not a required registry. If the user has custom agents, map decider roles to those IDs with `--agent-aliases` and optionally pass an allowlist with `--allowed-agents` or `--agent-registry`; do not invent one-off nicknames during the run. 22. **Budget actual reasoning:** budget checks must use the exact reasoning tier that will be used for each native worker. For custom agents whose names do not include `_low`, `_medium`, `_high`, or `_xhigh`, pass `--agent-reasoning worker=effort`. 23. **No micro follow-up waves:** do not spawn a new worker just to add a low-risk assertion, tiny formatting cleanup, or one-line test hardening after verification. Route it to an active owner if still running, fold it into the verifier only when already planned, or report it as a follow-up unless it is a blocking defect or failed validation. 24. **Worker events are structured:** every `worker_dispatched` event must include `--agent ` and `--reasoning ` so the control room can track lanes and cost accurately. 25. **No invented known-file counts:** pass `known-files > 0` only when the user named concrete paths or the root has allowed source evidence. Do not expand “go deep” into an audit/re-audit prompt or inflate known file count to force L/XL orchestration. ## Step 1 — Classify before spawning Classify the task using: - 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 Run `$AOC_SKILL_DIR/scripts/orchestration_decider.py` before any worker spawn. This is mandatory for every non-trivial task and for every proposed scout/research/review worker. Use the user’s actual task wording for `--task`. Do not rewrite a cohesive implementation request into “audit architecture, implement, verify, and re-audit” merely because the user said “go deep”. If the root has not read source and the user did not name files, use `--known-files 0`. ```bash python3 "$AOC_SKILL_DIR/scripts/orchestration_decider.py" \ --task "" \ --known-files \ --surfaces backend,tests \ --risk medium \ --ambiguity high \ --requires-docs true \ --root-can-edit false \ --force-delegate true \ --json ``` ## Step 2 — Pick the minimum viable orchestration mode | Mode | Criteria | Default behavior | |---|---|---| | XS | Known tiny task | Usually no subagent. If root edits are forbidden, exactly one `micro_implementer_medium` | | S | 1–3 related files | One bundled `micro_implementer_medium` or `batch_implementer_medium`; optional exact `test_runner_low` only when useful | | M | 3–8 files or unclear owner | Short DAG; `code_mapper_low` only if discovery is needed; one batched implementer; verifier | | L | Multi-surface feature/fix | Ledger + DAG + bounded scout/research + 1–2 implementers + verification | | XL | Very large or critical ambiguous work | Ledger + DAG + plan gate + optional `strategy_architect_xhigh`, then scoped high/medium workers | Do not spawn agents just to satisfy a habit. Spawn only when the worker has a meaningful bundle of work or isolates noisy verification/browser output. A useful worker must perform at least two valuable actions, such as inspect + patch, patch + validate, browser reproduce + evidence, or mapping + ownership summary. Mapper/scout hard stop: do not spawn a read-only mapper if the implementer must read the same files anyway. A mapper is allowed only when it inspects a substantially different surface, reduces unknown ownership across broad independent domains, or the root cannot compile a safe implementation Dispatch Packet without it. Otherwise one implementer owns context coverage, inspection, patching, focused validation, and handoff. First-scout exception: if ownership is genuinely unknown and the root cannot produce a safe implementation packet, the scout is allowed only after the decider recommends `code_mapper_low` or `scope_scout_low` and budget passes. The scout packet must be narrow, read-only, use `low` reasoning by default, cap must-read areas, and stop after recommending one bounded implementation bundle. Do not run a pre-gate scout. ## Step 3 — Preserve context before dispatch For every task with more than one phase or worker, create/update a Context Capsule. It is the root-owned source of truth for facts that must not be lost when a new subagent context opens. It is **not** prompt payload and must not be pasted wholesale into every worker prompt. For M/L/XL runs, do not initialize a capsule with zero `must_read` entries. Include the specific files/areas a worker must inspect before editing. If the first pass cannot identify exact files, perform a bounded read-only ownership scout first, then create/update the capsule with the discovered `must_read` list before any write worker is spawned. ```bash python3 "$AOC_SKILL_DIR/scripts/context_capsule.py" init \ --task "" \ --goal "" \ --run-id \ --must-read path/to/file_a \ --must-read path/to/file_b \ --require-must-read \ --acceptance "" \ --validation "" \ --out .orchestration/context_capsule.json ``` Keep the capsule compact. Store confirmed facts, rejected assumptions, decisions, ownership, required files/areas, forbidden files/areas, acceptance criteria, validation commands, blockers, and evidence references. Do not store raw logs, transcripts, broad summaries, or private reasoning. When dispatching a worker, use a narrow slice: ```bash python3 "$AOC_SKILL_DIR/scripts/context_capsule.py" slice \ --file .orchestration/context_capsule.json \ --focus "" \ --max-items 4 ``` Use: ```bash python3 "$AOC_SKILL_DIR/scripts/context_capsule.py" render --file .orchestration/context_capsule.json --focus "" --max-chars 1200 ``` Read `references/context-capsule.md` when needed. ## Step 4 — Create control-plane state when needed For XS/S, avoid unnecessary artifacts unless useful. For medium/large tasks, use the run attached in Step 0.2. If Step 0.2 was skipped because the task expanded after classification, attach/init now before any worker spawn: ```bash aoc current --repo . --json aoc init --repo . --task "" --json ``` Use the existing selected run when present. Use the ledger to record phases, dispatches, Handoff Packets, claimed files, evidence, failures, context capsule path, and final status. Before spawning any worker, check the ledger for duplicate active/completed work. When a ledger exists, treat the run as event-driven. Emit compact state changes so the optional control-room TUI can show the orchestration without parsing raw logs: ```bash python3 "$AOC_SKILL_DIR/scripts/event_emit.py" --root . --run-id --event worker_dispatched --agent batch_implementer_medium --reasoning medium --summary "frontend cart implementation bundle dispatched" ``` Use events for run creation, classification, DAG/budget gates, worker dispatch, Context Coverage, commands, handoffs, failures, memory updates, and final status. Worker dispatch events must include both `--agent` and `--reasoning`. Events are compact JSONL records; long logs belong in `evidence/` files. ## Step 5 — Build a DAG only when orchestration is justified Do not use a DAG for tiny tasks. For medium/large tasks, create a compact dependency-aware DAG with at most 7 phases: ```bash python3 "$AOC_SKILL_DIR/scripts/dag_planner.py" --task "" --size M --surfaces frontend,backend > .orchestration/plan.json python3 "$AOC_SKILL_DIR/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, context policy, and worker leaf policy. ## Step 6 — Reasoning router Use the cheapest adequate reasoning tier: - `low`: scouts, file/symbol discovery, code-path mapping, docs contract checks, exact command execution, routing/finalization. - `medium`: normal code writing, small-to-medium implementation bundles, browser QA, meaningful test design, verification matrices. - `high`: complex implementation, non-trivial business logic, migrations, concurrency suspicion, security-sensitive review, hard regression audit. - `xhigh`: very large ambiguous planning, architecture/feature structuring, critical design tradeoffs, or repeated high-effort failure with evidence. Do not use `xhigh` for routine updates, isolate … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [ZypherHQ](https://github.com/ZypherHQ) - **Source:** [ZypherHQ/agent-orchestration-skill](https://github.com/ZypherHQ/agent-orchestration-skill) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-zypherhq-agent-orchestration-skill-agent-orchestration-skill - Seller: https://agentstack.voostack.com/s/zypherhq - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.