orchestration-protocol

What this skill does

# Orchestration Protocol

**Version:** 1.0.0
**Portability:** Medium

---

## Objective

Defines patterns for orchestrating multiple specialized agents in complex workflows, including delegation strategies, context provision, conflict resolution, and workflow state management.

**Purpose:** Enable coordinated multi-agent systems where a main orchestrator delegates to specialized agents while maintaining workflow integrity and clear responsibility boundaries.

**Scope:**
- **Included:** Delegation patterns, context provision, agent specialization, conflict resolution, workflow coordination
- **Excluded:** Specific agent implementations, tool-specific orchestration APIs

---

## Core Principles

### Principle 1: Orchestrator Delegates, Never Acts Directly

**The Principle:** The main orchestrator coordinates work by delegating to specialized agents but never performs specialized work itself.

**Why this matters:** Mixing orchestration logic with specialized work creates single points of failure and makes systems harder to maintain. Specialization enables focused expertise.

**How to apply:**
- Orchestrator decides WHAT to do and WHO should do it
- Specialized agents decide HOW to do their specific work
- Orchestrator never writes code, edits files, or performs domain-specific tasks
- All specialized work flows through appropriate agents

**Example:**
```
❌ Bad: Orchestrator writes test directly
Orchestrator: (uses Write tool to create test file)

✓ Good: Orchestrator delegates to test-writing agent
Orchestrator: Delegate to TestWriter agent with context:
              "Create test for user authentication"
TestWriter: (writes test using domain knowledge)
```

### Principle 2: Fresh Context Per Agent (Zero Memory Assumption)

**The Principle:** Agents have zero context from the main conversation. Every delegation must include complete context.

**Why this matters:** Agents don't share conversation history. Assuming they know "what we discussed" leads to failures.

**What to provide:**
- File paths being modified
- Current state (what's passing/failing)
- Requirements (what "done" looks like)
- Domain constraints (types to use, patterns to follow)
- Error messages (exact text, not summaries)

**How to apply:**
```
❌ Bad: Vague delegation
"Continue where we left off"
"Fix the issue we discussed"
"You know what to do"

✓ Good: Complete context
"The test at `tests/auth_test.rs:45` fails with error: 'Email type not found'.
Create the Email type in `src/domain/types.rs` using newtype pattern.
Test expects: `Email::new(string) -> Result<Email, ValidationError>`"
```

**Template:**
```
WORKING_DIRECTORY: [Absolute path to project root]
TASK: [What to accomplish]
FILES: [Specific paths]
CURRENT STATE: [What exists, what's failing]
REQUIREMENTS: [Success criteria]
CONSTRAINTS: [Patterns to follow, types to use]
ERROR: [Exact error message if applicable]
```

### Principle 3: Workflow Gates Enforce Discipline

**The Principle:** Agents require explicit context confirmations before proceeding, preventing workflow step skipping.

**Why this matters:** Complex workflows have dependencies. Skipping steps (like domain review) leads to incomplete or incorrect work.

**Gate pattern:**
```
Agent checks for required context marker.
If missing → Reject with "GATE FAILED: Missing [context]"
If present → Proceed with work
```

**Example gates:**
```
Test-writing agent requires:
- Confirmation of acceptance criteria
- OR confirmation previous cycle completed

Implementation agent requires:
- Confirmation test exists and fails
- Confirmation domain review passed

Domain review agent requires:
- Confirmation of which phase is being reviewed (after test or after implementation)
```

**Benefits:**
- Prevents "quick fix" shortcuts
- Forces conscious workflow state tracking
- Makes workflow violations immediately visible
- Documents that required steps occurred

### Principle 4: Domain Expert Has Veto Power

**The Principle:** In multi-agent systems with domain modeling, the domain expert agent has veto authority over design decisions that violate domain principles.

**Why this matters:** Domain integrity is foundational. Compromising it for expediency creates technical debt that compounds.

**Domain veto authority covers:**
- Primitive obsession (String where Email type should exist)
- Invalid states representable (type allows impossible situations)
- Parse-don't-validate violations
- Domain boundary violations

**Resolution protocol:**
1. Domain raises concern
2. Affected agent responds with rationale
3. Orchestrator facilitates discussion
4. Seek compromise
5. If no consensus after 2 rounds → Escalate to user

**Example:**
```
TestWriter: Creates test using `String` for email parameter
  ↓
DomainReviewer: VETO - Primitive obsession. Use Email type.
  ↓
TestWriter: "Email type doesn't exist yet, using String for now"
  ↓
DomainReviewer: "That's why I review BEFORE implementation - so I can create Email type"
  ↓
Orchestrator: "DomainReviewer will create Email type, TestWriter will revise test to use it"
  ↓
TestWriter: Revises test with Email type
  ↓
DomainReviewer: Creates Email type
  ↓
Consensus reached, proceed
```

---

## Constraints and Boundaries

### DO (Orchestrator):
- Decide which agent handles which task
- Provide complete context to every agent
- Enforce workflow gates
- Facilitate agent conflicts
- Track workflow state
- Monitor for agent pause signals (questions, blockers)
- Ensure required confirmations before proceeding

### DON'T (Orchestrator):
- Perform specialized work (write code, edit files)
- Skip workflow steps ("just this once")
- Assume agents have context ("as we discussed")
- Override domain veto without user consultation
- Let agent debates drag (escalate after 2 rounds)
- Bypass gates ("I know this step isn't needed")

### DO (Specialized Agents):
- Focus on your specialty
- Validate input gates
- Provide clear output
- Signal when user input needed
- Raise concerns when design violates principles
- Document your decisions

### DON'T (Specialized Agents):
- Work outside your specialty
- Assume context from main conversation
- Proceed when gate validation fails
- Silently accept violations of your principles

**Rationale:** Clear boundaries prevent responsibility diffusion and maintain workflow integrity.

---

## Usage Patterns

### Pattern 1: Agent Specialization Hierarchy

**Scenario:** Multi-agent system needs clear responsibility boundaries.

**Specialization by concern:**
```
Orchestrator (coordinates)
├─ TestWriter (test files only)
├─ Implementer (production code only)
├─ DomainModeler (type definitions only)
├─ Reviewer (read-only analysis)
└─ ConfigManager (configuration files only)
```

**Delegation rules:**
- File pattern match → Appropriate agent
- Never multiple agents editing same file simultaneously
- Each agent has exclusive domain
- Orchestrator never bypasses agents

**Example:**
```
User request: "Add user authentication"

Orchestrator analysis:
- Needs: Test (TestWriter) + Types (DomainModeler) + Implementation (Implementer)

Orchestrator workflow:
1. Delegate to TestWriter: "Create failing test for authentication"
2. Wait for TestWriter completion
3. Delegate to DomainModeler: "Review test, create types"
4. Wait for DomainModeler completion
5. Delegate to Implementer: "Implement to pass test"
6. Wait for Implementer completion
7. Delegate to DomainModeler: "Review implementation"
8. Complete when DomainModeler approves
```

### Pattern 2: Workflow State Tracking

**Scenario:** Complex multi-step workflow needs state management.

**State markers:**
```
Workflow phases:
- Test: Not started | In progress | Failing (expected) | Passing | Approved
- Types: Not started | In progress | Created | Approved
- Implementation: Not started | In progress | Test passing | Approved

Current state determines next valid action.
```

**Gate enforcement:**
```python
def can_proceed_to_implementation(state):
    return (
        state.test == "Fa