Orchestration Patterns

Blue Gardener agents work together following proven orchestration patterns. This guide shows you how to coordinate multiple agents for complex workflows.

Agent Types

Orchestrators

Coordinate workflows and delegate to specialists:

blue-feature-specification-analyst - Requirements & planning
blue-architecture-designer - Technical design
blue-refactoring-strategy-planner - Refactoring strategy
blue-extraction-boundary-designer - Package/module boundary design for extractions
blue-app-quality-gate-keeper - Quality audits
blue-implementation-review-coordinator - Review coordination

Specialists

Execute specific tasks in their domain:

Development (9 agents) - Build features
Quality (11 agents) - Ensure code quality
Infrastructure (9 agents) - DevOps & tooling
Blockchain (11 agents) - Smart contracts
Configuration (1 agent) - Platform setup

View all agents →

Core Patterns

Pattern 1: Feature Development

Use when: Building new features from requirements to release

mermaid

flowchart TD
    User[User Request] --> Spec[1. Feature Spec Analyst]
    Spec --> Arch[2. Architecture Designer]
    Arch --> Impl[3. Implementation Specialists]
    Impl --> Review[4. Review Coordinator]
    Review --> Done[Feature Complete]

    style User fill:#e1f5ff
    style Done fill:#d4edda

Flow:

@blue-feature-specification-analyst
- Clarifies requirements
- Defines acceptance criteria
- Creates implementation plan
@blue-architecture-designer
- Designs technical approach
- Recommends technologies
- Identifies needed specialists
Implementation Specialists (parallel)
- @blue-react-developer (frontend)
- @blue-node-backend-implementation-specialist (backend)
- @blue-api-integration-expert (API layer)
@blue-implementation-review-coordinator
- Runs quality audits
- Routes fixes to specialists
- Iterates until standards met

Pattern 2: Quality Assurance

Use when: Verifying code quality before releases

mermaid

flowchart TD
    Feature[Feature Complete] --> ReviewCoord[Review Coordinator]
    ReviewCoord --> GateKeeper[Quality Gate Keeper]
    GateKeeper --> Audits[Specialist Audits]
    Audits --> Findings[Analyze Findings]
    Findings --> Fixes[Route to Specialists]
    Fixes --> ReAudit{Re-Audit}
    ReAudit -->|Issues| Fixes
    ReAudit -->|Pass| SignOff[Sign-Off]

    style Feature fill:#e1f5ff
    style SignOff fill:#d4edda

Flow:

@blue-implementation-review-coordinator
- Coordinates review process
- Manages feedback loops
Delegates to @blue-app-quality-gate-keeper
- Runs comprehensive audits
- Coordinates specialist reviews
Specialist Audits (parallel)
- @blue-frontend-code-reviewer (code quality)
- @blue-security-specialist (security)
- @blue-performance-specialist (performance)
- @blue-accessibility-specialist (accessibility)
Route Fixes
- Issues sent back to implementation specialists
- Iterative fix-verify cycles
Final Sign-Off
- All critical issues resolved
- Quality standards met

Pattern 3: Refactoring

Use when: Planning large-scale code changes

mermaid

flowchart TD
    Plan[Refactoring Plan] --> Phase1[Phase 1: Setup]
    Phase1 --> Verify1[Verify Phase 1]
    Verify1 --> Phase2[Phase 2: Migration]
    Phase2 --> Verify2[Verify Phase 2]
    Verify2 --> Phase3[Phase 3: Cleanup]
    Phase3 --> Final[Final Verification]

    style Plan fill:#e1f5ff
    style Final fill:#d4edda

Flow:

@blue-codebase-analyst (recommended for non-trivial scope)
- Produces Code Inventory: edge cases, data flow, coupling
@blue-extraction-boundary-designer (when extracting a package/module)
- Produces Boundary Specification: API, adapters, migration map
@blue-refactoring-strategy-planner
- Creates phased plan using the artifacts above
- Identifies risks and rollback options
Phase 1: Setup
- Preparation work
- Add abstractions
- Write tests
@blue-refactoring-verification-specialist
- Gate: coverage matrix vs. Code Inventory before next phase
@blue-implementation-review-coordinator
- Verify phase complete
- Check for regressions
Phase 2: Migration
- Incremental changes
- Coexistence period
Verify Phase 2
- @blue-refactoring-verification-specialist + quality checks
- Behavior preservation
Phase 3: Cleanup
- Remove old code
- Final optimizations
Final Verification
- @blue-implementation-review-coordinator
- Full verification matrix
- Sign-off

Recipe: Library/Pattern Migration (e.g., Jotai → Redux)

Use this recipe for any “replace X with Y” migration (state management, routing, API client, logging, etc.). Treat the example names as parameters, not defaults.

Inputs (parameters)

Source: <SourceLibOrPattern> (e.g., Jotai)
Target: <TargetLibOrPattern> (e.g., Redux)
Scope: directories/packages/features in-scope + explicit out-of-scope
Constraints: timeline, compatibility, risk tolerance
Verification: what must be proven (typecheck/tests/perf/a11y/security)

Worker sequence (manager-run)

Analysis + strategy
- @blue-codebase-analyst (Code Inventory for complex scope)
- @blue-extraction-boundary-designer (if extracting shared modules)
- @blue-refactoring-strategy-planner
- Output: phased plan with verification + rollback after each phase
Target architecture
- @blue-architecture-designer
- Output: target architecture + task assignment to specialists
Implementation (parallel where safe)
- @blue-state-management-expert (if the migration is state-related)
- @blue-react-developer (UI/component changes)
- @blue-api-integration-expert (if the migration touches data fetching/cache)
- (Add backend/infra specialists if the migration affects those areas)
Quality gate + iteration
- @blue-app-quality-gate-keeper (audit selection + consolidated findings)
- @blue-implementation-review-coordinator (route fixes, iterate, sign-off)
Optional tests (recommended for high-risk migrations)
- @blue-unit-testing-specialist
- @blue-e2e-testing-specialist

Platform-agnostic usage

Use the orchestrator agents to produce a plan and then have the main agent call the recommended specialist agents in sequence or in parallel (where safe). No platform-specific commands are required.

Pattern 4: Backend Development

Use when: Building backend services

mermaid

flowchart TD
    Arch[Architecture Designer] --> DB[Database Architect]
    DB --> ImplParallel[Implementation]
    ImplParallel --> Backend[Backend Specialist]
    ImplParallel --> DBImpl[Database Specialist]
    Backend --> Review[Review Coordinator]
    DBImpl --> Review
    Review --> Done[Service Complete]

    style Arch fill:#e1f5ff
    style Done fill:#d4edda

Flow:

@blue-architecture-designer
- System design
- Database selection
@blue-database-architecture-specialist
- Schema design
- Scaling strategy
Implementation (parallel)
- @blue-node-backend-implementation-specialist (API)
- @blue-relational-database-specialist (database)
@blue-implementation-review-coordinator
- Code quality review
- Security audit
- Performance check

Complexity Scaling

Task	Agents	Example
Trivial	1-2	Bug fix: developer + reviewer
Simple	2-3	Small feature: developer + stylist + reviewer
Standard	4-6	Feature: spec + arch + implementation + review
Complex	7-9	Major feature: add security, testing, performance
Enterprise	10+	Full release: all orchestrators + comprehensive specialists

Best Practices

Start with Orchestrators

For complex work, begin with planning orchestrators:

✅ Good:

1. @blue-feature-specification-analyst analyze this requirement
2. @blue-architecture-designer design the system
3. Implementation with specialists
4. @blue-implementation-review-coordinator verify quality

❌ Bad:

Jump straight to implementation without planning

Use Parallel Execution

When specialists can work independently:

@blue-react-developer     → Build components
@blue-ui-styling-specialist → Style components  } Execute simultaneously
@blue-state-management-expert → Set up state

Iterate Through Quality Checks

Allow feedback cycles:

Implementation → Review → Fix → Re-Review → Sign-off

Don't skip iterations when issues are found.

Escalate Appropriately

