# 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](#review-a-pr) 2. [Implement a Feature](#implement-a-feature) 3. [Fix a Bug](#fix-a-bug) 4. [Understand a Codebase](#understand-a-codebase) 5. [Run Tests and Fix Failures](#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 ```python # 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 ```bash # 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 ``` ```python # 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 ```python # 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 ```python # 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 ```python # 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 ───────────────── ```