Master Agent Orchestration v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/d19949c89f83d8f7.

---
name: Master Agent Orchestration
description: Guide for the Master Agent to orchestrate, monitor, and merge tasks across the 3-tier multi-agent architecture
when_to_use: when operating as the Master Agent (depth 0), spawning feature-level Superagents, managing worktrees, or merging branches in multi-agent mode
version: 1.0.0
languages: [typescript, shell]
---

# Master Agent Orchestration

## Overview
The **Master Agent (depth 0)** acts as the central orchestrator and coordinator. It does not modify code directly. Instead, it creates isolated worktrees, delegates feature-level development tasks to **Superagents (depth 1)**, monitors their progress, and merges the results back into the main branch.

```
                  Master Agent (depth 0)
                 /          |         \
         Superagent      Superagent   Superagent (depth 1)
        /          \         |          /        \
   Subagent      Subagent Subagent  Subagent   Subagent (depth 2)
```

---

## The Orchestration Tools

| Tool Name | Purpose | Key Parameters | Typical Usage Pattern |
|:---|:---|:---|:---|
| `invoke_superagent` | Spawns a Superagent on a new git branch & isolated worktree. | `role`, `task`, `branch`, `wait` (optional) | `invoke_superagent({ role: "ui-dev", task: "Build login screen", branch: "feat/login", wait: false })` |
| `await_superagents` | Waits for all running Superagents to finish their tasks. | `timeoutSeconds` (optional) | `await_superagents({ timeoutSeconds: 600 })` |
| `merge_superagents` | Merges completed Superagent branches with conflict resolution. | `cleanupWorktrees` (optional) | `merge_superagents({ cleanupWorktrees: true })` |
| `manage_superagents` | Lists instances, views logs/reports, or terminates agents. | `action` (`list`/`logs`/`report`/`kill`/`kill_all`), `superagentIds` | `manage_superagents({ action: "list" })` |
| `git_worktree` | Manages git worktree configurations manually. | `action`, `branch`, `path` | `git_worktree({ action: "list" })` |

---

## Core Workflow

### 1. Planning and Delegation
* Split complex requests into independent, parallelizable feature tasks.
* Assign each feature task a descriptive **role**, a **task prompt**, and a unique **branch name** (e.g. `feat/database-logger`).
* Spawn them concurrently using `invoke_superagent` with `wait: false`.

### 2. Monitoring Progress
* Use `manage_superagents` with `action: "list"` to check the status of all spawned instances.
* If a Superagent is taking long or you suspect issues, fetch active output logs using `manage_superagents` with `action: "logs"` and the target ID.
* Use `await_superagents` to pause execution until all delegated tasks finish.

### 3. Merging and Cleanup
* Once `await_superagents` reports success, review the task reports.
* Run `merge_superagents` to merge all feature branches back into the main branch. The Master Agent automatically uses LLM-assisted conflict resolution if merge conflicts arise.
* By default, this will also clean up the `.worktrees/` directory for those branches.

---

## Critical Architecture Rules & Constraints

### ⚠️ Preventing Circular Dependencies
* **Rule**: `toolsets.ts` and `prompts.ts` are imported by multiple tool files. Any tool file that needs to import from these files **MUST** use dynamic `import()` inside the `execute()` function body, never static top-level imports.
* **Example**:
  ```typescript
  // ❌ BAD: Top-level static import
  import { superagentToolset } from "./toolsets.js";

  // ✅ GOOD: Dynamic import inside execute
  async execute(args, cwd) {
    const { superagentToolset } = await import("./toolsets.js");
  }
  ```

### ⚙️ Windows PowerShell Separation
* **Rule**: When executing shell commands on Windows, statement separators must be `;` instead of `&&`. Always verify the platform first or default to compatible formats.

### 🛡️ Workspace Isolation
* **Rule**: Store global configs (`.env`), persistent logs (`superagent.log`), and session state inside the global home folder (`~/.superagent-r/`) rather than the target repository directory.

---

## Common Mistakes

### ❌ Spawning Superagents in Series (Blocking)
* **Mistake**: Setting `wait: true` or invoking one Superagent and immediately calling `await_superagents` before invoking the next.
* **Fix**: Fire all `invoke_superagent` calls with `wait: false` first, and then call `await_superagents` once.

### ❌ Direct File Modification by Master Agent
* **Mistake**: Master Agent using write/edit tools directly on source files in the main branch.
* **Fix**: Master Agent should only use read tools to analyze or inspect results. All code generation and bug fixes must happen inside a delegated Superagent or Subagent.