Subagent Orchestration

Orchestrator CLI

Orchestrate complex development workflows across multiple subagents with strict separation of implementation and validation roles.

Core Principle

User validates plan once at start, then orchestrator executes completely with no mid-flight stops.

YOU ARE THE ORCHESTRATOR: You execute the plan by dispatching subagents through natural language. There is no code running this - you make all decisions about when to dispatch implementers, validators, and fixers based on the workflow described below.

🚨 CRITICAL: As the orchestrator, you NEVER write or generate code yourself. You NEVER read files to review code. You NEVER execute commands. You NEVER do any task yourself. You ONLY dispatch subagents. Your entire job is coordination — deciding who does what and when.

Execution Model

YOU execute this workflow by dispatching subagents at each step:

START
  │
  ▼
User validates and approves plan
  │
  ▼
YOU execute each phase:
  ├─ For SINGLE-SUB-PHASE phases:
  │   ├─ YOU dispatch IMPLEMENTER subagent with COMPLETE requirements + NO-SLOP policy
  │   ├─ IMPLEMENTER runs gatekeeping commands (check-types, build) BEFORE reporting done
  │   ├─ YOU dispatch VALIDATOR subagent (different agent!) with STRINGENT instructions
  │   ├─ If validation FAILS:
  │   │   ├─ YOU dispatch FIXER subagent with ALL validator errors (fix ALL at once)
  │   │   ├─ FIXER runs gatekeeping commands BEFORE reporting done
  │   │   ├─ YOU dispatch VALIDATOR again
  │   │   └─ YOU REPEAT until validation PASSES (up to 3 attempts)
  │   └─ If validation PASSES:
  │       └─ Phase complete, move to next
  │
  ├─ For MULTI-SUB-PHASE phases (phase split into multiple sub-phases):
  │   ├─ For EACH sub-phase:
  │   │   ├─ Dispatch 1 IMPLEMENTER with COMPLETE requirements + NO-SLOP policy
  │   │   ├─ Implementer runs gatekeeping commands
  │   │   ├─ Dispatch 1 VALIDATOR right after (per-sub-phase validation)
  │   │   └─ If FAIL → fixer → validator ... UNTIL PASSES
  │   └─ When ALL sub-phases pass individual validation:
  │       ├─ Dispatch PHASE-WIDE VALIDATOR to read ALL sub-phase code together
  │       ├─ Phase-wide validator checks: integration, shared types, imports, coherence
  │       └─ Fix loop applies to phase-wide validation
  │
  └─ After all phases:
      └─ YOU report completion to user

Key workflow rules:

• 1 implementer per sub-phase → 1 validator per sub-phase → phase-wide validator → commit
• Validator right after each sub-phase — do not batch validations
• Fixers fix ALL validator errors at once — not one at a time
• check-types is MANDATORY — every package created must have it, validators must verify

Important: "Automatic" means you execute all phases without stopping to ask the user - not that code runs this. YOU (the orchestrator) make all decisions and dispatch all subagents through natural language, but you NEVER write or generate code yourself.

Quick Start

1. Prepare the Plan

Create a detailed plan document specifying:

• Numbered phases with clear requirements
• Inputs (files to read) and outputs (files to create)
• Validation criteria for each phase
• Dependencies between phases
• Phase type: Sequential or Parallel

See references/plan-template.md for full template.

2. Get User Approval

Present plan to user and confirm:

• "Execute this plan automatically?"
• Once approved, begin execution
• No further user interaction needed

3. Execute Automatically

For each phase:

1. Dispatch implementer → create/modify files 2. Dispatch validator → check requirements, run tests 3. If fails → dispatch fixer → re-validate 4. If passes → next phase

4. Report Results

After all phases complete:

• Success summary with statistics
• Or failure report with diagnostics

Concrete Example

User request: "Build a task manager API with database, services, and routes"

Your execution:

1. Phase 1: Database Schema

• Dispatch implementer with COMPLETE requirements + NO-SLOP policy: "Create src/db/schema.ts with tasks table following these exact requirements [paste complete requirements from plan]"
• Implementer creates file, runs check-types + build
• Dispatch validator: "Read and REVIEW src/db/schema.ts to verify all requirements are met, enforce NO-SLOP policy, then run check-types"
• Validator: PASS ✓

2. Phase 2: Database Client

• Dispatch implementer with COMPLETE requirements + NO-SLOP policy: "Create src/db/client.ts using schema, following these exact requirements [paste complete requirements from plan]"
• Implementer creates file, runs check-types + build
• Dispatch validator: "ACTUALLY READ src/db/client.ts, enforce NO-SLOP policy, check error handling, then run check-types and build"
• Validator: FAIL (missing error handling in connection logic)
• Dispatch fixer with ALL validator errors: "Fix all validator errors at once per validator report"
• Fixer runs check-types + build
• Dispatch validator again
• Validator: PASS ✓

3. Phase 3: Services (Parallel — each sub-phase gets its own validator)

• Dispatch 3 implementers simultaneously with COMPLETE requirements + NO-SLOP policy:
• Implementer A: "Create task.service.ts following these exact requirements [paste from plan]"
• Implementer B: "Create user.service.ts following these exact requirements [paste from plan]"
• Implementer C: "Create auth.service.ts following these exact requirements [paste from plan]"
• Each implementer runs check-types + build before reporting done
• Dispatch validator RIGHT AFTER each implementer finishes:
• Validator A checks task.service.ts → PASS ✓
• Validator B checks user.service.ts → PASS ✓
• Validator C checks auth.service.ts → PASS ✓
• Phase-wide validator reads ALL three services together → checks integration, shared types, imports → PASS ✓

4. Phase 4: API Routes

• Dispatch implementer with COMPLETE requirements: "Create API routes using services, following these exact requirements [paste from plan]"
• Dispatch validator: "ACTUALLY READ all route files to verify requirements are met, then run type check and build"
• Validator: PASS ✓

Result: Report to user "All 4 phases complete, 1 fix iteration in Phase 2"

This took 4 phases, 1 parallel phase, 1 fix loop - all executed without asking user.

Critical Rules

🚨 CRITICAL: Orchestrator Code Generation Rule

THE ORCHESTRATOR MUST NEVER WRITE OR GENERATE CODE

The orchestrator's job is to:

• Dispatch subagents with the COMPLETE plan requirements
• Provide clear instructions on which part/phase to work on
• Coordinate the workflow and track progress
• NOT write, modify, or generate any code yourself

If you need code written, dispatch an implementer subagent with the complete requirements.

🚨 CRITICAL: Validator Code Review Rule

THE VALIDATOR MUST ACTUALLY READ AND VALIDATE THE CODE

The validator's job is to:

• Read and understand every line of code created/modified
• Manually verify each requirement from the plan is met
• Check code quality, patterns, and implementation details
• NOT just run validation commands (typecheck, build, tests)
• Report specific issues with file paths and line numbers

Running validation commands is important, but it's NOT enough. You MUST ACTUALLY REVIEW THE CODE by reading through it and verifying requirements.

Rule 1: Strict Role Separation

NEVER let one subagent do both implementation and validation.

Rule 2: Implementers MUST Run Gatekeeping Commands

Every implementer and fixer MUST run all gatekeeping commands (typecheck, build, etc.) on their own work BEFORE reporting completion.

This is NOT validation — it is basic quality control. Implementers must: 1. Write the code 2. Run typecheck, build, and any other project-appropriate gatekeeping commands 3. Fix any errors found by those commands 4. Only report "done" once all gatekeeping commands pass cleanly

Why: No subagent should hand back broken code. Type errors and build failures are not acceptable deliverables. The validator's job is to review code quality and requirement compliance — not to catch basic compilation errors that the implementer should have caught themselves.

Rule 3: Phase-Wide Validation for Multi-Sub-Phase Phases

If a phase is split into multiple sub-phases with multiple implementers, per-sub-phase validation AND a phase-wide validator run are both MANDATORY.

Flow for multi-sub-phase phases: 1. Dispatch sub-phase implementers (parallel or sequential) 2. Each implementer runs their own gatekeeping commands 3. Dispatch 1 validator per sub-phase RIGHT AFTER each implementer finishes (not batched) 4. Fix loop per sub-phase until each passes individually 5. When ALL sub-phases pass: dispatch a phase-wide validator that reads ALL code from ALL sub-phases together 6. The phase-wide validator checks: integration between sub-phases, shared types, imports, overall coherence 7. Fix loop applies to the phase-wide validation

