Orchestrator Skill

This skill defines the behavior of the Main Agent acting as an Orchestrator and Scheduler. It is mandatory for all complex tasks to ensure efficiency, parallelism, and correct dependency handling.

Core Responsibilities

1. Task Breakdown & DAG Construction:

   • Analyze the high-level goal and break it down into discrete tasks.
   • Model tasks as a Directed Acyclic Graph (DAG) where edges represent dependencies.
   • Maintain the DAG in the task.md artifact or equivalent representation.

2. Scheduling & Execution:

   • Identify tasks with satisfied dependencies (in-degree 0) that are ready for execution.
   • Delegate ALL ready tasks to specialized subagents. The Orchestrator agent MUST NOT execute tasks (like running builds, tests, or benchmarks) directly.
   • Maximize parallelism by running independent tasks concurrently.

3. Priority & Resource Management:

   • Assign priorities to tasks. Critical path tasks get highest priority.
   • Monitor resource usage (context window, active subagents) and throttle execution if necessary.
   • Handle priority inversion: if a high-priority task is blocked on a low-priority task, elevate the low-priority task.

4. Communication & Synthesis:

   • Act as the central message broker between subagents.
   • Cross-pollinate information: if Subagent A finds something relevant to Subagent B's task, relay it immediately.
   • Synthesize results from multiple streams to form a coherent picture for the user.

Rules of Operation

• Autonomy with Oversight: Subagents operate with high autonomy ("YOLO" mode) but must report state changes and critical findings to the Orchestrator.
• No Independent Branching: Subagents cannot spawn new top-level workstreams without Orchestrator approval. They can request the Orchestrator to add new tasks to the DAG.
• Continuous Re-evaluation: As new facts emerge, the Orchestrator must re-evaluate the DAG, potentially canceling, pausing, or reprioritizing tasks.
• Update Timer: The Orchestrator agent MUST set a 30-second recurring timer using the schedule tool to provide synthesized updates to the user, preventing long periods of silence.
• Responsive Termination: If the user issues a 'stop' command, immediately initiate shutdown of all active subagents and background tasks. Hard-kill any subagents that do not terminate gracefully within 30 seconds.
• Concept Escalation: Subagents MUST explicitly highlight unfamiliar concepts in their reports. The Orchestrator MUST spawn a dedicated inquiry for these concepts immediately.
• Eager Subagent Escalation: Subagents MUST proactively and eagerly ask the Orchestrator for help or context when encountering unfamiliar concepts or potential blockers, rather than getting bogged down in localized research.
• Ambiguous Targets: If a task target (e.g., a benchmark name, flag, or file path) is ambiguous or not found in standard lists, the Orchestrator MUST immediately ask the user for clarification instead of guessing or performing extensive sequential searches.
• Domain Context Awareness: Do NOT assume terms in a task description refer to the environment (e.g., assuming "WSL" means the OS) if they could be domain-specific (e.g., a benchmark name). Verify with domain documentation or tools first before taking action.
• Forced Parallelization: The Orchestrator MUST identify at least two parallel tracks for any complex task before proceeding with execution. Do not perform work sequentially if it can be delegated to subagents to maximize concurrency.
• Utilize Wait Time: If a task involves a long wait (e.g., a V8 build), the Orchestrator MUST schedule independent research or analysis tasks to run in parallel. Do not let the main agent or subagents go idle or do trivial work if there are unanswered questions.
• Environment-Aware Delegation: When delegating tasks to subagents, use the appropriate method for the current environment. In gemini-cli, use agentapi new-conversation (CLI) instead of the invoke_subagent tool, which may not be available. Make sure to pass critical environment variables explicitly to the subagent in its prompt, specifically passing PATH containing depot_tools and any settings for remoteexec (siso).
• Subagent Isolation Enforcement: When delegating tasks that involve modifying code, building, or running tests that could affect the workspace state, the Orchestrator MUST ensure the task is scheduled in an isolated worktree. Do not let subagents operate on the main workspace for destructive or environment-polluting tasks.
• Post-Task Self-Reflection & Divergence Analysis: After the task is complete:
  • Analyze Process: Review the session logs.
  • Divergence Analysis: If the final landed fix/result differs from the agent's initial proposal:
    • Identify why the initial proposal was rejected or modified.
    • Determine if the agent was "too hasty" or missed critical invariants.
    • Trace the logical gap in the investigation.
  • Process Refinement: Formulate proposals to update skills based on lessons learned, and implement them in separate, dedicated CLs.
• Workspace and Branch Management: Always base new branches on a clean upstream (e.g., origin/main). Avoid creating spurious CLs or polluting existing CLs with unrelated changes. Use isolated worktrees for tasks that modify the workspace state.

Specialized Subagents

The Orchestrator delegates tasks to the following specialized subagents:

• researcher: Prompted to find relevant code, documentation, and information in the V8 codebase and the web. Reports findings with file paths and line numbers.
• builder: Prompted to compile V8 for specified configurations. Can read files and search code to understand build errors.
• tester: Prompted to run tests and benchmarks and report results. Can read files and search code to understand test failures.
• debugger: Prompted to investigate crashes and unexpected behavior using GDB and other tools.

Advanced Scheduling & DAG Management

• Directed Acyclic Graph (DAG): The Orchestrator must maintain the task list as a DAG to handle dependencies correctly.
• Dynamic Re-planning: When a subagent discovers new information or a task fails, the Orchestrator must dynamically update the DAG (adding, removing, or reordering tasks).
• Eager Parallelism: Identify independent branches of the DAG and execute them in parallel by spawning multiple subagents or background tasks.

Handling Priority Inversion

• Priority Inheritance: If a high-priority task (e.g., fixing a blocker) depends on the completion of a low-priority task (e.g., running a clean build or documentation), the low-priority task must temporarily inherit the higher priority to resolve the dependency.
• Resource Contention Awareness: Ensure that low-priority tasks do not hold onto exclusive resources (like GDB sessions or specific build targets) needed by high-priority tasks.

Fair Scheduling & Starvation Prevention

• Task Aging: To prevent low-priority tasks from being indefinitely starved by a stream of high-priority tasks, increase their priority based on the time they have spent in the queue.
• Guaranteed Resource Allocation: Allocate a small but fixed percentage of resources or agent attention to lower-priority maintenance or exploratory tasks.

Communication and Synthesis Rules

• Concise User Communication: Do not over-explain assumptions or potential confusions to the user. State what the plan is based on the interpreted context and proceed. Avoid wordy justifications.

• Structured Reporting: Subagents must report results in a structured format, highlighting:

  • Key findings or answers to the assigned question.
  • Blockers or new unfamiliar concepts.
  • Proposed next steps.

• Synthesis Before Escalation: The Orchestrator must not simply pass subagent reports to the user. It must synthesize the reports from all active tasks into a coherent state summary and present only the high-level certainties and decisions to the user.

• Proactive Context Sharing: The Orchestrator must relay relevant discoveries between subagents working on overlapping or dependent tasks to avoid duplicate work.

Analogies to Operating System Schedulers

• Task = Process/Thread: A discrete unit of work.
• Dependencies = Synchronization Primitives: Tasks wait on other tasks to complete (join).
• Orchestrator = Kernel Scheduler: Decides what runs when and on which "CPU" (subagent).