Orchestrator

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ./requirements.txt for the dependency lockfile (currently empty — standard library only).

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).

The Core Loop

Ecosystem Context

• Patterns: learning-loop | red-team-review | dual-loop | agent-swarm | triple-loop-learning
• Inner Loop Reference: cli-agent-executor.md — Persona configs for specialized CLI execution.

Routing Decision Tree

Use this to select the correct execution pattern (for interactive navigation, invoke the select-loop-strategy skill):

1. Does the task require formal state machine transitions, human gates, worktree sandboxing, and rollback?
   └─ YES → Pattern 6: graph-execution

2. Does the trigger mention unguided friction evaluation, tests, and self-optimization?
   └─ YES → Pattern 5: triple-loop-learning

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

4. Can the work be split into parallel independent tasks?
   └─ YES → Pattern 4: agent-swarm

5. Does it require hierarchical delegation (Outer Director managing git vs. Inner Worker)?
   └─ YES → Pattern 3: dual-loop

6. Is this work I can do entirely myself (research, document, iterate in single context)?
   └─ YES → Pattern 1: learning-loop

Process Flow

0. Interactively Determine CLI and Model (ask once during bootstrap): Before initiating delegation or preparing packets, you must interactively prompt the user to select their desired execution setup. Ask:
   • "Which LLM CLI backend would you like to use for sub-agent execution?" (Options: agy, claude, copilot, codex, llama).
   • "Which specific model should be used?" (Options/defaults per backend, e.g., Gemini 3.5 Flash (Low) or gemini-3.5-flash for agy). Record their choice and pass it to the sub-agent runner (run_agent.py) using the --cli and --model flags, ensuring you append < /dev/null to prevent SIGTTIN process halts.
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.

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.

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.

Commands

You orchestrate workflows by natively executing the agent_orchestrator.py script provided by this skill (located in scripts/).

1. Planning Status Assessment

Perform specification and task readiness assessment directly via native file inspection before delegating. Ensure the task has clear acceptance criteria, atomic scope, and verifiable tests.

2. Delegation (Handoff)

When a task is ready for implementation, generate a Task Packet using the packet command.

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.

3. Verification & Correction (Trust But Verify & TDD)

You must check all outputs of the agents you orchestrate. No blind trust is allowed. Check the Inner Loop's work against the packet using the verify command:

python ./scripts/agent_orchestrator.py verify --packet handoffs/task_packet_NNN.md --worktree <PATH>

Follow these strict verification rules:

• TDD Enforcement: Running tests is mandatory. Verify that code is functionally proven and passes the test suite. If tests are missing, reject the package until tests are written.
• Delta Inspection: Check modified files directly. Review all logic adjustments for stubs, stales, or architectural regressions.
• Continuous Loop Improvement: For any failure, evaluate the retrospective data and modify the templates, prompts, or reference instructions to prevent repeat failures (continuous learning).

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:

python ./scripts/agent_orchestrator.py correct --packet handoffs/task_packet_NNN.md --feedback "Specific failure reason"

4. Parallel Execution (Agent Swarm)

For bulk operations or partitioned tasks, use the swarm_run.py script from the agent-swarm skill.

python ./swarm_run.py --job <JOB_FILE> [--resume]

This is the designated route for all Pattern 4 triggers.

4. Dynamic Routing (Model Agnostic)

As the Orchestrator, you can route tasks to ANY capable CLI agent based on complexity:

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

When an architecture design, security assessment, or plan requires adversarial evaluation, delegate to the red-team-review skill to compile context packets and manage review rounds until approved.

6. Retrospective (Post-Loop Learning)

Generate a retrospective template to close the cognitive loop with structured learning, before signaling the environment to seal.

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.

7. Handoff to Primary Agent (Ecosystem Sealing)

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:

• Trigger context-bundler:context-bundling or update recursive language model (RLMs) summaries in caches.
• Trigger persist_soul 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.

Session Closure

Session Closure

Execution complete. Run your environment's standard session closure sequence. If you are using agent-agentic-os, trigger os-improvement-loop closure. If you are in a standalone project, save any outputs to your preferred persistence location and close the session.

8. Sub-Agent Limitations

• 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 (for agy / claude) or if the user is not authenticated natively using claude login.
• CRITICAL: When executing sub-agent commands in background or headless scripts (e.g., via run_agent.py or system subprocess runners), you must redirect standard input (e.g., stdin=subprocess.DEVNULL or < /dev/null) to prevent the operating system from suspending the process with a SIGTTIN signal, which hangs execution indefinitely.

Lifecycle State Tracking

The orchestrator must verify these gates at each phase:

No phase may be skipped. If a gate fails, the orchestrator must resolve it before proceeding.

Loop Controls (Ralph-Inspired)

Automation

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.

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.