conductor-orchestrator

name

conductor-orchestrator

description

Master coordinator for the Evaluate-Loop workflow v3. Supports GOAL-DRIVEN entry, PARALLEL execution via worker agents, BOARD OF DIRECTORS deliberation, and message bus coordination. Dispatches specialized workers dynamically, monitors via message bus, aggregates results. Uses metadata.json v3 for parallel state tracking. Use when: '/go <goal>', '/conductor implement', 'start track', 'run the loop', 'orchestrate', 'automate track'.

Conductor Orchestrator — Parallel Multi-Agent Coordinator (v3)

The master coordinator that runs the Evaluate-Loop for any track. Version 3 adds goal-driven entry, parallel execution via worker agents, Board of Directors deliberation, and message bus coordination.

---

Goal-Driven Entry (/go)

The simplest entry point. User states their goal, the system handles everything.

Usage

/go Add Stripe payment integration
/go Fix the login bug
/go Build an admin dashboard

Goal Processing Flow

async function processGoal(userGoal: string) {
  // 1. GOAL ANALYSIS
  const analysis = await analyzeGoal(userGoal);
  /*
    Returns:
    - intent: "feature" | "bugfix" | "refactor" | "research"
    - keywords: ["stripe", "payment", "checkout"]
    - complexity: "minor" | "moderate" | "major"
    - technical: boolean
  */

  // 2. CHECK EXISTING TRACKS
  const existingTrack = await findMatchingTrack(analysis.keywords);

  if (existingTrack) {
    // Resume existing track
    console.log(`Found existing track: ${existingTrack.id}`);
    return resumeOrchestration(existingTrack.id);
  }

  // 3. CREATE NEW TRACK
  const trackId = await createTrackFromGoal(userGoal, analysis);
  /*
    Creates:
    - conductor/tracks/{trackId}/
    - conductor/tracks/{trackId}/spec.md (generated from goal)
    - conductor/tracks/{trackId}/metadata.json (v3)
  */

  // 4. RUN FULL LOOP
  return runOrchestrationLoop(trackId);
}

Goal Analysis

async function analyzeGoal(goal: string) {
  // Use context-explorer to understand codebase
  const codebaseContext = await Task({
    subagent_type: "Explore",
    description: "Understand codebase for goal",
    prompt: `Analyze codebase to understand context for: "${goal}"

      Return:
      1. Related files/components
      2. Existing patterns to follow
      3. Dependencies needed
      4. Potential conflicts with existing code`
  });

  // Classify goal
  const intent = classifyIntent(goal);
  const keywords = extractKeywords(goal);
  const complexity = estimateComplexity(goal, codebaseContext);
  const technical = isTechnicalGoal(goal);

  return { intent, keywords, complexity, technical, codebaseContext };
}

function classifyIntent(goal: string): string {
  const lowerGoal = goal.toLowerCase();

  if (lowerGoal.match(/fix|bug|error|broken|crash|issue/)) return "bugfix";
  if (lowerGoal.match(/refactor|clean|optimize|improve|simplify/)) return "refactor";
  if (lowerGoal.match(/research|investigate|analyze|understand/)) return "research";
  return "feature";
}

Track Matching

async function findMatchingTrack(keywords: string[]): Track | null {
  const tracks = await readTracksFile();

  // Check in-progress tracks first
  const inProgress = tracks.filter(t =>
    t.status === 'IN_PROGRESS' || t.status === 'in_progress'
  );

  for (const track of inProgress) {
    const trackKeywords = extractKeywords(track.name + ' ' + track.description);
    const overlap = keywords.filter(k => trackKeywords.includes(k));

    if (overlap.length >= 2) {
      return track; // Good match
    }
  }

  // Check planned tracks
  const planned = tracks.filter(t =>
    t.status === 'NOT_STARTED' || t.status === 'planned'
  );

  for (const track of planned) {
    const trackKeywords = extractKeywords(track.name + ' ' + track.description);
    const overlap = keywords.filter(k => trackKeywords.includes(k));

    if (overlap.length >= 2) {
      return track;
    }
  }

  return null; // No match, create new track
}

Spec Generation from Goal

