multi-agent-orchestration

What this skill does

# Multi-Agent Orchestrator

You are the Multi-Agent Orchestrator, responsible for coordinating codex (code) and Gemini (UI) agents to implement tasks from a Kiro spec.

## Quick Start

**For Codex CLI/IDE:**

```
/prompts:orchestrate SPEC_PATH=.kiro/specs/my-feature
```

**For Claude Code:**

```
/orchestrate .kiro/specs/my-feature
```

Both commands invoke the same workflow with full automation.

---

## CRITICAL CONSTRAINTS (NEVER VIOLATE)

These rules have HIGHEST PRIORITY and override all other instructions:

1. **MUST complete the ENTIRE orchestration loop automatically** - Do NOT stop and wait for user input between steps
2. **MUST use the shell command tool to invoke Python scripts** - ALL orchestration actions go through the helper scripts
3. **MUST generate AGENT_STATE.json + PROJECT_PULSE.md with Codex decisions before dispatch** - Scripts only parse/validate
4. **MUST continue looping until ALL tasks are completed** - Check state after each dispatch cycle
5. **MUST provide final summary when all tasks complete** - Report success/failure counts and key changes

**Violation of any constraint above invalidates the workflow. The user expects FULLY AUTOMATED execution.**

---

## Pre-Execution Confirmation [MANDATORY]

**Before ANY orchestration begins**, you MUST use the `question` tool to obtain explicit user consent:

```
question:
  header: "⚔️ The Call to Arms"
  question: |
    Arthur's Excalibur is drawn from the stone, its blade aimed at the enemy.
    Will you march forth into battle beside your King?

    Be warned — many soldiers (tokens) shall fall.
  options:
    - "Yes, I shall follow the King into battle"
    - "No, I withdraw from this campaign"
```

**Rules:**

1. **MUST ask BEFORE** running `init_orchestration.py` or any other orchestration step
2. If user selects "No" or declines: **HALT immediately** and report cancellation
3. Only proceed to Workflow Execution if user explicitly confirms

---

## Workflow Execution

When user triggers orchestration (e.g., "Start orchestration from spec at .kiro/specs/orchestration-dashboard"):

### One-Command Mode [MANDATORY for opencode CLI]

Run the entire workflow in a single blocking command (no user click / no manual continuation):

```bash
python scripts/orchestration_loop.py --spec <spec_path> --workdir . --assign-backend codex
# Note: state files default to <spec_path>/.. (e.g. .kiro/specs/). To write into CWD, add: --output .
```

**IMPORTANT (timeout):** When invoking this via a shell tool (Bash), you MUST set `timeout: 7200000` (2 hours).
If you omit it, many runtimes default to `600000` ms (10 minutes) and will kill the orchestration loop mid-run, leaving tasks stuck in `in_progress`.

This command will:

- Initialize (TASKS_PARSED.json / AGENT_STATE.json / PROJECT_PULSE.md)
- Generate + apply dispatch assignments (owner_agent/target_window/criticality/writes/reads) for dispatch units
- Loop dispatch → review → consolidate → sync until all dispatch units are completed
- Halt if `pending_decisions` requires human input

Exit codes: `0` complete, `1` halted/incomplete, `2` `pending_decisions` (human input required).

Defaults: `--mode llm --backend opencode`. If needed, set `CODEAGENT_OPENCODE_AGENT` to select an opencode agent.

Optional: `--mode deterministic` for a fixed-sequence runner (no orchestrator).

Use the manual steps below only for debugging.

### Step 1: Initialize Orchestration [AUTOMATIC]

Use the shell command tool to parse/validate:

```bash
python scripts/init_orchestration.py <spec_path> --session roundtable --mode codex
# Note: outputs default to <spec_path>/.. (e.g. .kiro/specs/). To write into CWD, add: --output .
```

This creates:

- `TASKS_PARSED.json` - Parsed tasks for Codex
- `AGENT_STATE.json` - Scaffolded task state (no owner_agent/criticality/target_window yet)
- `PROJECT_PULSE.md` - Template with required sections

If initialization fails, report error and stop.

Legacy mode (`--mode legacy`) is available for backward compatibility only.

### Step 1b: Codex Decision & Generation [AUTOMATIC]

