/orchestration

name: orchestration
description: "Multi-agent workflow patterns: parallel dispatch, pipelines, QC gates, retries."
version: 0.1.0
user-invocable: false

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**: | Decision | Recommendation | |----------|---------------| | Max parallel agents | 6 (diminishing returns above this) | | Timeout per agent | 120 seconds for sonnet, 300 for opus | | Failure handling | Continue with other agents if one fails | | Result merging | Deduplicate findings that appear in multiple agents |

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**: | Decision | Recommendation | |----------|---------------| | Phase boundary | Each phase should have a clear input type and output type | | Error propagation | Fail fast -- don't continue past a failed phase | | State passing | Use structured output (JSON) between phases | | Resumability | Track phase status for long pipelines (see section 4) |

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**: | Verdict | Condition | Action | |---------|-----------|--------| | PASS | All checks green | Deliver output directly | | WARN | Minor issues (< 3 low-severity) | Deliver output with warnings section | | FAIL | Any critical finding OR > 5 total findings | Stop, report what failed, suggest re-run |

**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**: | Decision | Recommendation | |----------|---------------| | Max retries | 3 (rarely succeeds after 3 if it failed 3 times) | | Error context | Include specific failures, not "try again" | | Scope of retry | Fix only failures, preserve passing output | | Cost cap | Each retry costs full agent invocation -- budget accordingly |

2. Shared Partials for DRY

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

When to Extract

| Situation | Extract? | |-----------|----------| | Same logic in 3+ commands | Yes -- always extract | | Same logic in 2 commands, complex (> 20 lines) | Yes -- extract | | Same logic in 2 commands, simple (< 10 lines) | No -- duplication is fine | | Logic used by 1 command but might be reused | No -- wait until it's actually reused |

Good Candidates for Extraction

| Partial | What it contains | Who includes it | |---------|-----------------|-----------------| | `shared/load-config.md` | Read and validate plugin config file | All commands that need config | | `shared/discover-files.md` | Find target files by pattern/extension | Commands that scan the repo | | `shared/validate-prereqs.md` | Check tool availability, environment | Commands with external dependencies | | `share