Know when to involve the user:

Multiple valid approaches (architectural decisions)
Ambiguous requirements
Persistent quality issues after multiple iterations
Trade-offs requiring user input

Real-World Examples

Example 1: Building Authentication

User: "Build user authentication with email and password"

1. @blue-feature-specification-analyst
   → Clarifies: session management, password rules, forgot password, etc.

2. @blue-architecture-designer
   → Designs: JWT tokens, refresh flow, database schema

3. Implementation (parallel):
   → @blue-react-developer: Login/signup forms
   → @blue-node-backend-implementation-specialist: Auth API
   → @blue-security-specialist: Secure password hashing

4. @blue-implementation-review-coordinator
   → Security audit critical
   → Accessibility check on forms
   → Code review
   → Sign-off when standards met

Example 2: Performance Optimization

User: "App is slow, please optimize"

1. @blue-performance-specialist
   → Analyzes: bundle size, render performance, API calls
   → Identifies: issues and optimization opportunities

2. Implementation:
   → @blue-react-developer: Code splitting, memoization
   → @blue-api-integration-expert: Request optimization

3. @blue-implementation-review-coordinator
   → Verifies: performance improvements
   → Ensures: no regressions
   → Measures: metrics before/after

Example 3: Database Migration

User: "Migrate from MongoDB to PostgreSQL"

1. @blue-refactoring-strategy-planner
   → Creates phased migration plan
   → Identifies risks

2. @blue-database-architecture-specialist
   → Designs PostgreSQL schema
   → Plans data migration

3. Phase 1: Dual-write setup
   → @blue-node-backend-implementation-specialist

4. @blue-implementation-review-coordinator: Verify Phase 1

5. Phase 2: Migrate reads
6. Verify Phase 2
7. Phase 3: Remove MongoDB
8. Final verification

Troubleshooting

Too Many Agents Involved

Problem: Workflow becoming complex

Solution: Scale back to fewer orchestrators. For simple tasks, use specialists directly.

Issues Recurring Across Iterations

Problem: Same issues after multiple fix cycles

Solution: Escalate to architecture designer - likely an architectural problem.

Unclear Which Orchestrator to Use

Problem: Don't know where to start

Solution: Default to @blue-feature-specification-analyst - it will delegate to others as needed.

Next Steps

Agent Catalog →
Browse all agents and their capabilities

CLI Reference →
Complete command documentation

Orchestration Patterns ​

Agent Types ​

Orchestrators ​

Specialists ​

Core Patterns ​

Pattern 1: Feature Development ​

Pattern 2: Quality Assurance ​

Pattern 3: Refactoring ​

Recipe: Library/Pattern Migration (e.g., Jotai → Redux) ​

Inputs (parameters) ​

Worker sequence (manager-run) ​

Platform-agnostic usage ​

Pattern 4: Backend Development ​

Complexity Scaling ​

Best Practices ​

Start with Orchestrators ​

Use Parallel Execution ​

Iterate Through Quality Checks ​

Escalate Appropriately ​

Real-World Examples ​

Example 1: Building Authentication ​

Example 2: Performance Optimization ​

Example 3: Database Migration ​

Troubleshooting ​

Too Many Agents Involved ​

Issues Recurring Across Iterations ​

Unclear Which Orchestrator to Use ​

Next Steps ​

Orchestration Patterns

Agent Types

Orchestrators

Specialists

Core Patterns

Pattern 1: Feature Development

Pattern 2: Quality Assurance

Pattern 3: Refactoring

Recipe: Library/Pattern Migration (e.g., Jotai → Redux)

Inputs (parameters)

Worker sequence (manager-run)

Platform-agnostic usage

Pattern 4: Backend Development

Complexity Scaling

Best Practices

Start with Orchestrators

Use Parallel Execution

Iterate Through Quality Checks

Escalate Appropriately

Real-World Examples

Example 1: Building Authentication

Example 2: Performance Optimization

Example 3: Database Migration

Troubleshooting

Too Many Agents Involved

Issues Recurring Across Iterations

Unclear Which Orchestrator to Use

Next Steps