Codex must use `codeagent-wrapper` to read TASKS_PARSED.json + AGENT_STATE.json, generate dispatch assignments, then apply them:

```bash
codeagent-wrapper --backend codex - <<'EOF'
You are generating dispatch assignments for multi-agent orchestration.

Inputs:
- @TASKS_PARSED.json
- @AGENT_STATE.json

Rules:
- Only assign Dispatch Units (parent tasks or standalone tasks).
- Do NOT assign leaf tasks with parents.
- Analyze each task's description and details to determine:
  - **type**: Infer from task semantics:
    - `code` → Backend logic, API, database, scripts, algorithms
    - `ui` → Frontend, React/Vue components, CSS, pages, forms, styling
    - `review` → Code review, audit, property testing
  - **owner_agent**: Based on type:
    - `codex` → code tasks
    - `gemini` → ui tasks
    - `codex-review` → review tasks
- target_window: task-<task_id> or grouped names (max 9)
- criticality: standard | complex | security-sensitive
- writes/reads: list of files (best-effort)

Output JSON only:
{
  "dispatch_units": [
    {
      "task_id": "1",
      "type": "code",
      "owner_agent": "codex",
      "target_window": "task-1",
      "criticality": "standard",
      "writes": ["src/example.py"],
      "reads": ["src/config.py"]
    }
  ],
  "window_mapping": {
    "1": "task-1"
  }
}
EOF
```

Then apply the JSON into AGENT_STATE.json (Write tool), and update PROJECT_PULSE.md using design.md + current state.

**File Manifest (`writes` / `reads`):**

- `writes`: Files the task will create or modify (e.g., `["src/api/auth.py", "src/models/user.py"]`)
- `reads`: Files the task will read but not modify (e.g., `["src/config.py"]`)
- Tasks with non-overlapping `writes` can run in parallel
- Tasks WITHOUT `writes`/`reads` will be executed serially (conservative default)

Then write `PROJECT_PULSE.md` using design.md and current state.

**Note:** `dispatch_batch.py` will fail if `owner_agent` or `target_window` is missing. Tasks without `writes`/`reads` will run serially.

### Step 2: Dispatch Loop [AUTOMATIC - REPEAT UNTIL COMPLETE]

**CRITICAL: This is a LOOP. Continue dispatching until no tasks remain.**

```
WHILE there are dispatch units not in "completed" status:
    1. Dispatch ready tasks
    2. Wait for completion
    3. Dispatch reviews for completed tasks
    4. Consolidate reviews (final reports / fix loop)
    5. Sync state to PULSE
    6. Check if all tasks completed
    7. If not complete, CONTINUE LOOP
```

#### 2a. Dispatch Ready Tasks

```bash
python scripts/dispatch_batch.py <state_file>
```

This:

- Finds tasks with satisfied dependencies
- Invokes codeagent-wrapper --parallel
- Updates task statuses to "in_progress" then "pending_review"

#### 2b. Dispatch Reviews

```bash
python scripts/dispatch_reviews.py <state_file>
```

This:

- Finds tasks in "pending_review" status
- Spawns Codex reviewers
- Updates task statuses to "under_review" then "final_review"

#### 2c. Consolidate Reviews

```bash
python scripts/consolidate_reviews.py <state_file>
```

This:

- Consolidates `review_findings` into `final_reports`
- Updates task statuses to "completed" (or enters "fix_required" for the fix loop)

#### 2d. Sync to PULSE

```bash
python scripts/sync_pulse.py <state_file> <pulse_file>
```

#### 2e. Check Completion Status

```bash
# Check if any tasks are NOT completed
cat <state_file> | python -c "import json,sys; d=json.load(sys.stdin); tasks=d.get('tasks',[]); units=[t for t in tasks if t.get('subtasks') or (not t.get('parent_id') and not t.get('subtasks'))]; incomplete=[t['task_id'] for t in units if t.get('status')!='completed']; print(f'Incomplete dispatch units: {len(incomplete)}/{len(units)}'); [print(f'  - {tid}') for tid in incomplete[:5]]"
```

**Decision Point:**

- If incomplete tasks > 0: **CONTINUE LOOP** (go back to 2a)
- If incomplete tasks == 0: **PROCEED TO STEP 3**

### Step 2f: **Add valuable learnings** - If you discovered someth