orchestration-patterns

name	orchestration-patterns
description	Agentic orchestration patterns for long-running tasks. Implements evidence-based delivery and iterative agent loops. Use when managing multi-step work, coordinating workflows, or orchestrating PR workflows.

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

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

The Agent Loop

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

┌─────────────────────────────────────────────────────────┐
│  THE AGENT LOOP (for every task)                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. GOAL DEFINITION                                     │
│     └─ Clear acceptance criteria (from spec/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 with context         │     │
│     └─────────────────────────────────────────────┘     │
│                                                         │
│  4. EVIDENCE ATTACHMENT                                 │
│     └─ Attach proof to Linear (see templates below)     │
│                                                         │
│  5. QA GATE (MANDATORY before merge)                    │
│     └─ Independent review of PR                         │
│                                                         │
└─────────────────────────────────────────────────────────┘

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
QA Report	Independent verification	QA validation markdown
Session ID	Full audit trail available	Session reference

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	QA report, merge confirmation	Done Evidence Template

QA Pre-Merge Gate

MANDATORY: Before merging any PR, perform independent review.

Why QA Gate Matters

1. Separation of Concerns: QA 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: QA posts final evidence + verdict to Linear (system of record)

QA Review Checklist

## QA Review - PR #XXX for {{TICKET_PREFIX}}-YYY

### Commit Message Validation
- [ ] Ticket reference in subject line
- [ ] Proper format: `type(scope): description [{{TICKET_PREFIX}}-XXX]`

### Code Pattern Validation
- [ ] RLS context helpers used (no direct Prisma)
- [ ] Naming conventions followed
- [ ] File structure matches patterns

### CI Status
- [ ] All checks passing
- [ ] No new lint warnings

### Evidence Verification
- [ ] Dev evidence attached to Linear
- [ ] Acceptance criteria addressed

### Verdict
- [ ] APPROVED for merge
- [ ] CHANGES REQUESTED (list below)

QA Output Location

All QA 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 steps or sessions:

Checkpoint Pattern

Every 10-15 steps:
1. Update progress with current state
2. If nearing limits, 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 Checkpoint**

**Completed**:

- [x] Task 1
- [x] Task 2

**In Progress**:

- [ ] Task 3 (at step X)

**Remaining**:

- [ ] Task 4
- [ ] Task 5

**Blockers**: [if any]

**Next Action**: [specific next step]

Orchestration Workflow Example

# Complete workflow for feature implementation:

1. /start-work {{TICKET_PREFIX}}-XXX
   └─ Syncs to main, creates branch, sets context

2. Pattern discovery (skill auto-invokes or use /search-pattern)
   └─ Finds relevant patterns before implementation

3. [Implementation with agent loop]
   ├─ Implement
   ├─ Validate (yarn ci:validate)
   ├─ Adjust if needed
   └─ Repeat until passing

4. /pre-pr
   └─ Full validation checklist

5. Create PR with evidence

6. [QA GATE - MANDATORY]
   └─ Perform QA review
   └─ Fix any blocking issues
   └─ Commit QA report

7. Merge (only after QA approval)

8. /end-work
   └─ Updates Linear, cleans up

Reference

• AGENT_WORKFLOW_SOP.md: Full agent workflow documentation
• CONTRIBUTING.md: Workflow requirements
• linear-sop skill: Evidence templates for Linear

Anti-Patterns to Avoid

Anti-Pattern	Why It's Bad	Do This Instead
Skip QA review	Miss commit message issues	Always perform QA pre-merge
No evidence in Linear	No audit trail	Attach evidence every phase
Ignore CI failures	Broken code reaches main	Fix in agent loop, don't skip
Force-push without check	May lose teammate's changes	Use --force-with-lease
Continue when blocked	Waste time, no progress	Escalate with context