Why: Individual sub-phase validators only check their slice. A phase-wide validator catches integration issues, mismatched interfaces, duplicate code, and inconsistencies across sub-phases that individual validators miss.

Rule 4: Complete Execution

Once user approves plan:

• Execute all phases automatically
• No user interaction during execution
• Only stop if a phase fails after max fix attempts (3)
• Report final result to user

Rule 5: Validation Loop

For each phase:

1. Dispatch implementer → create/modify files 2. Dispatch validator → ACTUALLY READ AND REVIEW the code, check requirements, run tests 3. If validation PASSES → phase complete, continue 4. If validation FAILS:

• Dispatch fixer with ALL validator errors (fixer must fix ALL at once, not one at a time)
• Dispatch validator again
• REPEAT until pass or max attempts reached

Rule 6: NO-SLOP Policy — MANDATORY for Every Dispatch

Every dispatch to implementers and fixers MUST include the NO-SLOP policy. Every dispatch to validators MUST instruct them to enforce it.

NO-SLOP rules — all of these are hard requirements, not suggestions:

• NO any, as any, : any ANYWHERE
• NO placeholder code, NO // TODO, NO // FIXME
• NO unused imports, NO unused variables — if a variable is not used, it must not exist
• NO console.log hacks to suppress errors. NO void hacks.
• Use import type for type-only imports (verbatimModuleSyntax: true)
• External imports first, blank line, then local imports
• ONE query/mutation per file, named export
• Do NOT start the dev server

Validators must be STRINGENT. Only production-quality code passes. Any slop is rejected.

Rule 7: Phase Sizing — Must Fit in Agent Context

Every phase must fit comfortably inside a single agent's context window. If a phase is too large, it MUST be split into sub-phases.

Signs a phase is too large:

• More than ~15 files to create or modify
• Requirements that would produce more than ~500 lines of new code
• Multiple unrelated concerns crammed into one phase

When a phase is too large: 1. Split it into sub-phases, each with a clear, focused scope 2. Each sub-phase gets its own implementer → validator → fixer loop 3. After all sub-phases pass, a phase-wide validator checks integration 4. This avoids context compaction which degrades code quality

Why: When an agent's context fills up, compaction kicks in and quality drops precipitously. Large phases produce worse code because the agent loses track of earlier context. Smaller, focused phases produce better code.

Dispatching Subagents

Use the templates in references/subagent-templates.md when dispatching.

Quick reference:

• Implementer: Gets COMPLETE phase requirements from plan, creates/modifies files, does NOT validate
• Validator: Gets implementation + requirements, ACTUALLY READS AND REVIEWS the code thoroughly, runs typecheck/build/tests, does NOT modify code
• Fixer: Gets validator report, fixes all issues, does NOT validate

When dispatching implementers:

ALWAYS provide: 1. The COMPLETE requirements section from the plan (not a summary) 2. Specific instructions on which part/phase to proceed with 3. List of files to read for context 4. List of files to create/modify 5. Clear boundaries - what they should and should NOT do 6. Instruction to run gatekeeping commands (check-types, build) and fix any errors BEFORE reporting completion 7. The NO-SLOP policy (see Rule 6) — paste it verbatim

When dispatching validators:

ALWAYS provide: 1. Files that were created/modified (complete list) 2. The COMPLETE requirements section from the plan 3. Validation criteria (check-types, build, code review) 4. Instruction to ACTUALLY READ the code, not just run commands 5. Instruction to enforce the NO-SLOP policy — validators must be STRINGENT, only production code passes

When dispatching fixers:

ALWAYS provide: 1. ALL validator errors at once — fixers must fix everything, not one at a time 2. The NO-SLOP policy — fixes must meet the same quality bar 3. Instruction to run gatekeeping commands before reporting done

Example dispatch (see templates for full format):

You are the Implementer for Phase 2 - Database Client.

Requirements from plan:
- Create connection pool using Drizzle
- Export typed database client
- Load DATABASE_URL from environment

Read: src/db/schema.ts (to understand schema)
Create: src/db/client.ts

NO-SLOP POLICY (MANDATORY):
- NO `any`, `as any`, `: any` ANYWHERE
- NO placeholder code, NO `// TODO`, NO `// FIXME`
- NO unused imports, NO unused variables
- Use `import type` for type-only imports
- External imports first, blank line, then local imports

Run check-types and build before reporting done.
Do NOT validate your work - a validator will check it.
Report when complete.

See references/subagent-templates.md for complete templates with all sections.

Phase Types

Sequential Phases

Execute one at a time in order:

• Phase 1 complete → Phase 2 → Phase 3...
• Each phase must validate before next starts

Example:

Phase 1: Database schema
  Implement → Validate → Pass

Phase 2: Environment setup
  Implement → Validate → Pass

Phase 3: API implementation
  Implement → Validate → Pass

Parallel Phases

Execute multiple sub-tasks simultaneously:

• Dispatch all implementers at once
• Each implementer runs gatekeeping commands before reporting done
• Wait for all to complete
• Validate each independently
• Run a phase-wide validator that reads ALL sub-phase code together
• Fix any failures
• All must pass before continuing

Example:

Phase 3: Core services (parallel)
  Dispatch simultaneously:
    - Implementer A: Git manager (runs typecheck/build before done)
    - Implementer B: Database manager (runs typecheck/build before done)
    - Implementer C: Manifest manager (runs typecheck/build before done)

  Wait for all three to complete

  Validate each:
    - Validator A checks Git manager
    - Validator B checks Database manager
    - Validator C checks Manifest manager

  If any fail, fix that specific one

  PHASE-WIDE VALIDATION (mandatory):
    - Validator D reads ALL three services together
    - Checks: shared types, imports between services, interface consistency,
      no duplicates, overall integration coherence
    - If fails → fix loop on affected files

  All pass → continue to Phase 4

See references/workflow-patterns.md for more examples.

Error Handling

Implementer Fails

If implementer cannot complete:

• Log the failure reason
• Retry implementer (up to 2 times)
• If still failing → HALT execution
• Report to user: "Phase X failed during implementation"

Validation Fails (Normal Flow)

If validator finds issues:

• This is expected, enter fix loop
• Dispatch fixer with validator report
• Re-validate the fixes
• Loop until pass or max attempts (3)

Validation Fails After Max Attempts

If still failing after 3 fix attempts:

• HALT execution
• Report to user with full details:
• Which phase failed
• Validator's issue report
• Files with problems
• Suggestion to revise plan

Dependencies Missing

If required files from previous phase don't exist:

• Previous phase didn't complete properly
• HALT and report issue
• Don't try to continue

See references/error-handling.md for detailed recovery strategies.

Progress Reporting

During Execution (Optional)

Can report progress without requiring response:

Progress: Phase 3 of 7 complete
Current: Phase 4 - API Layer
Status: Implementing...

Final Report - Success

EXECUTION COMPLETE

All [N] phases completed successfully.

Phases:
✓ Phase 1: [Name]
✓ Phase 2: [Name]
✓ Phase 3: [Name]
...

Statistics:
- Total fix iterations: [N]
- Files created: [N]
- Files modified: [N]

Build: ✓
Type check: ✓

Execution complete.

Final Report - Failure

EXECUTION FAILED

Failed at Phase [X]: [Name]

After 3 fix attempts, validation still failing.

VALIDATOR REPORT:
[Specific issues found]

FILES WITH ISSUES:
[List files with line numbers]

SUGGESTION:
Review and update the plan, then re-execute.

Prerequisites

• Development environment with build tools
• Project with validation commands appropriate to the language/framework:
• Type checking if applicable (e.g., tsc --noEmit, mypy, type checking tools)
• Build/compile if applicable (e.g., npm run build, cargo build, compilation steps)
• Code quality checks for any language (linting, formatting, tests)
• Plan document following the template format (see references/plan-template.md)
• Ability to dispatch multiple subagent instances

Validation should be adapted to the project's language and tooling, not limited to TypeScript.

Summary

YOU execute the workflow:

1. User approves plan once 2. YOU dispatch subagents for each phase (implementer → validator → fixer if needed) 3. YOU continue through all phases without user input 4. YOU report results at the end

🚨 CRITICAL RULES - READ CAREFULLY:

1. YOU (orchestrator) MUST NEVER WRITE, READ, OR EXECUTE ANYTHING

• You ONLY dispatch subagents. No coding, no reading files, no running commands.
• Always dispatch implementers with COMPLETE plan requirements
• Give clear instructions on which part/phase to work on

2. Validators MUST ACTUALLY READ AND VALIDATE THE CODE

• Reading code line-by-line is REQUIRED
• Running commands alone is NOT sufficient
• Manual verification of each requirement is mandatory

3. NO-SLOP POLICY is MANDATORY — included in every implementer/fixer dispatch, enforced by every validator. No any, no TODOs, no unused imports, no placeholder code. Only production-quality code passes.

4. Implementers MUST run gatekeeping commands (check-types, build) on their own work BEFORE reporting done. Every package created must have check-types configured.

5. Multi-sub-phase phases: 1 implementer → 1 validator per sub-phase RIGHT AFTER → phase-wide validator when all pass.

6. Fixers fix ALL errors at once — not one at a time. If the validator lists 5 issues, the fixer fixes all 5.

7. Phases must fit in agent context — if too large, split into sub-phases. Compaction degrades quality.

8. Strict role separation: implementer ≠ validator ≠ fixer 9. Auto-retry fixes up to 3 validation attempts per phase 10. Halt only on max retry failures or environment issues

Reference Documentation

• Plan Template - Structure for multi-phase plans
• Subagent Templates - Full dispatch instructions
• Workflow Patterns - Sequential and parallel examples
• Error Handling - Recovery strategies and debugging

Orchestrator CLI Skill

Execute multi-phase development workflows by dispatching separate implementer and validator subagents.

Purpose

This skill helps you orchestrate complex development tasks that require:

• Multiple sequential or parallel phases
• Strict separation between implementation and validation
• Automatic retry loops when validation fails
• Complete execution after single user approval

How It Works

1. User provides or approves a detailed plan 2. You execute each phase by dispatching subagents 3. Each phase: implementer → validator → (fixer if needed) → pass/fail 4. You continue until all phases complete or one fails after max retries 5. You report final results to user

File Structure

• SKILL.md - Core workflow and rules (start here)
• references/plan-template.md - How to structure multi-phase plans
• references/subagent-templates.md - Complete dispatch templates for each role
• references/workflow-patterns.md - Sequential and parallel execution patterns
• references/error-handling.md - How to handle failures and retry

Key Concepts

Role Separation

Never let the same subagent both implement AND validate:

• Implementer: Creates/modifies code, does NOT validate
• Validator: Checks code thoroughly, does NOT modify
• Fixer: Repairs issues, does NOT validate

Execution Flow

You dispatch subagents and make decisions - there is no code running this orchestration. "Automatic execution" means you continue through all phases without asking the user for input, not that code executes the workflow.

Validation Loop

When validation fails (normal and expected):

1. Dispatch fixer with validator's report 2. Re-validate the fixes 3. Repeat up to 3 total validation attempts 4. If still failing, halt and report to user

When to Use This Skill

Use when the user requests:

• "Implement this multi-phase plan"
• "Build [complex system] with [architecture]"
• "Create [project] following these phases"
• Multi-step development requiring validation at each stage

Don't use for:

• Simple single-file tasks
• Exploratory coding without clear phases
• Tasks where user wants to review each step

Quick Start

1. Read SKILL.md for core workflow 2. Review a plan (or help user create one using plan-template.md) 3. Get user approval: "Execute this plan automatically?" 4. Execute each phase using subagent-templates.md 5. Report completion or failure

The skill ensures quality through separation of concerns and automatic validation cycles.

Error Handling

Comprehensive guide to handling errors and failures during orchestrated workflows.

Error Categories

1. Implementation Errors

What: Implementer fails to complete the task

Causes:

• Missing files referenced in plan
• Unclear requirements
• Technical blockers (missing dependencies, environment issues)
• Implementer confusion about what to do

Detection:

