Agent Collaboration Patterns

Effective multi-agent workflows for complex tasks.

Core Collaboration Principles
Pattern Catalog
Handoff Best Practices
Anti-Patterns to Avoid
Collaboration Decision Tree
Measuring Success
Advanced Patterns
Next Steps

Core Collaboration Principles

1. Sequential Handoffs

Agents pass work from one specialist to another in sequence.

@planner → @codebase → @review → @docs

When to use:

Clear linear dependency chain
Each phase builds on previous
No parallel work possible

2. Orchestrated Workflows

Orchestrator coordinates multiple agents and phases.

@orchestrator
  ├─ Phase 1: @codebase (backend)
  ├─ Phase 2: @codebase (frontend)
  ├─ Phase 3: @review (security)
  ├─ Phase 4: @codebase (fixes)
  └─ Phase 5: @docs (documentation)

When to use:

Complex multi-domain tasks
Multiple implementation phases
Need coordination and status tracking

Agent cycles back for improvements based on feedback.

@codebase → @review → @codebase → @review ✓

When to use:

Security-critical features
Performance optimization
Quality gate enforcement

4. Parallel-then-Merge

Multiple agents work independently, then integrate.

@codebase (backend) ─┐
                     ├─→ @orchestrator (merge) → @review
@codebase (frontend) ─┘

When to use:

Independent components
Different technical stacks
Speed optimization

Pattern Catalog

Pattern: Feature Development

Goal: Implement new feature from idea to production-ready.

Flow:

@planner     - Analyze requirements, propose architecture
@codebase    - Implement with tests
@review      - Security and quality audit
@codebase    - Address review findings
@docs        - API documentation and guides
@review      - Final approval

Example:

User: @planner Design user notification system with email and push

↓ Agent analyzes and proposes architecture ↓

User: @codebase Implement the plan

↓ Agent builds feature with tests ↓

User: @review Security audit

↓ Agent identifies rate limiting gap ↓

User: @codebase Add rate limiting

↓ Agent implements fix ↓

User: @docs Document API endpoints

↓ Complete! ↓

Pattern: Refactoring Large Module

Goal: Safely refactor without breaking functionality.

Flow:

@planner     - Analyze current code, identify issues
@planner     - Propose incremental refactoring plan
@codebase    - Execute phase 1
@review      - Verify no regressions
@codebase    - Execute phase 2
@review      - Verify no regressions
...repeat...
@docs        - Update architecture docs

Key Success Factor: Incremental changes with continuous validation.

Pattern: Production Incident

Goal: Debug and fix production issue quickly.

Flow:

@planner     - Analyze logs, identify root cause
@codebase    - Implement hotfix
@review      - Quick security check
@docs        - Update runbook
@planner     - Plan long-term solution

Emergency Mode: Skip formal planning, prioritize speed with review.

Pattern: Technical Debt Reduction

Goal: Systematically reduce technical debt.

Flow:

1. @review      - Audit codebase, identify debt
2. @planner     - Prioritize issues, create roadmap
3. @orchestrator - Coordinate multi-phase cleanup
   ├─ @codebase  - Fix category 1 issues
   ├─ @codebase  - Fix category 2 issues
   └─ @docs      - Update standards

Pattern: API Design

Goal: Design robust, user-friendly API.

Flow:

@docs        - Draft API specification (OpenAPI)
@planner     - Review design, suggest improvements
@codebase    - Implement endpoints
@review      - API security audit
@docs        - Create usage examples
@docs        - Generate client SDKs

Documentation-First Approach: Design API contract before implementation.

Pattern: Performance Optimization

Goal: Improve system performance systematically.

Flow:

@planner     - Analyze metrics, identify bottlenecks
@codebase    - Add performance tests/benchmarks
@codebase    - Implement optimization
@codebase    - Measure improvement
@review      - Verify no functionality broken
If not sufficient: repeat steps 3-5
@docs        - Document performance characteristics

Pattern: Security Hardening

Goal: Comprehensive security improvement.

Flow:

@review      - Security audit (OWASP Top 10)
@planner     - Prioritize findings
@codebase    - Implement critical fixes
@review      - Verify fixes
@codebase    - Implement high priority
@review      - Verify fixes
...continue...
@docs        - Security documentation
/security-audit - Generate final report

Pattern: Microservices Migration

Goal: Extract service from monolith.

Flow:

1. /architecture-review - Assess current architecture
2. @planner            - Design migration strategy
3. @orchestrator       - Coordinate migration phases
   ├─ Phase 1: @codebase - Extract domain logic
   ├─ Phase 2: @codebase - Database split
   ├─ Phase 3: @codebase - API layer
   ├─ Phase 4: @codebase - Data migration
   ├─ Phase 5: @review   - Integration testing
   └─ Phase 6: @docs     - Architecture docs

Pattern: Team Leadership Decision

Goal: Make informed technical or people decision.

Flow:

@em-advisor   - Analyze situation, provide framework
@planner      - Technical feasibility (if applicable)
@em-advisor   - Communication strategy
@docs         - Document decision (ADR/memo)

Example Decisions:

Technology adoption
Team restructuring
Promotion decisions
Performance improvement plans

Handoff Best Practices

Clear Context Passing

✅ Good:
@review Audit payment processing module (src/payments/) for:
- PCI compliance
- Proper error handling
- Rate limiting
- No sensitive data in logs

❌ Poor:
@review Check the payment code

Explicit Requirements

✅ Good:
@codebase Implement rate limiter:
- 100 requests/hour per user
- Redis-backed
- Exponential backoff
- Admin bypass capability

❌ Poor:
@codebase Add rate limiting

Accept Context Updates

When agents propose updating AGENTS.md, accept to maintain continuity.

Anti-Patterns to Avoid

❌ Skipping Planning

Bad: @codebase Just build a user system
Better: @planner Design user system → @codebase Implement

❌ No Review Step

Bad: @codebase Implement → Deploy
Better: @codebase Implement → @review Audit → Deploy

❌ Documentation Afterthought

Bad: Build everything → @docs Document at the end
Better: Interleave documentation throughout

❌ Over-Orchestration

Bad: @orchestrator for every small task
Better: Use @orchestrator only for multi-phase, multi-domain work

❌ Wrong Agent for Task

Bad: @em-advisor write code
Better: Each agent for their specialization

Collaboration Decision Tree

Is task complex with multiple phases?
├─ YES → Use @orchestrator
└─ NO
    │
    Is code change needed?
    ├─ YES
    │   │
    │   Is security critical?
    │   ├─ YES → @planner → @codebase → @review → @codebase
    │   └─ NO → @codebase → @review
    │
    └─ NO
        │
        Is planning/analysis needed?
        ├─ YES → @planner
        └─ NO
            │
            Is documentation needed?
            ├─ YES → @docs
            └─ NO → @review or @em-advisor

Measuring Success

Effective Collaboration Indicators

✅ Clear handoffs between agents
✅ Each agent used for their specialization
✅ Issues caught in review phase, not production
✅ Documentation stays current
✅ Plans approved before implementation

Red Flags

⚠️ Frequently rewriting implementations
⚠️ Security issues found late
⚠️ Documentation outdated
⚠️ Skipping review steps
⚠️ Using wrong agent for tasks

Advanced Patterns

Pattern: A/B Test Implementation

@planner     - Design experiment
@codebase    - Implement both variants
@codebase    - Add feature flags
@codebase    - Add metrics tracking
@review      - Verify statistical validity
@docs        - Document experiment setup

Pattern: API Version Migration

@docs        - Document v1 → v2 differences
@planner     - Design migration strategy
@codebase    - Implement v2
@codebase    - Add deprecation warnings to v1
@docs        - Client migration guide

Pattern: Incident Postmortem

@planner     - Analyze incident timeline
@review      - Identify root causes
@codebase    - Implement preventive measures
@docs        - Write postmortem report
@docs        - Update runbooks

Next Steps

Workflows - See these patterns in action
Agents Guide - Deep dive into each agent
Prompts - Slash commands for common patterns

Agent Collaboration Patterns

Table of Contents

Core Collaboration Principles

1. Sequential Handoffs

2. Orchestrated Workflows

3. Iterative Refinement

4. Parallel-then-Merge

Pattern Catalog

Pattern: Feature Development

Pattern: Refactoring Large Module

Pattern: Production Incident

Pattern: Technical Debt Reduction

Pattern: API Design

Pattern: Performance Optimization

Pattern: Security Hardening

Pattern: Microservices Migration

Pattern: Team Leadership Decision

Handoff Best Practices

Clear Context Passing

Explicit Requirements

Accept Context Updates

Anti-Patterns to Avoid

❌ Skipping Planning

❌ No Review Step

❌ Documentation Afterthought

❌ Over-Orchestration

❌ Wrong Agent for Task

Collaboration Decision Tree

Measuring Success

Effective Collaboration Indicators

Red Flags

Advanced Patterns

Pattern: A/B Test Implementation

Pattern: API Version Migration

Pattern: Incident Postmortem

Next Steps