Orchestration Examples

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Real-world workflows, end to end.                         │
│   See how patterns come together in practice.               │
│                                                             │
│   Each example shows:                                       │
│   • What the user says                                      │
│   • How you orchestrate (internal)                          │
│   • What the user experiences (external)                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Table of Contents

1. Review a PR
2. Implement a Feature
3. Fix a Bug
4. Understand a Codebase
5. Run Tests and Fix Failures

---

Review a PR

User says: "Review PR #123"

Internal Analysis

• Multi-dimensional analysis needed (code quality, security, performance)
• Independent dimensions → Fan-Out
• Need to aggregate findings → Map-Reduce

Execution

# Phase 1: Gather context + parallel analysis (single message)
Task(subagent_type="Explore", description="Get PR context",
     prompt="Fetch PR #123 details, understand what changed and why",
     model="haiku", run_in_background=True)
Task(subagent_type="general-purpose", description="Review quality",
     prompt="Review code quality: readability, patterns, maintainability",
     model="opus", run_in_background=True)  # Critical thinking for review
Task(subagent_type="general-purpose", description="Review security",
     prompt="Review security: injection, auth, data exposure risks",
     model="opus", run_in_background=True)  # Security needs judgment
Task(subagent_type="general-purpose", description="Review performance",
     prompt="Review performance: complexity, queries, memory usage",
     model="opus", run_in_background=True)  # Performance analysis

User Sees

Reviewing PR #123 from multiple angles...

---

## Summary
Adds user profile editing with image upload capability.

## Risk Assessment
- Security: Medium (file upload needs validation)
- Performance: Low
- Breaking Changes: No

## Must Fix
1. Missing file type validation in upload handler (line 47)
   - Could allow malicious file uploads

## Looks Good
- Clean component structure
- Good error handling in UI
- Tests cover happy path

---

Implement a Feature

User says: "Add dark mode to the app"

Internal Analysis

• Need to understand existing styling → Research first
• Multiple independent components → Fan-Out for implementation
• Must integrate at end → Pipeline finish

Execution

# Create tasks with cc-mirror
npx cc-mirror tasks create --subject "Research styling patterns" --description "Find existing theme/CSS architecture"
npx cc-mirror tasks create --subject "Design dark mode approach" --description "Plan theme variables, toggle component"
npx cc-mirror tasks create --subject "Add CSS variables" --description "Dark theme color variables"
npx cc-mirror tasks create --subject "Create toggle component" --description "Theme toggle in header"
npx cc-mirror tasks create --subject "Add persistence" --description "localStorage for preference"
npx cc-mirror tasks create --subject "Wire and test" --description "Integration, final testing"

# Set dependencies
npx cc-mirror tasks update 2 --add-blocked-by 1
npx cc-mirror tasks update 3 --add-blocked-by 2
npx cc-mirror tasks update 4 --add-blocked-by 2
npx cc-mirror tasks update 5 --add-blocked-by 2
npx cc-mirror tasks update 6 --add-blocked-by 3,4,5

# Track in session
TodoWrite([
    {"content": "Research styling patterns", "status": "in_progress", "activeForm": "Researching styling patterns"},
    {"content": "Design dark mode approach", "status": "pending", "activeForm": "Designing dark mode"},
    {"content": "Add CSS variables", "status": "pending", "activeForm": "Adding CSS variables"},
    {"content": "Create toggle component", "status": "pending", "activeForm": "Creating toggle"},
    {"content": "Add persistence", "status": "pending", "activeForm": "Adding persistence"},
    {"content": "Wire and test", "status": "pending", "activeForm": "Wiring and testing"}
])

# Phase 1: Research (haiku for exploration)
Task(subagent_type="Explore", description="Find styling patterns",
     prompt="Find existing theme/styling patterns, CSS architecture",
     model="haiku", run_in_background=True)

# After research completes...
# Phase 2: Plan (opus for design decisions)
Task(subagent_type="Plan", description="Design dark mode",
     prompt=f"Given: {context}. Design dark mode implementation.",
     model="opus", run_in_background=True)

# After plan completes...
# Phase 3: Implement (sonnet for well-structured work - single message, parallel)
Task(subagent_type="general-purpose", description="Add CSS variables",
     prompt="Add dark theme CSS variables...",
     model="sonnet", run_in_background=True)
Task(subagent_type="general-purpose", description="Create toggle",
     prompt="Create theme toggle component...",
     model="sonnet", run_in_background=True)
Task(subagent_type="general-purpose", description="Add persistence",
     prompt="Add localStorage persistence for theme preference...",
     model="sonnet", run_in_background=True)

# Phase 4: Integration (sonnet for implementation)
Task(subagent_type="general-purpose", description="Wire and test",
     prompt="Wire components together, test theme switching works",
     model="sonnet", run_in_background=True)

User Sees

Adding dark mode to your app.

Exploring your codebase to understand styling patterns...

Found: Tailwind with CSS variables in globals.css, no existing theme system.

Plan:
1. Add CSS variables for dark theme colors
2. Create theme toggle component
3. Persist preference in localStorage
4. Wire up and test

Starting implementation...

---

Progress:
- Added dark theme variables to globals.css
- Created ThemeToggle component at components/theme-toggle.tsx

Working on persistence...

---

Done! Dark mode is ready:
- Toggle in header (components/theme-toggle.tsx)
- Preference saved to localStorage
- System preference detected on first visit

Try it: Click the moon/sun icon in the header.

---

Fix a Bug

User says: "Users can't log in after password reset"

Internal Analysis

• Unknown cause → Need parallel investigation
• Multiple hypotheses → Fan-Out for diagnosis
• May need Speculative if cause unclear