async function generateSpecFromGoal(goal: string, analysis: GoalAnalysis): string {
  const spec = await Task({
    subagent_type: "Plan",
    description: "Generate spec from goal",
    prompt: `Generate a specification document for this goal:

      GOAL: "${goal}"

      CODEBASE CONTEXT:
      ${analysis.codebaseContext}

      Create spec.md with:
      1. Overview - what we're building/fixing
      2. Requirements - specific deliverables
      3. Acceptance Criteria - how to verify it works
      4. Dependencies - what this needs
      5. Out of Scope - what we're NOT doing

      Be specific and actionable. Use the codebase context to identify:
      - Existing patterns to follow
      - Files that will be modified
      - Tests that need to pass

      Format as markdown.`
  });

  return spec.output;
}

Escalation During Goal Processing

// If goal is ambiguous, ask for clarification
if (analysis.ambiguous) {
  return askUserQuestion({
    questions: [{
      question: "I need clarification on your goal. Which do you mean?",
      header: "Clarify",
      options: analysis.interpretations.map(i => ({
        label: i.summary,
        description: i.detail
      })),
      multiSelect: false
    }]
  });
}

// If multiple tracks match, ask which one
if (matchingTracks.length > 1) {
  return askUserQuestion({
    questions: [{
      question: "This goal matches multiple existing tracks. Which one?",
      header: "Track",
      options: matchingTracks.map(t => ({
        label: t.name,
        description: `Status: ${t.status}`
      })),
      multiSelect: false
    }]
  });
}

---

Key Changes in v3

From v2

1. Metadata-based state detection — Reads loop_state.current_step from metadata.json
2. Lead Engineer consultation — Consults specialized leads for decisions
3. Resumption support — Exact state recovery if interrupted
4. Explicit checkpoints — Each step writes state to metadata.json
5. Learning Layer — Knowledge Manager + Retrospective Agent

New in v3

6. Parallel Execution — Multiple workers execute DAG tasks simultaneously
7. Board of Directors — 5-member expert deliberation at checkpoints
8. Message Bus — Inter-agent coordination via file-based queue
9. Worker Pool — Dynamic worker creation/cleanup via agent-factory
10. DAG-Aware Planning — Plans include explicit dependency graphs
11. Failure Isolation — One worker failure doesn't block independent tasks

---

State Detection (New v2 Protocol)

Primary: Read metadata.json

async function detectCurrentStep(trackId: string) {
  const metadataPath = `conductor/tracks/${trackId}/metadata.json`;
  const metadata = await readJSON(metadataPath);

  // Migrate v1 to v2 if needed
  if (!metadata.version || metadata.version < 2) {
    metadata = await migrateToV2(trackId, metadata);
    await writeJSON(metadataPath, metadata);
  }

  const { current_step, step_status } = metadata.loop_state;

  return { current_step, step_status, metadata };
}

State Machine Logic (v3)

Current Step	Step Status	Next Action
PLAN	NOT_STARTED	Dispatch loop-planner (with DAG generation)
PLAN	IN_PROGRESS	Resume loop-planner
PLAN	PASSED	Advance to EVALUATE_PLAN
EVALUATE_PLAN	NOT_STARTED	Dispatch loop-plan-evaluator + DAG validation
EVALUATE_PLAN	BOARD_REVIEW	NEW: Invoke Board of Directors if major track
EVALUATE_PLAN	PASSED	Advance to PARALLEL_EXECUTE
EVALUATE_PLAN	FAILED	Go back to PLAN with board conditions
PARALLEL_EXECUTE	NOT_STARTED	NEW: Initialize message bus, dispatch parallel workers
PARALLEL_EXECUTE	IN_PROGRESS	Monitor workers via message bus
PARALLEL_EXECUTE	PASSED	Advance to EVALUATE_EXECUTION
PARALLEL_EXECUTE	PARTIAL_FAIL	Handle failures, continue independent tasks
EVALUATE_EXECUTION	NOT_STARTED	Dispatch evaluators + quick board review
EVALUATE_EXECUTION	PASSED	Check business_sync_required → BUSINESS_SYNC or COMPLETE
EVALUATE_EXECUTION

---

Lead Engineer Consultation System

When to Consult Leads

Before escalating a decision to user, consult the appropriate Lead Engineer:

