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 pro

---

*Content truncated.*