Execution

# Phase 1: Parallel diagnosis (haiku swarm - single message)
Task(subagent_type="Explore", description="Check logs",
     prompt="Search for login errors, password reset issues in logs",
     model="haiku", run_in_background=True)
Task(subagent_type="Explore", description="Find reset flow",
     prompt="Find password reset implementation, trace the flow",
     model="haiku", run_in_background=True)
Task(subagent_type="Explore", description="Check session handling",
     prompt="How are sessions/tokens handled after password change?",
     model="haiku", run_in_background=True)

# Phase 2: Synthesize (after results return)
# Identify: Password reset invalidates session but doesn't clear cookie

# Phase 3: Fix (sonnet for implementation)
Task(subagent_type="general-purpose", description="Fix session bug",
     prompt="Clear session cookie after password reset...",
     model="sonnet", run_in_background=True)

# Phase 4: Verify (sonnet for test writing)
Task(subagent_type="general-purpose", description="Add regression test",
     prompt="Add test for login after password reset...",
     model="sonnet", run_in_background=True)

User Sees

Investigating the login issue after password reset...

Checking a few things:
- Error logs
- Password reset flow
- Session handling

---

Found the issue: Password reset invalidates the session token in the database,
but the old session cookie remains in the browser. On next login attempt,
the invalid cookie causes auth to fail.

Fix: Clear the session cookie when password is reset.

Implementing fix...

---

Fixed in auth/password-reset.ts (line 89).
Added regression test in __tests__/auth.test.ts.

The flow now:
1. User resets password
2. Session cookie is cleared
3. User redirected to login
4. Fresh login works correctly

---

Understand a Codebase

User says: "Help me understand this codebase"

Internal Analysis

• Breadth-first exploration needed
• Multiple independent areas → Fan-Out
• Aggregate into overview → Map-Reduce

Execution

# Phase 1: Parallel exploration (haiku swarm - single message)
Task(subagent_type="Explore", description="Project structure",
     prompt="Analyze project structure, entry points, build system",
     model="haiku", run_in_background=True)
Task(subagent_type="Explore", description="Core patterns",
     prompt="Identify core architectural patterns, frameworks used",
     model="haiku", run_in_background=True)
Task(subagent_type="Explore", description="Data flow",
     prompt="Trace main data flows, API structure, state management",
     model="haiku", run_in_background=True)

User Sees

Exploring the codebase...

---

## Overview
Next.js 14 app with TypeScript, using App Router.

## Structure
src/
├── app/           # Routes and pages
├── components/    # React components (shadcn/ui)
├── lib/           # Utilities and helpers
├── services/      # API clients and business logic
└── types/         # TypeScript types

## Key Patterns
- **Data fetching**: Server components with async/await
- **State**: React Context for auth, Zustand for UI state
- **Styling**: Tailwind CSS with shadcn/ui components
- **API**: REST endpoints in app/api/, Prisma for database

## Entry Points
- `app/page.tsx` - Home page
- `app/api/` - API routes
- `middleware.ts` - Auth middleware

## Getting Started
npm install
npm run dev

Want me to dive deeper into any area?

---

Run Tests and Fix Failures

User says: "Run tests and fix any failures"

Internal Analysis

• Long-running task → Background for tests
• Multiple failures → Fan-Out for fixes

Execution

# Phase 1: Run tests in background (sonnet for test execution)
Task(subagent_type="general-purpose", description="Run tests",
     prompt="Run full test suite, report failures",
     model="sonnet", run_in_background=True)

# Continue with other work or wait
result = TaskOutput(task_id="...", block=True)

# Phase 2: Fix failures (sonnet for fixes - single message)
# If 3 failures found:
Task(subagent_type="general-purpose", description="Fix test 1",
     prompt="Fix failing test in auth.test.ts...",
     model="sonnet", run_in_background=True)
Task(subagent_type="general-purpose", description="Fix test 2",
     prompt="Fix failing test in api.test.ts...",
     model="sonnet", run_in_background=True)
Task(subagent_type="general-purpose", description="Fix test 3",
     prompt="Fix failing test in utils.test.ts...",
     model="sonnet", run_in_background=True)

# Phase 3: Verify (sonnet for test execution)
Task(subagent_type="general-purpose", description="Re-run tests",
     prompt="Run test suite again to verify fixes",
     model="sonnet", run_in_background=True)

User Sees

Running test suite...

---

Test Results: 47 passed, 3 failed

Failures:
1. auth.test.ts - "should reject expired tokens"
2. api.test.ts - "should handle rate limiting"
3. utils.test.ts - "should format dates correctly"

Fixing these now...

---

Fixed all 3 failures:
1. auth.test.ts - Updated mock token expiry time
2. api.test.ts - Added missing rate limit header in test
3. utils.test.ts - Fixed timezone handling in date formatter

Re-running tests...

---

All 50 tests passing.

---

Key Patterns Summary

| Scenario | Pattern | Why | | ----------- | ----------------------------- | ----------------------------------- | | PR Review | Fan-Out → Reduce | Parallel analysis, unified output | | Feature | Pipeline → Fan-Out → Pipeline | Research, parallel build, integrate | | Bug Fix | Fan-Out → Pipeline | Parallel diagnosis, sequential fix | | Exploration | Fan-Out → Reduce | Parallel discovery, synthesize | | Tests | Background → Fan-Out | Long-running, parallel fixes |

---

┌────────────────────────────────────────┐
│  Remember:                             │
│                                        │
│  • Users see natural conversation      │
│  • Pattern names stay internal         │
│  • Results feel like magic             │
│                                        │
└────────────────────────────────────────┘

─── ◈ Examples Complete ─────────────────