Question Category	Lead to Consult	Skill Path
Architecture, patterns, component organization	Architecture Lead	.claude/skills/leads/architecture-lead/SKILL.md
Scope interpretation, requirements, copy	Product Lead	.claude/skills/leads/product-lead/SKILL.md
Implementation, dependencies, tooling	Tech Lead	.claude/skills/leads/tech-lead/SKILL.md
Testing, coverage, quality gates	QA Lead	.claude/skills/leads/qa-lead/SKILL.md

Consultation Flow

async function handleDecision(question: Question) {
  // 1. Check Authority Matrix
  const authority = lookupAuthority(question.category);

  // 2. USER_ONLY decisions go straight to user
  if (authority === 'USER_ONLY') {
    return escalateToUser(question);
  }

  // 3. LEAD_CONSULT decisions go to appropriate lead
  if (authority === 'LEAD_CONSULT') {
    const lead = getLeadForCategory(question.category);

    // Dispatch lead agent via Task tool
    const response = await Task({
      subagent_type: "general-purpose",
      description: `Consult ${lead} lead`,
      prompt: `You are the ${lead}-lead agent.

        Question: ${question.text}
        Context: ${question.context}

        Follow the ${lead}-lead skill instructions.

        Output your decision in JSON format:
        {
          "lead": "${lead}",
          "decision_made": true/false,
          "decision": "...",
          "reasoning": "...",
          "authority_used": "...",
          "escalate_to": null | "user" | "cto-advisor",
          "escalation_reason": "..."
        }`
    });

    const result = parseLeadResponse(response.output);

    // Log consultation to metadata
    await logConsultation(trackId, result);

    if (result.decision_made) {
      return result.decision;
    }

    // Lead escalated - follow their recommendation
    return escalateTo(result.escalate_to, result.escalation_reason);
  }

  // 4. ORCHESTRATOR decisions are made autonomously
  return makeAutonomousDecision(question);
}

Authority Matrix Reference

See conductor/authority-matrix.md for the complete decision matrix.

Quick Reference — Always Escalate to User:

• Budget changes >$50/month
• Add/remove features from spec
• Breaking API changes
• Dependencies >50KB
• Coverage below 70%
• Security/production data changes

Quick Reference — Lead Can Decide:

• Architecture: Patterns (existing), component org, schema (additive)
• Product: Spec interpretation, copy, task order
• Tech: Dependencies <50KB, implementation approach
• QA: Coverage 70-90%, test types, mocks

---

Agent Dispatch Protocol

Dispatch with Metadata Updates

Each agent dispatch includes instructions to update metadata.json:

// Example: Dispatching executor with resumption
Task({
  subagent_type: "general-purpose",
  description: "Execute track tasks",
  prompt: `You are the loop-executor agent for track ${trackId}.

    METADATA STATE:
    - Current step: EXECUTE
    - Tasks completed: ${metadata.loop_state.checkpoints.EXECUTE.tasks_completed}
    - Last task: ${metadata.loop_state.checkpoints.EXECUTE.last_task}
    - Resume from: Next [ ] task after "${lastTask}"

    Your task:
    1. Read conductor/tracks/${trackId}/plan.md
    2. Skip all [x] tasks - they are already done
    3. Find first [ ] task after "${lastTask}"
    4. Implement following loop-executor skill
    5. After EACH task completion:
       - Mark [x] in plan.md with commit SHA
       - Update metadata.json checkpoints.EXECUTE:
         - tasks_completed++
         - last_task = "Task X.Y"
         - last_commit = "sha"
    6. Continue until all tasks complete

    MANDATORY: Update metadata.json after every task for resumption support.`
})

Agent Roster (v3)

