Multi-agent orchestration patterns for delegation, coordination, and conflict resolution
From sdlcnpx claudepluginhub jwilger/claude-code-plugins --plugin sdlcThis skill uses the workspace's default tool permissions.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Version: 1.0.0 Portability: Medium
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:
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:
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)
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:
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]
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:
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:
Resolution protocol:
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
Rationale: Clear boundaries prevent responsibility diffusion and maintain workflow integrity.
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:
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
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:
def can_proceed_to_implementation(state):
return (
state.test == "Failing (expected)" and
state.types == "Created" and
state.domain_review_after_test == "Approved"
)
if not can_proceed_to_implementation(state):
return "GATE FAILED: Prerequisites not met"
Scenario: Long-running agent needs user input mid-task.
Pause signal:
{
"status": "PAUSED",
"reason": "USER_INPUT_NEEDED",
"question": "Found 3 validation approaches. Which should I use?",
"options": ["Strict RFC compliance", "Lenient", "Custom rules"],
"state_checkpoint": "agent-123-checkpoint-456"
}
Orchestrator response:
Resume:
{
"status": "RESUMING",
"checkpoint": "agent-123-checkpoint-456",
"user_answer": "Strict RFC compliance",
"instruction": "Continue with user's choice"
}
Scenario: Two agents disagree on approach.
Debate protocol:
Round 1:
Agent A: States position
Agent B: States counter-position
Orchestrator: Summarizes both positions clearly
Round 2:
Agent A: Responds to B's points
Agent B: Responds to A's points
Orchestrator: Proposes compromise
If consensus:
Proceed with agreed approach
If no consensus after Round 2:
Orchestrator: Escalate to user
User: Makes decision
Agents: Implement user's decision
Example:
TestWriter: "Test should use String for email (simpler)"
DomainModeler: "Email type required (prevents invalid emails)"
Orchestrator: "TestWriter values simplicity, DomainModeler values safety"
Round 2:
TestWriter: "Email type adds complexity without immediate benefit"
DomainModeler: "Complexity is minimal, benefit is compile-time validation"
Orchestrator: "Compromise: Use Email type now (DomainModeler creates it), keep it simple"
Consensus: Use Email type (DomainModeler wins on principle)
Works well with:
Prerequisites:
Problem: "Quick fix" - orchestrator edits file directly
Solution: Always delegate. No exceptions.
Problem: "Fix the bug" without specifying which bug, which file, what error
Solution: Use context template. Be exhaustively specific.
Problem: "I know domain review isn't needed here"
Solution: Gates exist for discipline. If agent rejects, you skipped something.
Problem: Agents debate for 5+ rounds without resolution
Solution: Escalate after round 2. User breaks tie.
Problem: "Continue where you left off" to resumed agent
Solution: Provide full context, even on resume. Agents don't remember.
User: "Add email validation to User model"
Orchestrator:
State: Starting new feature
Next: Write failing test
Orchestrator → TestWriter:
CONTEXT: FIRST_TEST
TASK: Create failing test for email validation
FILE: tests/user_test.rs
REQUIREMENTS:
- Test User::new() with invalid email
- Expect validation error
CONSTRAINTS:
- Use domain types (Email, not String)
- One assertion per test
TestWriter: (creates test)
Result: test_user_rejects_invalid_email FAILS
Error: "Email type not found"
Orchestrator:
State: Test written, domain review needed
Orchestrator → DomainModeler:
CONTEXT: AFTER_RED
RED_COMPLETE:
- Test: test_user_rejects_invalid_email
- Error: "Email type not found"
TASK: Review test, create Email type
FILE: src/domain/types.rs
DomainModeler: (reviews test, creates Email type)
Output: Email type created with validation
Result: APPROVE - No domain concerns
Orchestrator:
State: Types created, ready for implementation
Orchestrator → Implementer:
CONTEXT: IMPLEMENTATION
RED_COMPLETE:
- Test: test_user_rejects_invalid_email
- Error: "unimplemented"
DOMAIN_REVIEW: PASSED
- Email type created in src/domain/types.rs
TASK: Implement User::new() to validate email
FILES:
- src/domain/user.rs (implementation)
- src/domain/types.rs (use Email type)
Implementer: (implements validation)
Result: test_user_rejects_invalid_email PASSES
Orchestrator:
State: Implementation complete, domain review needed
Orchestrator → DomainModeler:
CONTEXT: AFTER_GREEN
GREEN_COMPLETE:
- Test: test_user_rejects_invalid_email PASSES
- Files: src/domain/user.rs, src/domain/types.rs
TASK: Review implementation for domain integrity
DomainModeler: (reviews implementation)
Output: APPROVE - Email newtype used correctly, validation at construction
Orchestrator:
State: Cycle complete, feature implemented
Report: Email validation added with domain-rich types
Orchestrator → TestWriter: "Create test for order total calculation"
TestWriter: (creates test using float for money)
test_order_calculates_total() { order.add_item(10.99, 2); assert_eq!(order.total(), 21.98); }
Orchestrator → DomainModeler: "Review test"
DomainModeler: CONCERN - Primitive obsession
Money should be Money type, not float
Floats have precision issues (0.1 + 0.2 != 0.3)
Orchestrator facilitates:
TestWriter: Why float?
DomainModeler: Why Money type?
Round 1:
TestWriter: "Float is simpler, everyone understands money as numbers"
DomainModeler: "Money type prevents precision errors and enforces currency"
Orchestrator: "TestWriter values simplicity, DomainModeler values correctness"
Round 2:
TestWriter: "Can we use Decimal instead of custom Money type?"
DomainModeler: "Acceptable compromise - Decimal fixes precision, maintains simplicity"
Consensus: Use Decimal type (compromise)
Orchestrator → TestWriter: "Revise test with Decimal"
TestWriter: (revises)
Orchestrator → DomainModeler: "Re-review"
DomainModeler: APPROVE
Orchestrator → Implementer: "Implement payment processing"
Implementer: (starts work, encounters decision point)
Implementer output:
AWAITING_USER_INPUT
{
"context": "Payment processing needs retry strategy",
"checkpoint": "impl-payment-checkpoint-1",
"questions": [{
"question": "How should we handle payment failures?",
"options": [
"Immediate failure (no retries)",
"Retry 3 times with exponential backoff",
"Retry indefinitely until success"
]
}]
}
Orchestrator: (detects pause)
1. Asks user via AskUserQuestion
2. User chooses: "Retry 3 times with exponential backoff"
Orchestrator → Implementer: (resume)
USER_INPUT_RESPONSE: "Retry 3 times with exponential backoff"
CHECKPOINT: "impl-payment-checkpoint-1"
INSTRUCTION: "Continue implementation with user's retry strategy"
Implementer: (resumes with context, completes work)
Result: Payment processing implemented with 3-retry strategy
Source Documentation:
Related Skills:
External Resources:
Extraction Source: sdlc/commands/shared/orchestration.md Extraction Date: 2026-02-04 Last Updated: 2026-02-04 Compatibility: Medium portability (requires multi-agent framework) License: MIT