brycewang-stanford/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:

| Rule | Always include 1 persona differing from CP_PARADIGM_SELECTION | |------|---------------------------------------------------------------|

| Paradigm | Selection | |----------|-----------| | Quantitative | V1 + V4 + one of V2/V3/V5 | | Qualitative | V4 + V1 + one of V2/V3/V5 | | Mixed | V3 + two of V1/V2/V4/V5 | | No paradigm set | V1 + V3 + V4 (maximum paradigmatic spread) |

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

| Scenario | Team Name | Teammates | When | |----------|-----------|-----------|------| | VS Arena | vs-arena-{topic} | 3 of V1-V5 | CP_METHODOLOGY_APPROVAL or explicit request | | Systematic Review | sr-pipeline-{topic} | I1 x3 (per DB) | I0 multi-DB fetch | | Cross-Method | method-compare-{topic} | C1+C2+C3 | Competing design recommendations | | Parallel Review | review-{topic} | 2-5 agents | Quality review from multiple angles | | Custom | {user-specified} | User-specified | Explicit orchestrator call |

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.

| Category | Agent | Display Name | Tier | Model | |----------|-------|-------------|------|-------| | A: Foundation | A1 | Research Question Refiner | HIGH | opus | | | A2 | Theory & Critique Architect | HIGH | opus | | | A5 | Paradigm Advisor | HIGH | opus | | B: Evidence | B1 | Literature Scout | MEDIUM | sonnet | | | B2 | Quality Appraiser | MEDIUM | sonnet | | C: Design | C1 | Quantitative Design & Sampling | HIGH | opus | | | C2 | Qualitative Design (Ethnography/AR) | HIGH | opus | | | C3 | Mixed Methods Design | HIGH | opus | | | C5 | Meta-Analysis Master | HIGH | opus | | D: Collection | D2 | Data Collection Specialist | MEDIUM | sonnet | | | D4 | Instrument Developer | HIGH | opus | | E: Analysis | E1 | Quantitative Analysis & Code Gen | HIGH | opus | | | E2 | Qualitative Coding | HIGH | opus | | | E3 | Mixed Methods Integration | HIGH | opus | | F: Quality | F5 | Humanization Verifier | MEDIUM | sonnet | | G: Publication | G1 | Journal Matcher | MEDIUM | sonnet | | | G2 | Publication Specialist | MEDIUM | sonnet | | | G5 | Academic Style Auditor | MEDIUM | sonnet | | | G6 | Academic Style Humanizer | HIGH | opus | | I: Systematic Review | I0 | SR Pipeline Orchestrator | HIGH | opus | | | I1 | Paper Retrieval | MEDIUM | sonnet | | | I2 | Screening Assistant | MEDIUM | sonnet | | | I3 | RAG Builder | LOW | haiku | | X: Cross-Cutting | X1 | Research Guardian | HIGH | opus |

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.