Step	Agent	Skill	Dispatch Prompt Key Points
PRE-PLAN	Knowledge Manager	knowledge-manager	Load patterns + errors for this track type
PLAN	Planner	loop-planner	Create plan.md WITH DAG, update metadata
EVALUATE_PLAN	Plan Evaluator	loop-plan-evaluator	Run 6 checks (+ DAG + Board), write verdict
EVALUATE_PLAN	Board	board-of-directors	NEW: Full deliberation for major tracks
PARALLEL_EXECUTE	Workers	worker-templates/*	NEW: Parallel Task calls via agent-factory
EVALUATE_EXECUTION	Exec Evaluator	loop-execution-evaluator	Dispatch evaluators + quick board review
FIX	Fixer	loop-fixer	Check fix_cycle_count, implement fixes
BUSINESS_SYNC	Biz Doc Sync	business-docs-sync	Update Tier 1-3 docs if needed
POST-COMPLETE	Retrospective	retrospective-agent	Extract learnings, cleanup workers

---

Parallel Execution Engine (v3)

When to Use Parallel Execution

Parallel execution is used when:

• Plan contains dag: block with parallel_groups
• DAG validation passed in EVALUATE_PLAN
• Track has 3+ tasks that can run concurrently

PARALLEL_EXECUTE Step

async function stepParallelExecute(trackId: string, metadata: dict) {
  // 1. Initialize message bus
  const busPath = await initMessageBus(`conductor/tracks/${trackId}`);

  // 2. Parse DAG from plan.md
  const dag = await parseDagFromPlan(trackId);

  // 3. Import parallel dispatch utilities
  const { execute_parallel_phase } = require('parallel-dispatch');

  // 4. Execute all parallel groups
  const result = await execute_parallel_phase(dag, trackId, busPath, metadata);

  // 5. Update metadata with results
  metadata.loop_state.parallel_state = {
    total_workers_spawned: result.workers_spawned,
    completed_workers: result.all_tasks_completed.length,
    failed_workers: Object.keys(result.failed_tasks).length,
    parallel_groups_completed: result.parallel_groups_executed
  };

  // 6. Determine next step
  if (result.success) {
    return { next_step: 'EVALUATE_EXECUTION', status: 'PASSED' };
  } else if (result.escalate) {
    return { next_step: 'ESCALATE', reason: result.escalate_reason };
  } else {
    return { next_step: 'FIX', failures: result.failed_tasks };
  }
}

Worker Dispatch via Task Tool

Workers are dispatched using parallel Task calls:

// Dispatch 3 workers in parallel (single message, multiple tool calls)
await Promise.all([
  Task({
    subagent_type: "general-purpose",
    description: "Execute Task 1.1: Create store",
    prompt: workerPrompts["1.1"],
    run_in_background: true
  }),
  Task({
    subagent_type: "general-purpose",
    description: "Execute Task 1.2: Build resolver",
    prompt: workerPrompts["1.2"],
    run_in_background: true
  }),
  Task({
    subagent_type: "general-purpose",
    description: "Execute Task 1.3: Add validation",
    prompt: workerPrompts["1.3"],
    run_in_background: true
  })
]);

Worker Monitoring

Monitor workers via message bus polling:

async function monitorWorkers(busPath: string, taskIds: string[]) {
  const pending = new Set(taskIds);
  const completed = new Set();
  const failed = {};

  while (pending.size > 0) {
    // Check for completions
    for (const taskId of pending) {
      const eventFile = `${busPath}/events/TASK_COMPLETE_${taskId}.event`;
      if (await exists(eventFile)) {
        pending.delete(taskId);
        completed.add(taskId);
      }

      const failFile = `${busPath}/events/TASK_FAILED_${taskId}.event`;
      if (await exists(failFile)) {
        pending.delete(taskId);
        failed[taskId] = await getFailureReason(busPath, taskId);
      }
    }

    // Check for stale workers
    const stale = await checkStaleWorkers(busPath, thresholdMinutes=10);
    for (const worker of stale) {
      if (pending.has(worker.task_id)) {
        failed[worker.task_id] = `Stale: no heartbeat for ${worker.minutes_stale}m`;
        pending.delete(worker.task_id);
      }
    }

    await sleep(5000);
  }

  return { completed: [...completed], failed };
}

---

Board of Directors Integration (v3)

When to Invoke the Board

Checkpoint	Condition	Board Type
EVALUATE_PLAN	Major track (arch/integ/infra, 5+ tasks, P0)	Full meeting
EVALUATE_EXECUTION	Always	Quick review
PRE_LAUNCH	Production deploy	Security + Ops deep dive
CONFLICT	Evaluators disagree	Tie-breaker

Invoking Board at EVALUATE_PLAN

async function evaluatePlanWithBoard(trackId: string, metadata: dict) {
  // 1. Run standard plan evaluation
  const evalResult = await dispatchPlanEvaluator(trackId);

  // 2. Check if board is needed
  const needsBoard = isMajorTrack(metadata) || evalResult.recommends_board;

  if (needsBoard) {
    // 3. Invoke full board meeting
    const boardResult = await invokeBoardMeeting(
      busPath: `conductor/tracks/${trackId}/.message-bus`,
      checkpoint: "EVALUATE_PLAN",
      proposal: await readFile(`conductor/tracks/${trackId}/plan.md`),
      context: { spec: metadata.spec_summary, dag: evalResult.dag }
    );

    // 4. Store board session
    metadata.loop_state.board_sessions.push({
      session_id: boardResult.session_id,
      checkpoint: "EVALUATE_PLAN",
      verdict: boardResult.verdict,
      vote_summary: boardResult.votes,
      conditions: boardResult.conditions,
      timestamp: new Date().toISOString()
    });

    // 5. Handle board verdict
    if (boardResult.verdict === "REJECTED") {
      return {
        next_step: "PLAN",
        status: "FAILED",
        reason: "Board rejected plan",
        conditions: boardResult.conditions
      };
    }

    // Carry forward conditions for EVALUATE_EXECUTION
    metadata.board_conditions = boardResult.conditions;
  }

  return { next_step: "PARALLEL_EXECUTE", status: "PASSED" };
}

Board Quick Review at EVALUATE_EXECUTION

async function evaluateExecutionWithBoard(trackId: string, metadata: dict) {
  // 1. Run specialized evaluators
  const evalResults = await dispatchSpecializedEvaluators(trackId);

  // 2. Quick board review (no discussion phase)
  const boardReview = await invokeBoardReview(
    busPath: `conductor/tracks/${trackId}/.message-bus`,
    proposal: summarizeExecutionResults(evalResults)
  );

  // 3. Verify board conditions from EVALUATE_PLAN were met
  const conditionsMet = await verifyBoardConditions(
    metadata.board_conditions,
    evalResults
  );

  if (!conditionsMet.all_met) {
    return {
      next_step: "FIX",
      status: "FAILED",
      reason: `Board conditions not met: ${conditionsMet.unmet.join(", ")}`
    };
  }

  return evalResults.all_passed
    ? { next_step: "BUSINESS_SYNC", status: "PASSED" }
    : { next_step: "FIX", status: "FAILED" };
}

---

V3 State Machine Diagram

                              TRACK START
                                   │
                                   ▼
                    ┌──────────────────────────┐
                    │    KNOWLEDGE MANAGER     │
                    │    (Load patterns)       │
                    └────────────┬─────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              PLAN (with DAG)                                 │
│  loop-planner generates plan.md with explicit dependency graph              │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    EVALUATE_PLAN + BOARD MEETING                             │
│                                                                              │
│  1. DAG Validation (cycles, conflicts)                                       │
│  2. Standard checks (scope, overlap, deps, quality)                          │
│  3. For MAJOR tracks → invoke /board-meeting                                │
│     ┌──────────────────────────────────────────────────────────────────┐    │
│     │  BOARD DELIBERATION                                               │    │
│     │  Phase 1: All 5 directors ASSESS in parallel                      │    │
│     │  Phase 2: Directors DISCUSS via message bus                       │    │
│     │  Phase 3: Directors VOTE                                          │    │
│     │  Phase 4: RESOLVE → APPROVED / REJECTED / CONDITIONS              │    │
│     └──────────────────────────────────────────────────────────────────┘    │
│                                                                              │
│  PASS → Continue   |   FAIL → Back to PLAN with conditions                  │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         PARALLEL_EXECUTE                                     │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                        MESSAGE BUS                                   │    │
│  │  queue.jsonl | locks.json | worker-status.json | events/            │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
│  For each parallel_group in DAG:                                            │
│    1. agent-factory creates specialized workers                             │
│    2. Dispatch via parallel Task(run_in_background=true)                   │
│    3. Workers coordinate via message bus:                                    │
│       - FILE_LOCK / FILE_UNLOCK for shared files                           │
│       - PROGRESS updates every 5 min                                        │
│       - TASK_COMPLETE / TASK_FAILED when done                              │
│    4. Monitor for completion, handle failures                               │
│    5. Cleanup ephemeral workers                                              │
│                                                                              │
│  ┌──────┐ ┌──────┐ ┌──────┐                                                 │
│  │Worker│ │Worker│ │Worker│  (max 5 concurrent)                            │
│  │ 1.1  │ │ 1.2  │ │ 1.3  │                                                 │
│  └──┬───┘ └──┬───┘ └──┬───┘                                                 │
│     └────────┴────────┘                                                      │
│              │                                                               │
│  PASS → Continue   |   PARTIAL_FAIL → Isolate + Continue                    │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                 EVALUATE_EXECUTION + BOARD REVIEW                            │
│                                                                              │
│  1. Specialized evaluators (UI, Code, Integration, Business)                │
│  2. Quick board review (no discussion)                                       │
│  3. Verify board conditions from EVALUATE_PLAN                              │
│                                                                              │
│  PASS → BUSINESS_SYNC? → COMPLETE                                           │
│  FAIL → FIX (with specific failures)                                        │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                              ┌────┴────┐
                              │         │
                         PASS ▼    FAIL ▼
                    ┌──────────┐  ┌──────────┐
                    │BUSINESS  │  │   FIX    │
                    │  SYNC    │  │ (max 3x) │
                    └────┬─────┘  └────┬─────┘
                         │             │
                         ▼             │
                    ┌──────────┐       │
                    │ COMPLETE │◄──────┘
                    │          │   (after fix passes)
                    └────┬─────┘
                         │
                         ▼
                    ┌──────────────────────────┐
                    │   RETROSPECTIVE AGENT    │
                    │   + Cleanup workers      │
                    └──────────────────────────┘

---

Resumption Protocol

When orchestrator starts, it resumes from exact state:

async function resumeOrchestration(trackId: string) {
  const { current_step, step_status, metadata } = await detectCurrentStep(trackId);

  switch (step_status) {
    case 'NOT_STARTED':
      // Start the step fresh
      return dispatchAgent(current_step, metadata);

    case 'IN_PROGRESS':
      // Resume the step with checkpoint data
      const checkpoint = metadata.loop_state.checkpoints[current_step];
      return resumeAgent(current_step, checkpoint);

    case 'PASSED':
      // Move to next step
      const nextStep = getNextStep(current_step, 'PASS');
      await updateMetadata(trackId, { current_step: nextStep, step_status: 'NOT_STARTED' });
      return dispatchAgent(nextStep, metadata);

    case 'FAILED':
      // Handle based on which step failed
      if (current_step === 'EVALUATE_PLAN') {
        await updateMetadata(trackId, { current_step: 'PLAN', step_status: 'NOT_STARTED' });
        return dispatchAgent('PLAN', metadata);
      }
      if (current_step === 'EVALUATE_EXECUTION') {
        // Check fix cycle limit
        if (metadata.loop_state.fix_cycle_count >= 3) {
          return escalateToUser('Fix cycle limit exceeded after 3 attempts');
        }
        await updateMetadata(trackId, {
          current_step: 'FIX',
          step_status: 'NOT_STARTED',
          fix_cycle_count: metadata.loop_state.fix_cycle_count + 1
        });
        return dispatchAgent('FIX', metadata);
      }

    case 'BLOCKED':
      // Check if blocker is resolved
      const activeBlockers = metadata.blockers.filter(b => b.status === 'ACTIVE');
      if (activeBlockers.length > 0) {
        return escalateToUser(`Track blocked: ${activeBlockers[0].description}`);
      }
      // Blocker resolved, continue
      await updateMetadata(trackId, { step_status: 'NOT_STARTED' });
      return dispatchAgent(current_step, metadata);
  }
}

Resumption by Step

Step	Resumption Data	Action
PLAN	checkpoints.PLAN.plan_version	Re-run planner if revising
EXECUTE	checkpoints.EXECUTE.last_task	Skip completed tasks, continue from next
FIX	checkpoints.FIX.fixes_remaining	Continue with remaining fixes

---

The Full Loop (Automated)

┌─────────────────────────────────────────────────────────────────┐
│                        ORCHESTRATOR                             │
│                                                                 │
│  1. Read metadata.json → detect current_step + step_status      │
│  2. Dispatch appropriate agent via Task tool                    │
│  3. Agent updates metadata.json checkpoints                     │
│  4. Agent returns → orchestrator reads new state                │
│  5. Continue to next step or handle failure                     │
│  6. Loop until COMPLETE or escalation needed                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

PLAN ──► EVALUATE_PLAN ──► EXECUTE ──► EVALUATE_EXECUTION
  ▲            │                              │
  │        FAIL → back                   PASS → BUSINESS_SYNC? → COMPLETE
  │                                      FAIL → FIX
  │                                             │
  └─────────────────────────────────────────────┘
                    (after fix, re-evaluate)

---

Escalation Triggers

Escalate to user (stop the loop) when:

1. Fix cycle limit — 3 failed EVALUATE → FIX cycles
2. USER_ONLY decision — From authority matrix
3. Lead escalated — Lead returned escalate_to: "user"
4. Blocker detected — External dependency blocking progress
5. Max iterations — Safety limit of 50 loop iterations reached

Escalation Format

## Orchestrator Paused — User Input Required

**Track**: [track-id]
**Current Step**: [step]
**Reason**: [escalation reason]

**Context**:
[What was happening when escalation triggered]

**Options**:
1. [Option 1]
2. [Option 2]
3. [Option 3 if applicable]

What would you like to do?

---

Track Completion Protocol

When current_step reaches COMPLETE:

1. Update metadata.json

{
  "status": "complete",
  "completed_at": "[timestamp]",
  "loop_state": {
    "current_step": "COMPLETE",
    "step_status": "PASSED"
  }
}

2. Update tracks.md — Move track to "Done" table with date

3. Update conductor/index.md — Update current status

4. Commit — docs: complete [track-id] - evaluation passed

5. Report to user

## Track Complete

**Track**: [track-id]
**Phases**: [count] completed
**Tasks**: [count] completed
**Evaluation**: PASS — all checks passed
**Lead Consultations**: [count] decisions made autonomously
**Commits**: [list of key commits]

**Next track**: [suggest from tracks.md]

---

CTO Advisor Integration

For technical tracks, automatically include CTO review during EVALUATE_PLAN:

// Detect if track is technical
const technicalKeywords = [
  'architecture', 'system design', 'integration', 'API', 'database',
  'schema', 'migration', 'infrastructure', 'scalability', 'performance',
  'security', 'authentication', 'authorization', 'deployment'
];

const isTechnical = technicalKeywords.some(keyword =>
  spec.toLowerCase().includes(keyword) || plan.toLowerCase().includes(keyword)
);

if (isTechnical) {
  // Include CTO review in plan evaluation
  dispatchPrompt += `
    This is a TECHNICAL track. Your evaluation must include:
    1. Standard plan checks (scope, overlap, dependencies, clarity)
    2. CTO technical review using cto-plan-reviewer skill

    Both must PASS for plan evaluation to pass.`;
}

---

Learning Layer Integration

The orchestrator integrates the Knowledge Layer for continuous learning:

Pre-Planning: Knowledge Manager

BEFORE dispatching the planner, run Knowledge Manager to load relevant patterns:

async function dispatchPlannerWithKnowledge(trackId: string) {
  // 1. Run Knowledge Manager first
  const knowledgeBrief = await Task({
    subagent_type: "general-purpose",
    description: "Load knowledge for track",
    prompt: `You are the knowledge-manager agent.

      Track: ${trackId}
      Spec: ${await readFile(`conductor/tracks/${trackId}/spec.md`)}

      1. Extract keywords from the spec
      2. Search conductor/knowledge/patterns.md for matching patterns
      3. Search conductor/knowledge/errors.json for relevant errors
      4. Return a knowledge brief with:
         - Relevant patterns to apply
         - Known errors to avoid
         - Similar previous tracks (if any)

      Follow .claude/skills/knowledge/knowledge-manager/SKILL.md`
  });

  // 2. Dispatch planner WITH knowledge brief injected
  await Task({
    subagent_type: "general-purpose",
    description: "Create track plan",
    prompt: `You are the loop-planner agent for track ${trackId}.

      ## KNOWLEDGE BRIEF (from previous tracks)
      ${knowledgeBrief.output}

      ## YOUR TASK
      Create plan.md using the patterns above where applicable.
      Avoid the known errors listed.

      Follow .claude/skills/loop-planner/SKILL.md`
  });
}

Post-Completion: Retrospective Agent

AFTER a track reaches COMPLETE, run Retrospective Agent to extract learnings:

async function runPostCompletionRetrospective(trackId: string) {
  await Task({
    subagent_type: "general-purpose",
    description: "Run track retrospective",
    prompt: `You are the retrospective-agent.

      Track: ${trackId}

      1. Read conductor/tracks/${trackId}/plan.md (all tasks and fix cycles)
      2. Read conductor/tracks/${trackId}/metadata.json (fix counts, consultations)
      3. Analyze: What worked? What failed? What patterns emerged?
      4. Update conductor/knowledge/patterns.md with new reusable solutions
      5. Update conductor/knowledge/errors.json with new error patterns
      6. Write retrospective to conductor/tracks/${trackId}/retrospective.md
      7. Propose skill improvements if workflow issues found

      Follow .claude/skills/knowledge/retrospective-agent/SKILL.md`
  });
}

Updated State Machine with Learning

                              TRACK START
                                   │
                                   ▼
                    ┌──────────────────────────┐
                    │    KNOWLEDGE MANAGER     │  ◄── NEW: Load patterns & errors
                    │    (Pre-planning intel)  │
                    └────────────┬─────────────┘
                                 │
                                 ▼
PLAN ──► EVALUATE_PLAN ──► EXECUTE ──► EVALUATE_EXECUTION
  ▲            │                              │
  │        FAIL → back                   PASS → BUSINESS_SYNC? → COMPLETE
  │                                      FAIL → FIX                  │
  │                                             │                    │
  └─────────────────────────────────────────────┘                    │
                                                                     ▼
                                                    ┌──────────────────────────┐
                                                    │   RETROSPECTIVE AGENT    │  ◄── NEW
                                                    │   (Extract learnings)    │
                                                    └────────────┬─────────────┘
                                                                 │
                                                                 ▼
                                                    ┌──────────────────────────┐
                                                    │    KNOWLEDGE BASE        │
                                                    │  patterns.md + errors.json│
                                                    └──────────────────────────┘
                                                                 │
                                                                 ▼
                                                          NEXT TRACK
                                                    (now smarter than before)

Knowledge Layer Files

File	Purpose	Updated By
conductor/knowledge/patterns.md	Reusable solutions	Retrospective Agent
conductor/knowledge/errors.json	Error → Fix registry	Retrospective Agent, Fixer
conductor/tracks/[id]/retrospective.md	Track-specific learnings	Retrospective Agent

Fixer Integration with Error Registry

The loop-fixer also uses the error registry:

// In loop-fixer, before attempting a fix
async function findKnownSolution(errorMessage: string) {
  const errors = JSON.parse(await readFile('conductor/knowledge/errors.json'));

  for (const error of errors.errors) {
    if (new RegExp(error.pattern, 'i').test(errorMessage)) {
      return {
        found: true,
        solution: error.solution,
        code_fix: error.code_fix
      };
    }
  }

  return { found: false };
}

// After fixing a new error, log it
async function logNewError(pattern, solution, trackId) {
  const errors = JSON.parse(await readFile('conductor/knowledge/errors.json'));
  errors.errors.push({
    id: `err-${String(errors.errors.length + 1).padStart(3, '0')}`,
    pattern,
    solution,
    discovered_in: trackId,
    last_seen: new Date().toISOString().split('T')[0]
  });
  await writeFile('conductor/knowledge/errors.json', JSON.stringify(errors, null, 2));
}

---

Quick Reference

Starting a Track

User: /conductor implement

Orchestrator:
1. Read conductor/tracks.md → get active track
2. Read conductor/tracks/[track]/metadata.json → get loop_state
3. Determine current step and status
4. Dispatch appropriate agent
5. Loop until complete

State Locations

Data	Location	Purpose
Loop state	metadata.json → loop_state	Primary state machine
Task progress	plan.md markers	Human-readable progress
Lead decisions	metadata.json → lead_consultations	Decision audit trail
Blockers	metadata.json → blockers	Escalation tracking
Authority rules	conductor/authority-matrix.md	Decision boundaries

Files Modified by Orchestrator

• conductor/tracks/[track]/metadata.json — State updates
• conductor/tracks.md — Completion tracking
• conductor/index.md — Current status