orchestration

Orchestration

Scope: covers multi-agent workflow design. For individual agent authoring, see [[writing-agents]]. For plugin architecture, see [[writing-plugins]].

1. Four Orchestration Patterns

Pattern A: Parallel Dispatch

Multiple agents run simultaneously on independent work. A command dispatches them via the Task tool and synthesizes results.

Command dispatches via Task:
  |-- agent-1 (analyzes security)
  |-- agent-2 (analyzes performance)
  |-- agent-3 (analyzes architecture)
  --> Command synthesizes all results into final report

Use when: agents don't depend on each other's output.

Real examples:

• grill plugin: 6 review agents analyze code from different angles in parallel
• docs-guardian: 4 agents (staleness, accuracy, coverage, quality) run simultaneously

Implementation pattern in command body:

## Execution
1. Dispatch the following agents in parallel using Task:
   - security-agent: analyze for vulnerabilities
   - performance-agent: analyze for bottlenecks
   - architecture-agent: analyze for structural issues
2. Collect all agent outputs
3. Synthesize into a unified report with cross-references

Key decisions:

Pattern B: Sequential Pipeline

Each stage feeds into the next. Output of stage N is input to stage N+1.

parse --> chunk --> summarize --> QC --> output

Use when: each stage depends on the previous stage's output.

Real examples:

• reading-assistant: parse PDF -> chunk content -> summarize chunks -> QC summaries -> output
• tdd-guardian: discover tests -> run tests -> check coverage -> analyze failures -> report -> enforce

Implementation pattern:

## Execution
### Phase 1: Parse (haiku)
1. Scan input files
2. Extract structured content
3. Output: parsed data as JSON

### Phase 2: Process (sonnet)
4. Receive parsed data from Phase 1
5. Analyze and transform
6. Output: processed results

### Phase 3: QC (sonnet)
7. Verify Phase 2 output meets quality bar
8. Output: pass/warn/fail verdict

### Phase 4: Output
9. If QC passed: format and deliver final report
10. If QC failed: report failures and stop

Key decisions:

Pattern C: QC Gate

AI processing followed by quality verification before output reaches the user.

Phase 1: Mechanical prep (haiku)
Phase 2: AI work (sonnet)
Phase 3: QC verification (sonnet/opus)
  --> pass: proceed to output
  --> warn: output with warnings
  --> fail: stop, report issues
Phase 4: Output

Use when: AI output needs verification before the user sees it.

Threshold design:

Real examples:

• reading-assistant: QC agents verify summaries for accuracy, completeness, fidelity
• codex-toolkit audit-fix: audit -> fix -> verify loop

Pattern D: Retry Loop

On failure, re-dispatch with error context. The agent gets a second chance with specific feedback about what went wrong.

agent produces output
  --> QC checks output
    --> pass: done
    --> fail: re-dispatch agent with error context
      --> QC re-checks
        --> pass: done
        --> fail (attempt 2): re-dispatch again
          --> max retries reached: fail with report

Use when: quality failures are recoverable by re-trying with more context.

Implementation:

## Retry Protocol
- Max retries: 3
- On retry, include in the agent prompt:
  - Previous output (or summary if too long)
  - Specific failures from QC
  - Instruction: "Fix ONLY the listed failures. Do not change passing sections."
- If max retries exhausted: output best attempt with failure annotations

Key decisions:

2. Shared Partials for DRY

Extract common logic into commands/shared/*.md with user-invocable: false in frontmatter.

When to Extract

Good Candidates for Extraction

Partial File Structure

---
user-invocable: false
description: "Shared config loading logic — reads and validates the plugin config file"
---

## Config Loading

1. Look for `.config.md` in the project root
2. If not found, look for `.config.yaml`
3. If neither found, output error: "Run `/plugin:init` first to create a config file"
4. Parse the config file
5. Validate required fields: [list fields]
6. Return parsed config

3. Cost Gates

For expensive AI pipelines, add a cost estimation step between mechanical prep and AI processing.

Implementation

Phase 1: Parse and discover (haiku -- cheap)
  --> Count items to process
  --> Estimate cost: items x model cost per item
  --> Display estimate to user

User confirms or adjusts scope

Phase 2: AI processing (sonnet/opus -- expensive)
  --> Process confirmed scope

Cost Estimation Table

"Item" = one agent invocation processing one unit of work (one file, one chunk, one artifact).

User Confirmation Pattern

## Cost Gate
After Phase 1, display:
- Items to process: {N}
- Estimated model: {model}
- Estimated cost: ~${amount}
- Estimated time: ~{minutes} minutes

Ask: "Proceed with {N} items? (You can reduce scope with --filter)"

4. Pipeline State

For resumable pipelines (long-running, expensive, or failure-prone), track state in a JSON file.

State File Schema

{
  "pipeline": "my-pipeline",
  "startedAt": "2024-01-15T10:00:00Z",
  "configFingerprint": "sha256:abc123",
  "phases": {
    "parse": {
      "status": "completed",
      "startedAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:00:05Z",
      "itemsProcessed": 42,
      "output": "parse-output.json"
    },
    "analyze": {
      "status": "running",
      "startedAt": "2024-01-15T10:00:06Z",
      "itemsProcessed": 15,
      "itemsTotal": 42
    },
    "qc": {
      "status": "pending"
    }
  },
  "lock": {
    "pid": 12345,
    "acquiredAt": "2024-01-15T10:00:00Z"
  }
}

State Transitions

pending --> running --> completed
                   --> failed
                   --> skipped (if previous phase failed)

Resumability Rules

1. On start: check for existing state file
2. If state exists and configFingerprint matches: resume from last incomplete phase
3. If state exists and configFingerprint differs: warn user, offer fresh start or resume
4. If lock exists: check if PID is alive. If dead, clear stale lock. If alive, abort.

5. Model Tier Allocation

Assign models by cognitive load, not by importance.

Mechanical / IO:     haiku    (parser, scanner, formatter, counter)
Reasoning / AI:      sonnet   (summarizer, extractor, reviewer, linter)
Judgment / QC:       opus     (coordinator, architect, final reviewer)

Pipeline Model Assignment Example

Phase 1: Discover files          → haiku  (just glob + read)
Phase 2: Parse and chunk         → haiku  (mechanical splitting)
Phase 3: Analyze each chunk      → sonnet (requires judgment)
Phase 4: QC all analyses         → sonnet (verify, not create)
Phase 5: Synthesize final report → opus   (cross-reference, prioritize)

Cost Optimization

6. Error Propagation

Rules

1. Phase fails -> STOP. Set status "failed" + error message in state. Do not continue to next phase.
2. Agent fails -> report and continue (in parallel dispatch). One agent's failure shouldn't block others.
3. Retry fails -> escalate. After max retries, surface the failure to the user with full context.
4. Never swallow errors silently. Every failure must be visible in the final output.

Error Report Format

## Pipeline Error

**Phase**: {phase_name}
**Status**: FAILED
**Error**: {error_message}

### Context
- Items processed before failure: {N} of {M}
- Last successful item: {item_id}
- Time elapsed: {duration}

### Recovery Options
1. Fix the finding and run `/command --resume` to continue from this phase
2. Run `/command --restart` to start fresh
3. Run `/command --skip-phase {phase_name}` to skip this phase (not recommended)

Fallback Paths

Always offer a manual fallback when automation fails:

## Fallback
If the pipeline fails after 3 retries:
1. Output all successfully processed items
2. List failed items with error context
3. Suggest manual analysis for failed items

7. Pattern Selection Guide