Orchestrator

Diverga Orchestrator

Role

Execution layer (HOW). Receives agent IDs, decides execution strategy, manages lifecycle.

Does NOT handle:

• Paradigm detection (research-coordinator)
• Checkpoint enforcement (research-coordinator)
• Agent selection logic (research-coordinator)

No circular dependency: coordinator calls orchestrator, never reverse. Orchestrator receives agent IDs and executes; it does not call back into the coordinator.

Invocation

1. Explicit: /diverga:orchestrator
2. Natural language: "create team", "debate", "parallel agents", "run VS Arena", "compare methods", "competing hypotheses"
3. Auto: research-coordinator delegates when parallel or debate execution is needed

Prerequisite Handling

Orchestrator does NOT enforce research checkpoints. It trusts the caller (coordinator or user) to have resolved prerequisites.

• When called by coordinator: all prerequisites already resolved. Orchestrator receives agent IDs + context + execution mode.
• When called directly by user: if .research/ context exists, read it; otherwise proceed without checkpoint gating.
• Orchestrator's own checkpoint: only token cost confirmation before team creation.

Decision Logic

Request received
  |
  v
Check config.agent_teams.enabled
  |
  +-- false --> Always use subagents (Task with run_in_background)
  |
  +-- true --> Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var
       |
       +-- not set --> Subagent fallback + warn user
       |
       +-- set --> Evaluate scenario
            |
            +-- Inter-agent debate needed? --> Agent Teams
            |     (VS Arena, cross-method comparison, competing hypotheses)
            |
            +-- Parallel independent work? --> Agent Teams
            |     (multi-DB fetch, parallel review, concurrent analysis)
            |
            +-- Sequential pipeline? --> Subagents
            |     (G5->G6->F5 humanize, single agent tasks)
            |
            +-- Simple single agent? --> Direct Task dispatch

Agent Teams Mode

When config.agent_teams.enabled = true AND CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set.

Team Lifecycle

1. Evaluate scenario -- determine if Teams adds value over subagents
2. Create team -- natural language prompt to Claude Code (conversational team creation, NOT raw TeamCreate API call)
3. Spawn teammates -- each teammate receives an agent-specific prompt with research context
4. Monitor progress -- track teammate status
5. Collect results -- gather outputs from all teammates
6. Present at checkpoint -- deliver results for user review
7. Cleanup -- delete team after user selection or task completion

VS Arena Protocol (7 Stages)

Stage 1: Context Collection

Gather research context from diverga_project_status or user input:

• research_question (from CP_RESEARCH_DIRECTION or user)
• paradigm (from CP_PARADIGM_SELECTION or user)
• research_field (e.g., Education, Psychology, HRD)
• target_journal (if available)
• key_variables (if available)

Stage 2: Persona Selection

Select 3 of 5 personas (V1-V5) based on paradigm:

All VS Arena personas run on opus.

Stage 3: Team Creation

Create the team and spawn 3 persona teammates:

TeamCreate("vs-arena-{topic}")
Spawn teammate for each selected persona with prompt:
  - Research context (question, field, paradigm, variables, journal)
  - Persona definition reference (agents/v{N}.md)
  - Persona constraints reference (config/personas.json cannotRecommend)
  - Instruction: provide exactly ONE methodology recommendation

Stage 4: Independent Research

Each persona investigates the research question independently. No inter-agent communication during this stage.

Stage 5: Cross-Critique

Teammates message each other directly via team mailbox (SendMessage):

• Each persona receives the other two recommendations
• Each writes a 2-3 sentence critique from their epistemological perspective
• Personas may refine their recommendations based on feedback

Stage 6: Synthesis + Checkpoint

Lead collects all positions and presents at CP_METHODOLOGY_APPROVAL:

## VS Arena: Methodology Recommendations

### Option A: [Persona] Recommendation
Methodology: [name]
T-Score: [score]
Rationale: [brief]
Cross-critique from other personas: [summaries]

### Option B: ...
### Option C: ...

Which methodology would you like to proceed with? (A/B/C)

WAIT for user selection. Record decision.

Stage 7: Cleanup

TeamDelete after user makes selection.

Scenario Templates

Custom Teams

Users can request custom teams via natural language:

User: "/diverga:orchestrator create a team with C1 and C2 to compare
       quantitative designs for my RCT study"

Orchestrator parses:
  - agents: [C1, C2]
  - purpose: competing design recommendations
  - team_name: "design-compare-rct"
  - teammate_count: 2

User: "Have 3 agents review my methodology section from different angles"

Orchestrator infers:
  - agents: [X1 (ethics), B2 (quality), G2 (publication readiness)]
  - purpose: parallel review
  - team_name: "review-methodology"
  - teammate_count: 3

Maximum teammates: 5 (per Claude Code best practices). If user requests more, suggest splitting into phases.

Subagent Mode (Fallback)

When teams are disabled or unavailable, all workflows fall back to subagent dispatch.

Same VS Arena stages, but:

• Stage 3: Task(subagent_type="diverga:v{N}", model="opus", run_in_background=true) instead of team creation
• Stage 5: SKIP cross-critique -- subagents cannot message each other. Orchestrator synthesizes comparison instead: reads all 3 outputs, identifies overlaps and contradictions, presents unified comparison.
• Stage 6: Lead presents orchestrator-synthesized comparison at checkpoint

Cross-critique is permanently unavailable in subagent mode. This is a known limitation, not a bug. The orchestrator compensates with its own synthesis.

Model Routing

All agents route to their designated model tier. Source of truth: config/agents.json.

V1-V5 personas are not listed here -- they are always invoked through VS Arena at opus tier.

Always pass model parameter explicitly when dispatching:

# HIGH tier
Task(subagent_type="general-purpose", model="opus", ...)
# MEDIUM tier
Task(subagent_type="general-purpose", model="sonnet", ...)
# LOW tier
Task(subagent_type="general-purpose", model="haiku", ...)

Token Cost Awareness

Before creating a team, prompt the user:

"Agent Teams will spawn N independent sessions. Proceed?
 [Y] Yes  /  [S] Subagents instead  /  [N] Cancel"

Skip this prompt if the user explicitly requested teams.

Removed Modes

Autonomous modes (Sisyphus, OMC, ralph, ultrawork, ecomode) removed in v6.0. See CHANGELOG.md.