| 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
- Separation of Concerns: QA validates but doesn't write product code
- Independent Verification: Catches what implementer missed
- Bias Prevention: Fresh eyes on commit messages, patterns
- Evidence in Linear: QA posts final evidence + verdict to Linear (system of record)
QA Review Checklist
## QA Review - PR #XXX for REN-YYY
### Commit Message Validation
- [ ] Ticket reference in subject line
- [ ] Proper format: `type(scope): description [REN-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/REN-{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: REN-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 REN-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 |
