orchestration-patterns

TEMPLATE: This skill uses {{PLACEHOLDER}} tokens. Replace with your project values before use.

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 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."

1. GOAL DEFINITION
   - Clear acceptance criteria (from BSA/ticket)

2. PATTERN DISCOVERY
   - Search codebase, docs, previous sessions
   - Use: pattern-discovery skill (auto-invoked)

3. ITERATIVE EXECUTION LOOP:
   +---------------------------------------------+
   |  Implement approach                         |
   |       |                                     |
   |  Run validation ({{CI_VALIDATE_COMMAND}})   |
   |       |                                     |
   |  If PASS -> proceed to evidence             |
   |  If FAIL -> analyze error, adjust, repeat   |
   |  If BLOCKED -> escalate to TDM with context |
   +---------------------------------------------+

4. EVIDENCE ATTACHMENT
   - Attach proof to ticket system (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	{{CI_VALIDATE_COMMAND}} 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	Agent session reference

Phase Evidence Requirements

Phase	Evidence Required	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 does not write product code
2. Independent Verification: Catches what implementer missed
3. Bias Prevention: Fresh eyes on commit messages, patterns
4. Evidence in Tickets: QAS posts final evidence and verdict to ticket system

QAS Invocation Pattern

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 ticket system
  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
- 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 ticket

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

1. Start work on {{TICKET_PREFIX}}-XXX
   - Syncs to dev, creates branch, sets context

2. Pattern discovery (skill auto-invokes)
   - Finds relevant patterns before implementation

3. Implementation with agent loop
   - Implement
   - Validate ({{CI_VALIDATE_COMMAND}})
   - Adjust if needed
   - Repeat until passing

4. Pre-PR validation
   - Full validation checklist

5. Create PR with evidence

6. QAS GATE (MANDATORY)
   - Invoke QAS subagent for review
   - Fix any blocking issues
   - Commit QAS report

7. Merge (only after QAS approval)

8. End work
   - Updates ticket, cleans up

Anti-Patterns to Avoid

Anti-Pattern	Why It's Bad	Do This Instead
Skip QAS review	Miss commit message issues	Always invoke QAS pre-merge
No evidence in tickets	No audit trail	Attach evidence every phase
Ignore CI failures	Broken code reaches dev	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

Authoritative References

• AGENTS.md: Agent roles and orchestration model
• Agent Workflow SOP: docs/sop/AGENT_WORKFLOW_SOP.md
• CONTRIBUTING.md: Workflow requirements
• linear-sop skill: Evidence templates for ticket system