/orchestration-patterns

name: orchestration-patterns
description: Agentic orchestration patterns for long-running tasks. Implements evidence-based delivery and Simon Willison's agent loop. Use when managing multi-step work, coordinating subagents, or orchestrating PR workflows.
allowed-tools: Read, Bash, Grep, Glob, Task

Orchestration Patterns Skill

Purpose

Codify evidence-based delivery and iterative agent loop for orchestrating complex, long-running tasks. These patterns ensure verifiable progress and intelligent escalation.

When This Skill Applies

Invoke this skill when:

• Orchestrating multi-step implementation tasks
• Managing work across multiple subagents
• Running long-running sessions that need checkpoints
• Preparing PRs for merge (mandatory QAS gate)
• Coordinating team handoffs

Simon Willison's Agent Loop

**Core Philosophy**: "Iterate until success or blocked, then escalate."

┌─────────────────────────────────────────────────────────┐
│  THE AGENT LOOP (for every task)                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. GOAL DEFINITION                                     │
│     └─ Clear acceptance criteria (from BSA/ticket)      │
│                                                         │
│  2. PATTERN DISCOVERY                                   │
│     └─ Search codebase, docs, previous sessions         │
│     └─ Use: pattern-discovery skill (auto-invoked)      │
│     └─ Or: /search-pattern for explicit code search     │
│                                                         │
│  3. ITERATIVE EXECUTION LOOP:                           │
│     ┌─────────────────────────────────────────────┐     │
│     │  Implement approach                         │     │
│     │       ↓                                     │     │
│     │  Run validation (yarn ci:validate)          │     │
│     │       ↓                                     │     │
│     │  If PASS → proceed to evidence              │     │
│     │  If FAIL → analyze error, adjust, repeat    │     │
│     │  If BLOCKED → escalate to TDM with context  │     │
│     └─────────────────────────────────────────────┘     │
│                                                         │
│  4. EVIDENCE ATTACHMENT                                 │
│     └─ Attach proof to Linear (see templates below)     │
│                                                         │
│  5. QAS GATE (MANDATORY before merge)                   │
│     └─ Invoke QAS subagent for independent review       │
│                                                         │
└─────────────────────────────────────────────────────────┘

Evidence-Based Delivery

**Core Principle**: "All work requires verifiable evidence - no 'trust me, it works'"

Evidence Types

| Type | What It Proves | Example | | -------------- | -------------------------- | -------------------------- | | Test Results | Code works as expected | `yarn ci:validate` output | | Screenshots | UI changes are correct | Before/after comparison | | Command Output | Operations completed | Build logs, migration logs | | QAS Report | Independent verification | QA validation markdown | | Session ID | Full audit trail available | Claude Code session ref |

Phase Evidence Requirements

| Phase | Evidence Required | Linear Template | | ----------- | ------------------------------ | ---------------------- | | **Dev** | Test results, command output | Dev Evidence Template | | **Staging** | UAT validation or N/A + reason | Staging Template | | **Done** | QAS report, merge confirmation | Done Evidence Template |

QAS Pre-Merge Gate

**MANDATORY**: Before merging any PR, invoke QAS for independent review.

Why QAS Gate Matters

1. **Separation of Concerns**: QAS validates but doesn't write product code 2. **Independent Verification**: Catches what implementer missed 3. **Bias Prevention**: Fresh eyes on commit messages, patterns 4. **Evidence in Linear**: QAS posts final evidence + verdict to Linear (system of record)

QAS Invocation Pattern

# After implementation complete, before merge:
Task tool: QAS subagent
Prompt: "Review PR #XXX for {{TICKET_PREFIX}}-YYY. Validate:
  - Commit message format (ticket in subject line)
  - Code patterns (RLS, naming, structure)
  - CI status (all checks passing)
  - Evidence attachments in Linear
  Generate validation report to docs/agent-outputs/qa-validations/"

QAS Output Location

All QAS reports go to: `docs/agent-outputs/qa-validations/{{TICKET_PREFIX}}-{number}-qa-validation.md`

Escalation Patterns

When to Escalate

| Condition | Escalate To | Include | | ---------------------- | ----------- | --------------------------- | | Blocked > 4 hours | TDM | Full context, attempts made | | Architecture ambiguity | ARCHitect | Options, trade-offs | | Cross-team dependency | TDM | Which teams, what's blocked | | Security concern | SecEng | Specific risk, evidence |

Escalation Template

**Escalation Required**

**Blocked On**: [specific blocker]
**Attempts Made**:

1. [what you tried]
2. [what you tried]

**Context**:

- Ticket: {{TICKET_PREFIX}}-XXX
- Session ID: [if available]
- Time blocked: X hours

**Request**: [specific ask - what do you need?]

Long-Running Task Checkpoints

For tasks spanning multiple tool calls or sessions:

Checkpoint Pattern

Every 10-15 tool calls:
1. Update todo list with current progress
2. If nearing context limit, summarize state
3. If handoff needed, provide continuation context

At session boundaries:
1. Summarize completed work
2. List remaining items
3. Document any blockers
4. Attach evidence to Linear

State Preservation

**Session Chec