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.

Mode Configuration Protocol

FIRST ACTION: Read conductor/config.json to determine operating mode.

const config = await readJSON('conductor/config.json').catch(() => ({ mode: 'agentic' }));
const MODE = config.mode; // "agentic" | "human-in-the-loop"
const MAX_FIX_CYCLES = config.max_fix_cycles || 5;

All decision points below check MODE before acting. If config.json doesn't exist, default to "agentic".

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;
}

Goal Resolution (Mode-Dependent)

// If goal is ambiguous, check mode
if (analysis.ambiguous) {
  if (MODE === 'human-in-the-loop') {
    // HUMAN MODE: Ask user to pick interpretation
    return ask_user({
      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
      }]
    });
  }
  // AGENTIC MODE: Resolve autonomously — NEVER ask the user
  // Spawn a Plan subagent to pick the best interpretation
  const resolution = await Task({
    subagent_type: "Plan",
    description: "Resolve ambiguous goal",
    prompt: `The user's goal "${userGoal}" has multiple interpretations:
      ${analysis.interpretations.map(i => `- ${i.summary}: ${i.detail}`).join('\n')}

      Analyze the codebase context and pick the BEST interpretation.
      Consider: existing code patterns, project structure, recent git history.
      Return JSON: {"chosen": "<interpretation summary>", "reasoning": "<why>"}`
  });
  // Use the resolved interpretation and continue
  analysis = { ...analysis, ambiguous: false, resolvedGoal: resolution.chosen };
}

// If multiple tracks match, check mode
if (matchingTracks.length > 1) {
  if (MODE === 'human-in-the-loop') {
    // HUMAN MODE: Ask user which track
    return ask_user({
      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
      }]
    });
  }
  // AGENTIC MODE: Pick the most relevant one — NEVER ask the user
  // Pick the track with the highest keyword overlap and most recent activity
  const bestMatch = matchingTracks.sort((a, b) => {
    const aOverlap = keywords.filter(k => a.name.toLowerCase().includes(k)).length;
    const bOverlap = keywords.filter(k => b.name.toLowerCase().includes(k)).length;
    if (bOverlap !== aOverlap) return bOverlap - aOverlap;
    return new Date(b.updated_at) - new Date(a.updated_at); // Most recent
  })[0];
  console.log(`Auto-selected track: ${bestMatch.id} (best keyword match)`);
  return resumeOrchestration(bestMatch.id);
}

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