• Implementer reports "cannot complete"
• Implementer asks questions (shouldn't happen in auto-execution)
• Timeout waiting for implementer
• Implementer creates wrong files

Response:

1. Log the failure reason
2. Retry implementer dispatch with clarified instructions (up to 2 retries)
3. If still failing after 2 retries:
   - HALT execution
   - Report to user: "Phase X implementation failed"
   - Provide implementer's error messages
   - Suggest plan revision

2. Validation Errors

What: Validator finds issues with implementation

Causes:

• Requirements not fully met
• Type errors
• Build failures
• Code quality issues
• Missing exports or incorrect patterns

Detection:

• Validator returns FAIL status
• Type check errors reported
• Build errors reported
• Code review identifies issues

Response:

1. This is NORMAL - expected part of workflow
2. Enter fix loop:
   a. Dispatch fixer with validator report
   b. Dispatch validator again
   c. Repeat up to 3 total validation attempts
3. If still failing after 3 attempts:
   - HALT execution
   - Report detailed failure to user

Example:

Validation Attempt 1: FAIL
├─ Issues: Missing type, incorrect export
├─ Fixer: Adds type, fixes export
└─ Validation Attempt 2: PASS ✓

Outcome: Continue to next phase

3. Fixer Errors

What: Fixer fails to resolve validation issues

Causes:

• Misunderstood the validator report
• Introduced new bugs while fixing
• Incomplete fixes (fixed some but not all issues)
• Fixed wrong things

Detection:

• Re-validation after fix still shows same errors
• Re-validation shows NEW errors that didn't exist before
• Fixer reports inability to fix

Response:

1. Count this as one attempt
2. Dispatch fixer again with more explicit instructions
3. After 3 total attempts (original validation + 2 fix attempts):
   - HALT execution
   - Report that fixes were unsuccessful
   - Show original issues and attempted fixes

Example:

Validation 1: FAIL (Issue: missing type on user_id)
Fix Attempt 1: Fixer adds type but creates new error
Validation 2: FAIL (Original issue fixed, new issue: wrong type)
Fix Attempt 2: Fixer fixes type correctly
Validation 3: PASS ✓

Outcome: Took 3 attempts but succeeded

4. Dependency Errors

What: Required files from previous phases don't exist or are incorrect

Causes:

• Previous phase didn't actually complete
• Previous phase created wrong files
• Files were created in wrong location
• Orchestration bug (skipped a phase)

Detection:

• Implementer reports "file X not found"
• Type errors about missing imports
• Build fails due to missing modules

Response:

1. HALT immediately - don't try to continue
2. Identify which phase was supposed to create the file
3. Check if that phase reported success
4. Report to user:
   - "Phase X requires file Y from Phase Z"
   - "Phase Z reported success but file not found"
   - "Possible orchestration error - review plan"

Example:

Phase 3 requires: src/db/client.ts (from Phase 2)
Phase 2 reported: ✓ Complete
Reality: File doesn't exist

Action: HALT
Report: "Dependency error - Phase 2 claimed success but output missing"

5. Integration Errors

What: Individual tasks pass validation but don't work together

Causes:

• Type mismatches between modules
• Circular dependencies
• Import/export issues
• Parallel tasks conflicted

Detection:

• Integration type check fails (individual checks passed)
• Integration build fails (individual builds passed)
• Runtime errors when components interact

Response:

1. Identify the conflicting modules
2. Dispatch specialized "integration fixer"
3. Re-run integration validation
4. If still failing:
   - Report which modules conflict
   - Suggest sequential execution instead of parallel

Example:

Phase 3 (Parallel):
├─ Task A: user.service.ts → ✓ Types pass
├─ Task B: order.service.ts → ✓ Types pass
└─ Task C: product.service.ts → ✓ Types pass

Integration Check: ✗ FAIL
Error: order.service imports User type but user.service doesn't export it

Action: Dispatch integration fixer
Fix: Add export to user.service.ts
Integration Check: ✓ PASS

6. Environment Errors

What: Build tools, dependencies, or environment not set up correctly

Causes:

• Missing npm packages
• Wrong Node.js version
• Database not running
• Build scripts not configured

Detection:

• Commands fail (pnpm not found, etc.)
• Type check command doesn't exist
• Build command errors immediately
• Import errors for known packages

Response:

1. Check if error is environmental vs code issue
2. If environmental:
   - HALT execution
   - Report: "Environment not ready"
   - List missing prerequisites
   - Don't try to fix code
3. User must fix environment, then restart

Example:

Validation runs: pnpm run check-types
Error: "pnpm: command not found"

Action: HALT
Report: "Environment error - pnpm not installed"
Suggestion: "Install pnpm and retry execution"

Recovery Strategies

Strategy 1: Retry with Clarification

When: First failure of implementer

How:

1. Analyze what went wrong
2. Enhance the dispatch with:
   - More explicit requirements
   - Additional examples
   - Specific file paths
   - Clearer expected outputs
3. Retry implementer
4. Max 2 retries total

Example:

Attempt 1 Failed: "Implementer confused about schema format"

Attempt 2 Enhanced Dispatch:
- Added: "Use Drizzle pgTable syntax"
- Added: "Example: export const users = pgTable('users', {...})"
- Added: "Reference existing file: src/db/example-schema.ts"

Attempt 2: ✓ Success

Strategy 2: Fix Loop

When: Validation failures

How:

1. Validator identifies issues
2. Fixer attempts to resolve
3. Re-validate
4. Repeat up to 3 total validation attempts
5. Each attempt should show progress

Example:

Validation 1: FAIL (5 issues)
Fix 1: Resolves 4 issues
Validation 2: FAIL (1 issue remaining)
Fix 2: Resolves last issue
Validation 3: PASS ✓

Took 3 attempts but made progress each time

Strategy 3: Isolated Testing

When: Integration failures after parallel execution

How:

1. Re-validate each parallel task individually
2. Identify which task(s) cause the integration failure
3. Fix only the problematic tasks
4. Re-run integration check

Example:

Integration FAIL: Type conflicts

Individual Re-checks:
├─ Task A alone: ✓ PASS
├─ Task B alone: ✓ PASS
└─ Task C alone: ✓ PASS

A + B together: ✓ PASS
A + C together: ✗ FAIL → Found the conflict!
B + C together: ✓ PASS

Fix: Adjust Task C exports
Integration: ✓ PASS

Strategy 4: Graceful Degradation

When: Non-critical failures in low-priority tasks

How:

1. Mark task as "partial success"
2. Continue with remaining phases
3. Report at end: "Phase X had warnings but continued"
4. Let user decide if acceptable

Example:

Phase 3, Task B: Code works but has style warnings

Decision: Mark as partial success
Continue: Phases 4, 5, 6
Final Report: "All phases complete, Phase 3 Task B has style warnings"

User can decide to:
- Accept as-is
- Go back and clean up

Strategy 5: Rollback

When: Fix attempts make things worse

How:

1. Detect that validation errors increased after fix
2. Restore previous version
3. Try different fix approach
4. Track fix attempts separately

Example:

Validation 1: FAIL (2 type errors)
Fix Attempt: Changes types
Validation 2: FAIL (5 type errors) ← WORSE!

Action: Rollback to Validation 1 state
Fix Attempt 2: Different approach
Validation 3: FAIL (1 type error) → Progress!
Fix Attempt 3: Fix last error
Validation 4: PASS ✓

Error Messages

Clear Error Reports

Bad Error Report:

Phase 3 failed

Good Error Report:

EXECUTION FAILED AT PHASE 3

Phase: Core Services (Parallel)
Task: User Service (3.1)
Failure Type: Validation failure after max fix attempts

VALIDATOR REPORT (Final Attempt):
Status: FAIL

Critical Issues:
1. src/services/user.service.ts:42
   - Type error: Cannot assign string to number
   - Expected: userId as number
   - Received: userId as string

2. src/services/user.service.ts:67
   - Missing export: createUser function not exported
   - Required by: API routes

FIX ATTEMPTS:
- Attempt 1: Fixed type error, but didn't fix export
- Attempt 2: Fixed export, but broke type again
- Attempt 3: Fixed type, but export still wrong

SUGGESTION:
Review user.service.ts type definitions and exports.
Consider updating plan to be more explicit about:
- Expected types for userId (number vs string)
- Which functions must be exported

Diagnostic Information

Always include:

• Phase number and name
• Task number (if parallel)
• Failure type
• Specific files and line numbers
• What was attempted
• What the expected outcome was
• What actually happened
• Number of attempts made
• Suggestion for next steps

Debugging Failed Executions

Step 1: Identify Failure Point

Review execution log:
- Which phase failed?
- Was it implementation, validation, or integration?
- First failure or after retries?

Step 2: Check Dependencies

Verify:
- Did all previous phases complete successfully?
- Do required input files exist?
- Are imports/exports correct from earlier phases?

Step 3: Examine Validation Reports

Look at:
- What specific errors were reported?
- Did errors change between attempts?
- Did fixes make things better or worse?

Step 4: Review Plan Requirements

Check if:
- Requirements were clear enough
- Requirements were achievable
- Requirements conflicted with each other
- Requirements assumed knowledge not provided

Step 5: Determine Root Cause

Common root causes:
- Vague requirements → Update plan
- Missing dependencies → Fix environment
- Integration conflicts → Reorder phases
- Too ambitious → Break into smaller phases

Prevention

Write Better Plans

✓ DO:

• Be extremely specific in requirements
• List exact file paths
• Provide examples and references
• Specify validation criteria clearly
• Break large phases into smaller ones

✗ DON'T:

• Use vague terms like "make it work"
• Assume knowledge of patterns
• Skip validation criteria
• Make phases too large

Set Realistic Expectations

✓ DO:

• Estimate phase complexity realistically
• Plan for 1-2 fix attempts per phase
• Allow time for integration testing
• Expect some failures (normal)

✗ DON'T:

• Expect perfect first-time success
• Rush through phases
• Skip integration checks
• Blame tools when plan was unclear

Monitor Progress

✓ DO:

• Log each step
• Track fix attempt counts
• Note patterns in failures
• Learn from successful phases

✗ DON'T:

• Only check at the end
• Ignore warning signs
• Continue blindly after failures
• Skip post-execution review

Summary

Error handling is not about avoiding errors (impossible) but about:

1. Detecting errors quickly and accurately 2. Diagnosing root causes correctly 3. Recovering with appropriate strategies 4. Reporting clearly for user action 5. Learning to prevent similar errors

The orchestrator's job is to handle expected errors gracefully (validation failures, simple fixes) and report unexpected errors clearly (environment issues, plan problems, dependency failures).

Remember: Validation failures are NORMAL. Integration issues are NORMAL. The system should handle these automatically. Only HALT for unexpected issues that require user intervention.

Plan Template

A well-structured plan is essential for successful orchestration. This template ensures all necessary information is provided for automatic execution.

Template Structure

# [Plan Name]

## Overview
Brief description of what this plan accomplishes.

## Prerequisites
- Tools required (e.g., pnpm, TypeScript)
- Files that must exist before starting
- Environment setup needed

## Phase 1: [Name]
**Type**: Sequential

**Requirements**:
- [Specific requirement 1]
- [Specific requirement 2]
- [Specific requirement 3]

**Inputs**:
- Read: [file1.ts, file2.ts]
- Reference: [existing patterns to follow]

**Outputs**:
- Create: [new-file1.ts, new-file2.ts]
- Modify: [existing-file.ts]

**Validation Criteria**:
- Type check: Zero errors
- Build: Success
- All requirements implemented
- [Specific criteria for this phase]

**Dependencies**: None (first phase)

---

## Phase 2: [Name]
**Type**: Sequential

**Requirements**:
- [Specific requirement 1]
- [Specific requirement 2]

**Inputs**:
- Read: [outputs from Phase 1]
- Reference: [patterns]

**Outputs**:
- Create: [files]
- Modify: [files]

**Validation Criteria**:
- [Criteria specific to this phase]

**Dependencies**: Phase 1 must complete successfully

---

## Phase 3: [Name]
**Type**: Parallel

**Sub-tasks**:

### 3.1: [Sub-task A Name]
**Requirements**:
- [Requirement 1]
- [Requirement 2]

**Outputs**:
- Create: [fileA1.ts, fileA2.ts]

**Validation**:
- [Criteria for sub-task A]

### 3.2: [Sub-task B Name]
**Requirements**:
- [Requirement 1]
- [Requirement 2]

**Outputs**:
- Create: [fileB1.ts, fileB2.ts]

**Validation**:
- [Criteria for sub-task B]

### 3.3: [Sub-task C Name]
**Requirements**:
- [Requirement 1]

**Outputs**:
- Create: [fileC1.ts]

**Validation**:
- [Criteria for sub-task C]

**Phase-level Validation**:
- All sub-tasks pass individual validation
- Integration: Sub-tasks work together
- Type check: Zero errors across all files
- Build: Success

**Dependencies**: Phase 2 must complete successfully

---

[Continue for all remaining phases...]

## Success Criteria

Overall success requires:
- All phases complete and validate successfully
- Final build passes
- Final type check passes
- All requirements from all phases met

Example: E-Commerce System

# E-Commerce Backend System

## Overview
Build a complete e-commerce backend with database, API layer, and authentication.

## Prerequisites
- pnpm installed
- PostgreSQL running locally
- TypeScript 5.x
- Node.js 20.x

## Phase 1: Database Schema
**Type**: Sequential

**Requirements**:
- Define User table with id, email, password_hash, created_at
- Define Product table with id, name, description, price, stock
- Define Order table with id, user_id, total, status, created_at
- Define OrderItem table with id, order_id, product_id, quantity, price
- All tables have proper foreign keys
- All timestamps default to NOW()

**Inputs**:
- Read: None (first phase)
- Reference: None

**Outputs**:
- Create: src/db/schema.ts

**Validation Criteria**:
- Type check: Zero errors
- Schema exports all table definitions
- Proper Drizzle ORM syntax
- Foreign key relationships defined correctly

**Dependencies**: None

---

## Phase 2: Database Client
**Type**: Sequential

**Requirements**:
- Create database connection pool
- Export typed database client
- Add connection error handling
- Load DATABASE_URL from environment

**Inputs**:
- Read: src/db/schema.ts
- Reference: Drizzle documentation patterns

**Outputs**:
- Create: src/db/client.ts

**Validation Criteria**:
- Type check: Zero errors
- Client properly typed with schema
- Connection pooling configured
- Error handling present

**Dependencies**: Phase 1 must complete

---

## Phase 3: Core Services
**Type**: Parallel

### 3.1: User Service
**Requirements**:
- createUser(email, password) function
- getUserById(id) function
- getUserByEmail(email) function
- Password hashing with bcrypt
- Proper error handling

**Outputs**:
- Create: src/services/user.service.ts

**Validation**:
- All functions properly typed
- Uses db client from Phase 2
- Bcrypt integration working

### 3.2: Product Service
**Requirements**:
- createProduct(name, description, price, stock) function
- getProductById(id) function
- listProducts(limit, offset) function
- updateStock(productId, quantity) function

**Outputs**:
- Create: src/services/product.service.ts

**Validation**:
- All functions properly typed
- Uses db client
- Stock management logic correct

### 3.3: Order Service
**Requirements**:
- createOrder(userId, items[]) function
- getOrderById(id) function
- getUserOrders(userId) function
- Calculate totals correctly
- Handle out-of-stock scenarios

**Outputs**:
- Create: src/services/order.service.ts

**Validation**:
- All functions properly typed
- Transaction handling for order creation
- Stock validation logic

**Phase-level Validation**:
- All services type check
- All services import db client correctly
- Build succeeds
- No circular dependencies

**Dependencies**: Phase 2 must complete

---

## Phase 4: API Routes
**Type**: Sequential

**Requirements**:
- POST /api/users - create user
- GET /api/users/:id - get user
- POST /api/products - create product
- GET /api/products - list products
- GET /api/products/:id - get product
- POST /api/orders - create order
- GET /api/orders/:id - get order
- All routes use services from Phase 3
- Proper request validation
- Error responses with status codes

**Inputs**:
- Read: src/services/*.service.ts
- Reference: Express.js patterns

**Outputs**:
- Create: src/api/routes/users.ts
- Create: src/api/routes/products.ts
- Create: src/api/routes/orders.ts
- Create: src/api/index.ts

**Validation Criteria**:
- Type check: Zero errors
- All routes properly typed
- Request/response types defined
- Error handling middleware present
- Build succeeds

**Dependencies**: Phase 3 must complete

---

## Success Criteria

- All 4 phases complete
- pnpm run check-types: Zero errors
- pnpm run build: Success
- All services integrate correctly
- Database schema properly defined
- API routes functional

Key Elements to Include

1. Clear Phase Boundaries

Each phase should be:

• Self-contained where possible
• Have clear inputs and outputs
• Specify exact validation criteria
• List dependencies explicitly

2. Specific Requirements

Avoid vague requirements like "make it work" or "implement the feature."

Bad:

• Make the API work
• Add authentication

Good:

• Implement JWT token generation with 24-hour expiry
• Add middleware that validates Bearer token on protected routes
• Return 401 for invalid/expired tokens

3. Explicit Validation

State exactly what "passing" means:

Bad:

• Make sure it works

Good:

• Type check: Zero errors
• Build: Success
• All functions return correct types
• Error handling for null cases

4. File-Level Outputs

List specific files to create or modify:

Bad:

• Add the database stuff

Good:

• Create: src/db/schema.ts
• Create: src/db/client.ts
• Modify: src/index.ts (add db import)

5. Dependencies

Make phase dependencies explicit:

• "Dependencies: None" for first phase
• "Dependencies: Phase 1 must complete" for dependent phases
• "Dependencies: Phases 1, 2, 3 must complete" for later phases

Anti-Patterns to Avoid

❌ Vague Requirements

Phase 1: Set up the project
Requirements:
- Make it ready to use

✓ Specific Requirements

Phase 1: Project Initialization
Requirements:
- Initialize pnpm workspace
- Install dependencies: drizzle-orm, postgres, express, zod
- Create tsconfig.json with strict mode enabled
- Create src/ directory structure
- Add type-check and build scripts to package.json

❌ Missing Validation

Phase 2: Create the API
Outputs:
- Create: api.ts

✓ Complete Validation

Phase 2: API Layer
Outputs:
- Create: src/api/routes.ts
- Create: src/api/middleware.ts
- Create: src/api/index.ts

Validation Criteria:
- Type check: Zero errors
- All routes properly typed with Request/Response types
- Middleware properly chains
- Error handler catches and formats errors
- Build produces valid JavaScript

❌ Implicit Dependencies

Phase 3: Use the database
Phase 4: Add API routes

✓ Explicit Dependencies

Phase 3: Database Client
Dependencies: None

Phase 4: API Routes
Dependencies: Phase 3 must complete (requires db client)

Tips for Writing Plans

1. Start with the end goal - Know what the final system should do 2. Work backwards - Identify what needs to exist at each stage 3. Group related work - Phases that can run in parallel should be grouped 4. Be specific - The more specific your requirements, the better the implementation 5. Include validation - Every phase needs clear pass/fail criteria 6. Test the plan - Read through and imagine executing it step by step 7. Size phases for agent context - Each phase must fit comfortably in a single agent's context window. If a phase would create/modify more than ~15 files or produce more than ~500 lines of code, split it into sub-phases. Context compaction degrades quality severely.

Phase Sizing Guidelines

A phase is too large if:

• It creates or modifies more than ~15 files
• Its requirements would produce more than ~500 lines of new code
• It covers multiple unrelated concerns
• An implementer would need to hold too much context to complete it

When a phase is too large: 1. Split into focused sub-phases, each with a single clear concern 2. Each sub-phase gets its own implementer → validator flow 3. Add a phase-wide validator after all sub-phases pass 4. This keeps each agent's context manageable and avoids compaction

Why this matters: Agent context windows are finite. When context fills up, compaction discards earlier information and code quality drops precipitously — the agent loses track of patterns, conventions, and decisions made earlier in the phase. Smaller phases = better code.

Subagent Templates

Complete templates for dispatching implementer, validator, and fixer subagents.

Implementer Template

Full Template

ROLE: Implementer
PHASE: [number] - [name]

MISSION:
Implement exactly what the plan specifies for this phase. You are responsible for creating or modifying code files according to the requirements. Do NOT validate your own work - a separate validator will check it.

PLAN REQUIREMENTS:
[Copy the specific requirements from the plan document for this phase]
Example:
- Create User table with id, email, password_hash, created_at fields
- Add proper foreign key constraints
- Use Drizzle ORM syntax
- Export all table definitions

INPUTS:
- Read first: [list files to examine before starting]
  Example: src/db/schema-example.ts (to understand the pattern)

- Reference: [section of plan to reference]
  Example: "Database Schema" section of plan

- Patterns: [existing patterns to follow]
  Example: Follow the table definition pattern in existing schema files

WORK:
[Specific tasks to complete in this phase]
Example:
1. Create src/db/schema.ts file
2. Define User table with pgTable
3. Define Product table with proper relations
4. Export all table definitions
5. Add TypeScript types for insert/select

OUTPUTS:
- Create: [files to create]
  Example: src/db/schema.ts, src/db/types.ts

- Modify: [files to modify]
  Example: src/db/index.ts (add schema export)

RULES:
- Implement exactly according to requirements
- Follow existing code patterns in the codebase
- Use proper TypeScript types (no "any" types)
- Add error handling where appropriate
- Do NOT validate your own work (validator will check)
- Do NOT run tests yourself
- Focus only on implementation
- Do NOT start the dev server

NO-SLOP POLICY (MANDATORY):
- NO `any`, `as any`, `: any` ANYWHERE
- NO placeholder code, NO `// TODO`, NO `// FIXME`
- NO unused imports, NO unused variables — if a variable is not used, it must not exist
- NO console.log hacks to suppress errors. NO void hacks.
- Use `import type` for type-only imports (`verbatimModuleSyntax: true`)
- External imports first, blank line, then local imports
- ONE query/mutation per file, named export

REPORT BACK:
When complete, report:
- Files created: [list with paths]
- Files modified: [list with paths]
- Confirmation: "Implementation complete, ready for validation"
- Any blockers encountered: [describe any issues]

Example: Database Schema Implementer

ROLE: Implementer
PHASE: 1 - Database Schema

MISSION:
Implement the database schema for the e-commerce system using Drizzle ORM.

PLAN REQUIREMENTS:
- Define User table with id (serial primary key), email (text unique), password_hash (text), created_at (timestamp)
- Define Product table with id, name, description, price (decimal), stock (integer)
- Define Order table with id, user_id (FK to User), total (decimal), status (enum), created_at
- Define OrderItem table with id, order_id (FK to Order), product_id (FK to Product), quantity, price
- All foreign keys must have onDelete actions defined
- All timestamps default to NOW()
- Export all tables and create TypeScript types

INPUTS:
- Read first: None (first phase)
- Reference: Drizzle ORM documentation for pgTable syntax
- Patterns: Standard Drizzle schema patterns

WORK:
1. Create src/db/schema.ts
2. Import necessary functions from drizzle-orm/pg-core
3. Define users table with all required fields
4. Define products table with all required fields
5. Define orders table with user_id foreign key
6. Define order_items table with order_id and product_id foreign keys
7. Create TypeScript types for each table (InsertUser, User, etc.)
8. Export all tables and types

OUTPUTS:
- Create: src/db/schema.ts

RULES:
- Use Drizzle ORM pgTable syntax
- No "any" types in TypeScript
- All foreign keys must specify onDelete behavior
- Timestamps use timestamp() with defaultNow()
- Export everything that will be needed by other modules
- Do NOT validate - validator will check

REPORT BACK:
- Files created: src/db/schema.ts
- Confirmation: Implementation complete, ready for validation
- Any blockers: [none expected]

Validator Template

Full Template

ROLE: Validator
PHASE: [number] - [name]

MISSION:
Check that the implementation meets ALL requirements from the plan. You are NOT to modify any code - only validate it. If issues are found, report them clearly so a fixer can address them.

IMPLEMENTATION TO CHECK:
[Files that were created or modified by the implementer]
Example:
- src/db/schema.ts (created)
- src/db/index.ts (modified)

REQUIREMENTS FROM PLAN:
[Copy the exact requirements from the plan]
Example:
- User table must have id, email, password_hash, created_at
- Foreign keys must be defined with onDelete actions
- No "any" types allowed
- All tables must be exported

VALIDATION CHECKLIST:

□ STEP 1: Type Check (if applicable)
  Command: [project's type check command]
  Examples: pnpm run check-types, tsc --noEmit, mypy ., cargo check
  Expected: Zero type errors
  If fails: Note all type errors with file and line numbers

□ STEP 2: Build/Compile (if applicable)
  Command: [project's build command]
  Examples: pnpm run build, npm run build, cargo build, make
  Expected: Build succeeds
  If fails: Note all build errors

□ STEP 3: Code Quality (always applicable)
  Run: [project's quality checks]
  Examples: linting, formatting checks, unit tests if specified in plan
  Expected: All checks pass
  If fails: Note specific issues

□ STEP 4: Code Review (always applicable)
  Check each requirement:

  □ Requirement 1: [specific requirement]
     Status: [✓ Met / ✗ Not met]
     Notes: [if not met, explain what's wrong]

  □ Requirement 2: [specific requirement]
     Status: [✓ Met / ✗ Not met]
     Notes: [if not met, explain what's wrong]

  [Continue for all requirements...]

□ STEP 5: Code Quality Review
   □ Follows existing patterns in codebase?
   □ Proper types (no loose/any types if statically typed)?
   □ Proper error handling where needed?
   □ Correct exports (everything needed is exported)?
   □ Code is readable and well-organized?

□ STEP 6: NO-SLOP Policy Enforcement (MANDATORY — be STRINGENT)
   □ NO `any`, `as any`, `: any` anywhere?
   □ NO placeholder code, NO `// TODO`, NO `// FIXME`?
   □ NO unused imports, NO unused variables?
   □ NO console.log hacks, NO void hacks?
   □ Type-only imports use `import type`?
   □ External imports first, blank line, then local imports?
   □ ONE query/mutation per file, named export?
   
   If ANY of these fail, the validation FAILS. No exceptions.

OUTPUT FORMAT:

**Status**: PASS or FAIL

If PASS:
- All requirements met
- Type check: ✓
- Build: ✓
- Ready to proceed to next phase

If FAIL:
**Critical Issues** (must fix):
1. [File path:line] - [specific issue]
   Example: src/db/schema.ts:15 - Missing onDelete on user_id foreign key

2. [File path:line] - [specific issue]
   Example: src/db/schema.ts:23 - Using "any" type for created_at

**Warnings** (should fix):
1. [File path:line] - [specific issue]

**What needs to be fixed**:
- Add onDelete: 'cascade' to user_id foreign key in orders table
- Change created_at type from any to timestamp()
- Export OrderItem type (currently not exported)

RULES:
- Be thorough - check EVERY requirement
- Do NOT modify code - only report issues
- Provide specific file paths and line numbers
- Distinguish between critical issues and warnings
- If everything passes, clearly state PASS

Example: Database Schema Validator

ROLE: Validator
PHASE: 1 - Database Schema

MISSION:
Validate that the database schema implementation meets all requirements.

IMPLEMENTATION TO CHECK:
- src/db/schema.ts (created by implementer)

REQUIREMENTS FROM PLAN:
- User table: id (serial PK), email (text unique), password_hash (text), created_at (timestamp)
- Product table: id, name, description, price (decimal), stock (integer)
- Order table: id, user_id (FK to User), total (decimal), status (enum), created_at
- OrderItem table: id, order_id (FK to Order), product_id (FK to Product), quantity, price
- All FKs have onDelete actions
- All timestamps default to NOW()
- All tables and types exported

VALIDATION CHECKLIST:

□ STEP 1: Type Check
  Command: pnpm run check-types
  Expected: Zero type errors

□ STEP 2: Build Check
  Command: pnpm run build
  Expected: Build succeeds

□ STEP 3: Code Review

  □ User table has all required fields
     Status: [check each field]

  □ Product table has all required fields
     Status: [check each field]

  □ Order table has FK to User with onDelete
     Status: [verify FK and onDelete present]

  □ OrderItem table has FKs to Order and Product
     Status: [verify both FKs]

  □ Timestamps use defaultNow()
     Status: [check all timestamp fields]

  □ All tables exported
     Status: [verify exports]

  □ TypeScript types created and exported
     Status: [verify InsertUser, User, etc.]

□ STEP 4: Code Quality
  □ No "any" types
  □ Proper Drizzle syntax
  □ Readable and organized

OUTPUT:
**Status**: [PASS or FAIL]

[If FAIL, list all issues with file:line numbers and specific fixes needed]

Fixer Template

Full Template

ROLE: Fixer
PHASE: [number] - [name]

MISSION:
Fix ALL issues reported by the validator. Your job is to make changes to the code so that it passes validation. Do NOT skip any issues - fix every single one.

VALIDATOR REPORT:
[Copy the FULL validator output here, including all issues]

ISSUES TO FIX:

Critical Issues:
1. [File:line] - [issue]
   Required fix: [what needs to be done]

2. [File:line] - [issue]
   Required fix: [what needs to be done]

[List ALL issues from validator report]

Warnings:
1. [File:line] - [issue]
   Required fix: [what needs to be done]

FILES TO MODIFY:
[List all files that have issues]
Example:
- src/db/schema.ts
- src/api/routes.ts

WORK:
For each issue:
1. Open the file
2. Locate the exact line
3. Make the fix
4. Verify the fix follows existing patterns
5. Move to next issue

RULES:
- Fix ALL issues - don't skip any
- Don't introduce new problems
- Match the existing code style
- Use the same patterns as existing code
- If a fix requires adding imports, add them
- Don't remove working code unnecessarily
- Make minimal changes - only fix what's broken
- Fix ALL validator errors at once, not one at a time

NO-SLOP POLICY (MANDATORY — fixes must meet the same quality bar):
- NO `any`, `as any`, `: any` ANYWHERE
- NO placeholder code, NO `// TODO`, NO `// FIXME`
- NO unused imports, NO unused variables
- Use `import type` for type-only imports
- External imports first, blank line, then local imports
- ONE query/mutation per file, named export

REPORT BACK:
When complete:
- Issues fixed: [list each one]
- Files modified: [list files]
- Changes made: [brief description of each change]
- Confirmation: "All issues fixed, ready for re-validation"

Example: Database Schema Fixer

ROLE: Fixer
PHASE: 1 - Database Schema

MISSION:
Fix all issues found in the schema validation.

VALIDATOR REPORT:
**Status**: FAIL

**Critical Issues**:
1. src/db/schema.ts:42 - Missing onDelete on user_id foreign key in orders table
2. src/db/schema.ts:58 - Using "any" type for created_at in order_items table
3. src/db/schema.ts:75 - OrderItem type not exported (needed by other modules)

**Warnings**:
1. src/db/schema.ts:12 - Consider adding index on email field for faster lookups

**What needs to be fixed**:
- Add onDelete: 'cascade' to user_id foreign key
- Change created_at from any to timestamp().defaultNow()
- Export OrderItem type
- (Optional) Add index to email field

ISSUES TO FIX:

Critical Issues:
1. src/db/schema.ts:42 - Missing onDelete
   Fix: Add .references(() => users.id, { onDelete: 'cascade' })

2. src/db/schema.ts:58 - Wrong type for created_at
   Fix: Change to timestamp('created_at').defaultNow()

3. src/db/schema.ts:75 - OrderItem type not exported
   Fix: Add "export type OrderItem = typeof orderItems.$inferSelect"

Warnings:
1. src/db/schema.ts:12 - Add email index
   Fix: Add .index() to email field

FILES TO MODIFY:
- src/db/schema.ts

WORK:
1. Fix line 42: Add onDelete to user_id FK
2. Fix line 58: Change created_at to proper timestamp type
3. Fix line 75: Export OrderItem type
4. Fix line 12: Add index to email field

RULES:
- Fix all 4 issues
- Don't change anything else
- Match the Drizzle syntax used elsewhere
- Keep the same formatting style

REPORT BACK:
Issues fixed:
1. Added onDelete: 'cascade' to user_id FK in orders table (line 42)
2. Changed created_at to timestamp().defaultNow() in order_items (line 58)
3. Added export for OrderItem type (line 75)
4. Added index() to email field in users table (line 12)

Files modified:
- src/db/schema.ts

Changes made:
- Fixed foreign key reference to include onDelete behavior
- Corrected TypeScript type for timestamp field
- Exported missing type
- Added performance index

Confirmation: All issues fixed, ready for re-validation

Dispatch Guidelines

When to Dispatch Implementer

Dispatch implementer when:

• Starting a new phase
• Creating new files
• Adding new functionality
• Implementing requirements from plan

Provide implementer with:

• Clear requirements from plan
• List of files to read/reference
• List of files to create/modify
• Any existing patterns to follow

When to Dispatch Validator

Dispatch validator when:

• Implementer reports completion
• After fixer makes changes
• Before moving to next phase

Provide validator with:

• Files to check
• Original requirements from plan
• Validation criteria (type check, build, code review)

When to Dispatch Fixer

Dispatch fixer when:

• Validator returns FAIL status
• Specific issues identified

Provide fixer with:

• Complete validator report
• List of all issues
• Files that need modification

Iteration Flow

Implementer
    ↓
Validator
    ↓
  PASS? ──Yes──> Next phase
    ↓
   No
    ↓
Fixer
    ↓
Validator
    ↓
  PASS? ──Yes──> Next phase
    ↓
   No
    ↓
[Repeat up to 3 times total]
    ↓
Still FAIL? ──> HALT and report to user

Tips for Effective Dispatch

1. Be Specific

Don't say "implement the feature" - list exactly what needs to be done.

2. Reference the Plan

Always include the relevant section of the plan in the dispatch.

3. Set Clear Boundaries

Tell implementer: "Do NOT validate" Tell validator: "Do NOT modify code" Tell fixer: "Fix ALL issues, not just some"

4. Include Context

Provide enough context that the subagent can work independently.

5. Request Detailed Reports/

Ask for specific confirmation of what was done, not just "done."

6. Handle Parallel Dispatches

When dispatching parallel implementers:

• Make sure each has independent tasks
• Each gets their own validator
• Track each one separately

Workflow Patterns

Common patterns for orchestrating sequential and parallel phases in multi-phase development workflows.

IMPORTANT: You (the orchestrator agent) execute these patterns through natural language by dispatching subagents. There is NO code that runs this orchestration - you make decisions and dispatch implementers/validators/fixers through conversation. The "Agent Execution Flow" sections describe what YOU do, not what code does.

Sequential Workflow

Execute phases one at a time, each depending on the previous.

Pattern

Phase 1 → Validate → Pass
    ↓
Phase 2 → Validate → Pass
    ↓
Phase 3 → Validate → Pass
    ↓
Complete

When to Use

Use sequential workflow when:

• Each phase depends on outputs from the previous phase
• Order matters significantly
• Parallel execution would create conflicts
• Testing must happen in sequence

Example: API Development

Phase 1: Database Schema
├─ Implementer: Create schema.ts
├─ Validator: Check types, verify exports
└─ Result: schema.ts ✓

Phase 2: Database Client
├─ Implementer: Create client.ts (uses schema.ts)
├─ Validator: Check connection, verify types
└─ Result: client.ts ✓

Phase 3: Service Layer
├─ Implementer: Create services/*.ts (uses client.ts)
├─ Validator: Check business logic, verify types
└─ Result: services/*.ts ✓

Phase 4: API Routes
├─ Implementer: Create routes/*.ts (uses services/*.ts)
├─ Validator: Check endpoints, verify types
└─ Result: routes/*.ts ✓

Agent Execution Flow

As the orchestrator agent, you: 1. Execute Phase 1 → dispatch implementer → wait for completion 2. Dispatch validator → wait for PASS/FAIL 3. If FAIL → dispatch fixer → re-validate (repeat up to 3 attempts) 4. If PASS → move to Phase 2 5. Repeat for each phase in sequence

No code runs this - YOU execute each step by dispatching subagents through conversation.

Parallel Workflow

Execute multiple independent tasks simultaneously, then validate each.

Pattern

Phase 3: Parallel Execution
├─ Task A → Validate A → Pass
├─ Task B → Validate B → Pass
└─ Task C → Validate C → Pass
    ↓
All Pass → Continue

When to Use

Use parallel workflow when:

• Tasks are independent (no shared file edits)
• Order doesn't matter within the phase
• Can speed up execution significantly
• Each task can be validated separately

Example: Service Layer

Phase 3: Core Services (Parallel)

Task 3.1: User Service
├─ Implementer A: Create user.service.ts
├─ Validator A: Check user operations
└─ Result: user.service.ts ✓

Task 3.2: Product Service
├─ Implementer B: Create product.service.ts
├─ Validator B: Check product operations
└─ Result: product.service.ts ✓

Task 3.3: Order Service
├─ Implementer C: Create order.service.ts
├─ Validator C: Check order operations
└─ Result: order.service.ts ✓

Integration Validation:
├─ Check: All services work together
├─ Check: Type check passes for all
├─ Check: Build succeeds
└─ Result: Phase 3 complete ✓

Agent Execution Flow

As the orchestrator agent, you: 1. Dispatch all 3 implementers simultaneously (in same message or separate) 2. Wait for all 3 to report completion 3. Dispatch validator for Task 3.1 → get result 4. Dispatch validator for Task 3.2 → get result 5. Dispatch validator for Task 3.3 → get result 6. For any that FAIL → dispatch fixer for that specific task → re-validate 7. Once ALL pass → run integration check (type check + build for all files together) 8. If integration PASS → move to Phase 4

You're making decisions and dispatching subagents, not running code.

Mixed Sequential + Parallel

Combine both patterns for complex workflows.

Pattern

Phase 1 (Sequential)
    ↓
Phase 2 (Sequential)
    ↓
Phase 3 (Parallel)
├─ Task A
├─ Task B
└─ Task C
    ↓
Phase 4 (Sequential)
    ↓
Phase 5 (Parallel)
├─ Task D
└─ Task E
    ↓
Complete

Example: Full-Stack Application

Phase 1: Database Setup (Sequential)
└─ Create schema, migrations, client

Phase 2: Environment Config (Sequential)
└─ Set up .env, config loader, validation

Phase 3: Backend Services (Parallel)
├─ Auth service
├─ User service
├─ Product service
└─ Order service

Phase 4: API Layer (Sequential)
└─ Create Express app, routes, middleware

Phase 5: Frontend Components (Parallel)
├─ Auth components
├─ Product list component
├─ Cart component
└─ Checkout component

Phase 6: Integration (Sequential)
└─ Wire frontend to backend, test flows

Agent Execution Flow

As the orchestrator agent, you execute each phase in order by dispatching the appropriate subagents:

Phase 1: Dispatch implementer for database setup → validate → fix if needed → pass → continue

Phase 2: Dispatch implementer for environment config → validate → fix if needed → pass → continue

Phase 3 (Parallel):

• Dispatch implementers for all 4 services simultaneously
• Validate each service independently
• Fix any that fail
• Run integration check once all pass
• Continue

Phase 4: Dispatch implementer for API layer → validate → fix if needed → pass → continue

Phase 5 (Parallel):

• Dispatch implementers for all 4 components simultaneously
• Validate each component
• Fix any that fail
• Run integration check
• Continue

Phase 6: Dispatch implementer for integration work → validate → fix if needed → pass → complete

You execute this flow through agent dispatching, not code.

Dependency Patterns

Linear Dependencies

Each phase depends on the immediately previous one.

Phase 1 ──> Phase 2 ──> Phase 3 ──> Phase 4

Example:

Schema ──> Client ──> Services ──> API

Multi-Level Dependencies

Later phases depend on multiple earlier phases.

Phase 1 ──┐
          ├──> Phase 3
Phase 2 ──┘

Example:

Database Schema ──┐
                  ├──> Service Layer
Auth Setup ───────┘

Diamond Dependencies

Converge and diverge.

      Phase 1
         ↓
    ┌────┴────┐
    ↓         ↓
Phase 2A  Phase 2B
    ↓         ↓
    └────┬────┘
         ↓
      Phase 3

Example:

      Database
         ↓
    ┌────┴────┐
    ↓         ↓
  Users    Products
    ↓         ↓
    └────┬────┘
         ↓
      Orders

Error Recovery Patterns

Retry with Backoff

Attempt 1: Implementer → Validator → FAIL
    ↓
Attempt 2: Fixer → Validator → FAIL
    ↓
Attempt 3: Fixer → Validator → FAIL
    ↓
HALT and report

Partial Success

When some parallel tasks succeed and others fail:

Phase 3 (Parallel)
├─ Task A → ✓ PASS
├─ Task B → ✗ FAIL → Fix → ✓ PASS
└─ Task C → ✓ PASS
    ↓
All Pass → Continue

Cascading Failure

If one task in a parallel phase fails after max attempts:

Phase 3 (Parallel)
├─ Task A → ✓ PASS
├─ Task B → ✗ FAIL (max attempts)
└─ Task C → ✓ PASS (but phase fails)
    ↓
HALT entire phase
Report: "Phase 3 failed: Task B could not pass validation"

Integration Patterns

Post-Phase Integration Check

After all tasks in a parallel phase complete:

Phase 3 (Parallel)
├─ Task A → ✓
├─ Task B → ✓
└─ Task C → ✓
    ↓
Integration Check:
├─ Type check all files together → ✓
├─ Build entire project → ✓
└─ Check imports/exports → ✓
    ↓
Continue

Cross-Phase Integration

Check integration between phases:

Phase 2 complete
Phase 3 complete
    ↓
Integration Check:
├─ Does Phase 3 correctly use Phase 2 outputs?
├─ Are all imports correct?
└─ Do types align?
    ↓
If FAIL → Fix cross-phase issues

Complete Workflow Example

E-Commerce Platform

========================================
Phase 1: Foundation (Sequential)
========================================
Task: Database Schema
├─ Implementer: Create tables
├─ Validator: Verify schema
└─ Status: ✓ PASS

========================================
Phase 2: Database Client (Sequential)
========================================
Task: Connection & ORM
├─ Implementer: Create client
├─ Validator: Test connection
└─ Status: ✓ PASS

========================================
Phase 3: Core Services (Parallel)
========================================
Task 3.1: User Service
├─ Implementer A: Create user CRUD
├─ Validator A: Check operations
└─ Status: ✓ PASS

Task 3.2: Product Service
├─ Implementer B: Create product CRUD
├─ Validator B: Check operations
└─ Status: ✗ FAIL
    ├─ Fixer B: Fix type issues
    ├─ Validator B: Re-check
    └─ Status: ✓ PASS

Task 3.3: Order Service
├─ Implementer C: Create order logic
├─ Validator C: Check operations
└─ Status: ✓ PASS

Integration Check:
├─ Type check: ✓
├─ Build: ✓
└─ Status: ✓ ALL PASS

========================================
Phase 4: API Routes (Sequential)
========================================
Task: Express Routes
├─ Implementer: Create endpoints
├─ Validator: Check routes
└─ Status: ✓ PASS

========================================
Phase 5: Frontend (Parallel)
========================================
Task 5.1: Product List Component
├─ Implementer A: Create component
├─ Validator A: Check rendering
└─ Status: ✓ PASS

Task 5.2: Cart Component
├─ Implementer B: Create component
├─ Validator B: Check state mgmt
└─ Status: ✓ PASS

Integration Check:
├─ Build: ✓
└─ Status: ✓ ALL PASS

========================================
Execution Complete
========================================
Total Phases: 5
Total Tasks: 8
Fix Iterations: 1
Status: ✓ SUCCESS

Best Practices

Planning Parallel Phases

✓ DO:

• Ensure tasks are truly independent
• Check for file conflicts before parallel dispatch
• Validate each task independently
• Run integration check after all complete

✗ DON'T:

• Let parallel tasks modify the same file
• Skip integration validation
• Assume parallel = faster without checking dependencies

Planning Sequential Phases

✓ DO:

• Make dependencies explicit
• Pass outputs clearly to next phase
• Validate before proceeding
• Stop immediately on failure

✗ DON'T:

• Continue with missing dependencies
• Skip phases assuming "it'll work"
• Let phases be too large (break them down)

Mixing Patterns

✓ DO:

• Use sequential for foundation/setup phases
• Use parallel for independent feature work
• Return to sequential for integration
• Document why each pattern is chosen

✗ DON'T:

• Over-parallelize (diminishing returns)
• Under-parallelize (missing optimization opportunities)
• Mix patterns without clear reasoning