hierarchical-coordinator

# Hierarchical Coordinator **Version:** 1.0.0 **Purpose:** Prevent goal drift in multi-agent workflows through coordinated checkpoint validation **Status:** Production Ready ## Overview Multi-agent workflows suffer from a fundamental problem: **goal drift**. As agents execute phases sequentially, each agent interprets its instructions through its own lens, gradually diverging from the original user intent. By phase 4 of a 6-phase workflow, the output may address a subtly different problem than what the user requested. **The Problem:** ``` User Request: "Add pagination to the products API endpoint" Phase 1 (Architect): Plans pagination with cursor-based approach Drift: None (directly from user request) Phase 2 (Developer): Implements cursor pagination + adds sorting + filtering Drift: LOW (scope creep - sorting/filtering not requested) Phase 3 (Tester): Writes tests for sorting and filtering, light coverage on pagination Drift: MEDIUM (testing unrequested features, under-testing requested ones) Phase 4 (Reviewer): Reviews sorting/filtering implementation quality Drift: HIGH (reviewing features user never asked for) Result: User gets pagination + unrequested sorting/filtering, but pagination edge cases are untested. ``` **The Solution:** A **coordinator agent** sits above specialist agents, holding the original requirements as immutable context. After each phase, the coordinator validates the output against the original goals before allowing the next phase to proceed. If drift is detected, the coordinator issues corrective guidance. ``` +---------------------+ | COORDINATOR | | Holds: Requirements | | Holds: Success | | Criteria | +---------------------+ | | | | Validate | OK | OK | DRIFT v v v v +----+ +----+ +----+ +----+ | P1 | | P2 | | P3 | | P3 | | OK | | OK | | !! | | FIX| +----+ +----+ +----+ +----+ ``` **When to Use This Skill:** - Workflows with 3+ agents executing sequentially - Multi-phase feature implementations (plan, build, test, review) - Complex refactoring tasks spanning multiple files or systems - Any workflow where the final output must precisely match original requirements - Long-running workflows (>15 minutes) where drift accumulates over time **When NOT to Use:** - Simple 1-2 agent workflows (overhead exceeds benefit) - Parallel-only workflows (no sequential drift accumulation) - Quick tasks (<5 minutes) where drift is unlikely --- ## The Coordinator Pattern ### Coordinator Role Definition The coordinator is NOT a specialist. It does not write code, design architecture, or run tests. Its sole responsibility is **goal alignment**: ``` Coordinator Responsibilities: 1. RECEIVE original requirements and success criteria from user 2. DECOMPOSE task into phases with clear deliverables 3. SPAWN specialist agents for each phase 4. VALIDATE each phase output against original goals 5. CORRECT drift before allowing next phase 6. REPORT final alignment status to user Coordinator Does NOT: - Write code (delegate to developer agent) - Design architecture (delegate to architect agent) - Run tests (delegate to tester agent) - Make subjective decisions (escalate to user) ``` ### Coordinator Initialization Before any work begins, the coordinator captures the immutable context: ``` Step 0: Coordinator Initialization Write: ai-docs/coordinator-context.md # Coordinator Context (IMMUTABLE) ## Original User Request "[Exact user request, verbatim]" ## Success Criteria 1. [Specific, measurable criterion 1] 2. [Specific, measurable criterion 2] 3. [Specific, measurable criterion 3] ## Scope Boundaries IN SCOPE: - [What the user explicitly asked for] OUT OF SCOPE: - [What the user did NOT ask for] - [Adjacent features that seem related but were not requested] ## Phases Phase 1: [Name] - Deliverable: [specific output] Phase 2: [Name] - Deliverable: [specific output] Phase 3: [Name] - Deliverable: [specific output] Phase 4: [Name] - Deliverable: [specific output] This file is READ-ONLY during workflow execution. No agent may modify it. Only the coordinator reads it. ``` ### Coordinator Execution Flow ``` Full Coordinator Workflow: Step 1: Initialize coordinator context Write ai-docs/coordinator-context.md (requirements, criteria, scope) Step 2: Initialize Tasks (all phases visible upfront) [ ] PHASE 1: [Architecture/Planning] [ ] CHECKPOINT 1: Validate Phase 1 alignment [ ] PHASE 2: [Implementation] [ ] CHECKPOINT 2: Validate Phase 2 alignment [ ] PHASE 3: [Testing] [ ] CHECKPOINT 3: Validate Phase 3 alignment [ ] PHASE 4: [Review] [ ] CHECKPOINT 4: Final alignment validation Step 3: Execute Phase 1 Task: specialist-agent Prompt: "Read ai-docs/coordinator-context.md for requirements. Execute Phase 1 deliverables." Output: [phase 1 artifacts] Step 4: Checkpoint 1 (Coordinator validates) Read: Phase 1 output artifacts Read: ai-docs/coordinator-context.md (original requirements) Evaluate: Does output align with requirements? Write: ai-docs/checkpoint-1.md (validation result) Step 5: Gate Decision If ALIGNED: Proceed to Phase 2 If DRIFTED: Corrective action (see Anti-Drift Checkpoints) Step 6-N: Repeat for each phase Execute phase -> Checkpoint -> Gate decision -> Next phase ``` --- ## Anti-Drift Checkpoints ### What a Checkpoint Validates Each checkpoint answers three questions: ``` Checkpoint Validation Questions: 1. COMPLETENESS: Does the output address ALL requirements? - Check each success criterion - Flag any missing deliverables - Score: N/M criteria addressed 2. RELEVANCE: Does the output ONLY address requirements? - Detect scope creep (unrequested features) - Detect tangential work (related but not requested) - Flag any out-of-scope additions 3. QUALITY: Does the output meet the expected standard? - Deliverable exists and is non-empty - Deliverable is actionable (next phase can use it) - No placeholder or stub content ``` ### Checkpoint Format Structure every checkpoint evaluation consistently: ``` # Checkpoint [N]: Phase [Name] Validation ## Alignment Score: [ALIGNED | MINOR_DRIFT | MAJOR_DRIFT | OFF_TRACK] ## Completeness (Requirements Coverage) - [x] Criterion 1: "Add pagination to products endpoint" Evidence: src/routes/products.ts implements cursor-based pagination - [x] Criterion 2: "Support page size parameter" Evidence: Query parameter `limit` accepts 1-100 values - [ ] Criterion 3: "Return total count in response" MISSING: Response does not include total record count Score: 2/3 criteria met ## Relevance (Scope Adherence) - OUT OF SCOPE: Added sorting by price (not requested) Files affected: src/routes/products.ts lines 45-67 - OUT OF SCOPE: Added filtering by category (not requested) Files affected: src/routes/products.ts lines 70-92 Score: 2 out-of-scope additions detected ## Quality - Deliverable exists: Yes - Actionable for next phase: Yes - Placeholder content: None ## Verdict: MINOR_DRIFT - Missing: Total count in response (Criterion 3) - Extra: Sorting and filtering (not requested) ## Corrective Action - ADD: Total count field in paginated response - REMOVE: Sorting implementation (lines 45-67) - REMOVE: Filtering implementation (lines 70-92) - RE-FOCUS: Next phase should test pagination only ``` ### Drift Severity Levels ``` ALIGNED (No Drift): - All criteria addressed - No out-of-scope additions - Quality threshold met Action: Proceed to next phase MINOR_DRIFT (Low Severity): - Most criteria addressed (>80%) - Small out-of-scope additions - Quality acceptable Action: Issue corrective guidance, proceed with adjustments MAJOR_DRIFT (High Severity): - Significant criteria gaps (<80% addressed) - Large out-of-scope work - Quality concerns Action: Re-run phase with corrective instructions OFF_TRACK (Critical): - Output does not address original requirements - Completely wrong direction - Fundamental misunderstanding Action: Escalate to user, re-evaluate approach ``` ### Corrective Actions When drift is detected, the coordinator takes structured action: ``` Corrective Action Flow: MINOR_DRIFT: 1. Write corrective guidance to file: Write: ai-docs/correction-phase-N.md "Phase N produced minor drift: - Missing: [specific gaps] - Extra: [out-of-scope additions] Correction: [specific instructions for next agent]" 2. Provide corrective context to next phase agent: Task: next-specialist Prompt: "Read ai-docs/coordinator-context.md for requirements. Read ai-docs/correction-phase-N.md for corrections. Execute Phase N+1 WITH corrections applied." MAJOR_DRIFT: 1. Write detailed correction: Write: ai-docs/correction-phase-N.md "Phase N produced major drift. Re-run required. Missing requirements: [list] Out-of-scope work to remove: [list] Specific re-run instructions: [detailed guidance]" 2. Re-run the same phase with corrective instructions: Task: same-specialist Prompt: "Read ai-docs/coordinator-context.md for requirements. Read ai-docs/correction-phase-N.md for corrections. RE-DO Phase N following correction guidance." 3. Re-validate at checkpoint (max 2 re-runs per phase) OFF_TRACK: 1. Stop workflow immediately 2. Present user with: "Phase N output does not align with original requirements. Original request: [verbatim user request] Phase N produced: [summary of what was built] This appears to be a fundamental misalignment. How would you like to proceed? 1. Provide clarified requirements 2. Re-start from Phase 1 3. Cancel workflow" ``` ### Maximum Drift Tolerance Set limits to prevent infinite correction loops: ``` Drift Tolerance Limits: Per-phase re-runs: Maximum 2 After 2 re-runs of the same phase, escalate to user: "Phase N has been re-run twice but still shows drift. Manual review needed." Consecutive minor drifts: Maximum 3 If 3 phases in a row show MINOR_DRIFT, escalate: "Multiple consecutive phases showing drift. Requirements may need clarification." Total workflow corrections: Maximum 5 If 5 total corrections across all phases, pause: "Workflow has required 5 corrections. Recommend reviewing requirements before continuing." ``` --- ## Shared State via Tasks ### Cross-Agent State Management Tasks serves as the coordinator's shared state mechanism. Beyond progress tracking, it carries context between phases: ``` Tasks as Shared State: Standard progress tracking: [ ] PHASE 1: Architecture planning [ ] PHASE 2: Implementation Enhanced with coordinator state: [ ] PHASE 1: Architecture planning [ ] CHECKPOINT 1: Validate architecture alignment [ ] PHASE 2: Implementation [ ] CHECKPOINT 2: Validate implementation alignment [ ] DRIFT_CHECK: Overall alignment status ``` ### State Format Conventions Use prefixed entries to distinguish state types: ``` Tasks State Prefixes: PHASE: - Standard phase tracking CHECKPOINT: - Coordinator validation point CONTEXT: - Shared context between agents DRIFT: - Drift detection result CORRECTION: - Corrective action applied Example Tasks State: [x] PHASE 1: Architecture planning [x] CHECKPOINT 1: ALIGNED (3/3 criteria met) [x] CONTEXT: Architecture uses cursor-based pagination [x] PHASE 2: Implementation [x] CHECKPOINT 2: MINOR_DRIFT (2/3 criteria, scope creep detected) [x] CORRECTION: Removed sorting, added total count [->] PHASE 3: Testing [ ] CHECKPOINT 3: Validate test coverage [ ] PHASE 4: Code review [ ] CHECKPOINT 4: Final alignment check ``` ### Key Findings Propagation The coordinator writes key findings that subsequent agents must read: ``` Pattern: Coordinator Writes, Next Agent Reads After Checkpoint 1: Coordinator writes to ai-docs/phase-1-findings.md: "KEY_FINDINGS: - Architecture: cursor-based pagination with offset fallback - Data model: Products table has 50k+ rows - Constraint: Must maintain backward compatibility with v1 API - Decision: Use cursor over offset for performance CONTEXT FOR PHASE 2: - Implement cursor pagination as designed - Include total_count field in response - Do NOT add sorting or filtering (out of scope) - Maintain v1 API contract" Phase 2 agent reads this file before starting: Task: developer Prompt: "Read ai-docs/coordinator-context.md for requirements. Read ai-docs/phase-1-findings.md for architecture context. Implement pagination per architecture plan." ``` ### Clean State Between Phases Prevent state pollution by keeping phase artifacts isolated: ``` State Isolation Pattern: ai-docs/ coordinator-context.md # Immutable - original requirements phase-1-findings.md # Phase 1 output + coordinator notes checkpoint-1.md # Checkpoint 1 validation result phase-2-findings.md # Phase 2 output + coordinator notes checkpoint-2.md # Checkpoint 2 validation result correction-phase-2.md # Correction applied (if drift) phase-3-findings.md # Phase 3 output + coordinator notes checkpoint-3.md # Checkpoint 3 validation result Each phase agent reads: 1. coordinator-context.md (always - original requirements) 2. phase-N-1-findings.md (previous phase output) 3. correction-phase-N-1.md (if corrections were applied) Each phase agent writes: 1. Its own artifacts (code, tests, docs) 2. Brief summary for coordinator to validate ``` --- ## Phase Gate Pattern ### Gate Definition A phase gate is a formal decision point between workflow stages. The coordinator evaluates gate criteria and determines the next action: ``` Phase Gate Structure: +----------+ +----------+ +----------+ | Phase N | --> | GATE | --> | Phase | | Execute | | Evaluate | | N+1 | +----------+ +----------+ +----------+ | +---------+ | PROCEED | All criteria met | RETRY | Criteria gaps, re-run phase | ABORT | Critical failure, stop workflow +---------+ ``` ### Gate Criteria Every gate evaluates three dimensions: ``` Gate Criteria: 1. DELIVERABLES PRESENT - All expected output files exist - Files are non-empty and well-formed - No placeholder or TODO content 2. QUALITY THRESHOLD MET - Code compiles / tests pass (if applicable) - Architecture is sound (no obvious anti-patterns) - Output is actionable for next phase 3. DRIFT CHECK PASSED - Checkpoint validation score is ALIGNED or MINOR_DRIFT - No OFF_TRACK or unresolved MAJOR_DRIFT - Corrective actions applied (if any) Gate passes when ALL THREE dimensions are satisfied. ``` ### Gate Actions ``` PROCEED: All criteria met. Move to next phase. Log: "Gate N passed. Proceeding to Phase N+1." TaskUpdate: Mark CHECKPOINT N as completed. RETRY: One or more criteria not met, but recoverable. Log: "Gate N failed. Re-running Phase N with corrections." Write: correction file with specific guidance. Re-execute Phase N (max 2 retries per gate). Re-evaluate gate after retry. ABORT: Critical failure or max retries exceeded. Log: "Gate N failed after 2 retries. Aborting workflow." Save partial results. Present user with: "Workflow stopped at Phase N gate. Reason: [specific failure] Partial results saved to ai-docs/ Options: Provide clarification, restart, or cancel." ``` ### Integration with Quality Gates Skill The phase gate pattern extends the quality-gates skill with drift awareness: ``` Quality Gates + Phase Gates: Standard Quality Gate (from quality-gates skill): - Issue severity classification - Iteration loop with max retries - User approval for expensive operations Phase Gate (adds coordinator validation): - All quality gate criteria PLUS - Drift check against original requirements - Scope adherence validation - Cross-phase context propagation Combined Flow: Phase N completes -> Quality Gate: Are there CRITICAL issues? (quality-gates) -> Phase Gate: Does output align with requirements? (coordinator) -> Both pass: Proceed -> Quality fails: Fix issues, re-validate -> Drift detected: Corrective action, re-validate -> Both fail: Fix both, re-run phase ``` --- ## Task Decomposition Patterns ### How to Break Down Complex Tasks The coordinator decomposes tasks based on natural phase boundaries: