orchestrator

name	orchestrator
description	Full orchestration workflow with swarm mode: evaluate -> clarify -> classify -> persist -> plan mode -> spawn teammates -> execute -> validate -> retrospective. Use when: (1) implementing features, (2) complex refactoring, (3) multi-file changes, (4) tasks requiring coordination. Triggers: /orchestrator, /orch, 'orchestrate', 'full workflow', 'implement feature'.
argument-hint	<task description>
user-invocable	true
context	fork
agent	orchestrator
allowed-tools	["LSP","Task","AskUserQuestion","EnterPlanMode","ExitPlanMode","TodoWrite","Read","Edit","Write","Bash","Glob","Grep"]

Orchestrator - Multi-Agent Ralph v3.0

Smart Memory-Driven Orchestration with swarm mode, parallel memory search, RLM-inspired routing, and quality-first validation.

Based on @PerceptualPeak Smart Forking concept:

"Why not utilize the knowledge gained from your hundreds/thousands of other Claude code sessions? Don't let that valuable context go to waste!!"

Quick Start

# Via skill invocation
/orchestrator Implement OAuth2 authentication with Google

# Via CLI
ralph orch "Migrate database from MySQL to PostgreSQL"

# With specific teammates
/orchestrator "Refactor database layer" --teammates coder,reviewer

v2.88 Key Changes (MODEL-AGNOSTIC)

• Model-agnostic: Uses model configured in ~/.claude/settings.json or CLI/env vars
• No flags required: All teammates use the configured default model
• Flexible: Works with GLM-5, Claude, Minimax, or any configured model
• Settings-driven: Model selection via ANTHROPIC_DEFAULT_*_MODEL env vars

v2.87 Key Changes (UNIFIED SKILLS MODEL)

• Skills/Commands unification: All commands now use SKILL.md format
• Single source of truth: Skills live in repo, symlinked globally
• Version alignment: All skills updated to v2.87.0
• Documentation consolidated: Architecture docs in docs/architecture/

v2.81 Key Changes (SWARM MODE)

Swarm mode is now ENABLED by default using native Claude Code multi-agent features:

1. Team Creation: Orchestrator creates team "orchestration-team" with identity
2. Teammate Spawning: ExitPlanMode spawns 3 teammates (codex-reviewer, test-architect, security-auditor)
3. Shared Task List: All teammates see same tasks via TeammateTool
4. Inter-Agent Messaging: Teammates can communicate via mailbox
5. Plan Approval: Leader can approve/reject teammate plans

Core Workflow (10 Steps)

0. EVALUATE     -> Quick complexity assessment (trivial vs non-trivial)
1. CLARIFY      -> AskUserQuestion intensively (MUST_HAVE + NICE_TO_HAVE)
2. CLASSIFY     -> Complexity 1-10, model routing
2b. WORKTREE    -> Ask about worktree isolation
3. PLAN         -> Design detailed plan (orchestrator analysis)
3b. PERSIST     -> Write to .claude/orchestrator-analysis.md
4. PLAN MODE    -> EnterPlanMode (reads analysis as foundation)
5. DELEGATE     -> Route to appropriate model/agent
6. EXECUTE      -> Parallel subagents
7. VALIDATE     -> Quality gates + Adversarial
8. RETROSPECT   -> Analyze and improve

Step 0: EVALUATE (Aristotle + 3-Dimension Classification)

Phase A: Aristotle First Principles (integrated, not pre-step):

For complexity 1-3 (quick mode):

1. Assumption Autopsy — What are we assuming without questioning?
2. Aristotelian Move — What is the single highest-leverage action?

For complexity 4+ (full mode):

1. Assumption Autopsy — Identify all inherited assumptions
2. Irreducible Truths — List only what survives when assumptions are removed
3. Reconstruction from Zero — Generate 3 distinct approaches from truths only
4. Assumption vs Truth Map — Where does conventional thinking deceive?
5. Aristotelian Move — Identify the single action of maximum leverage

Reference: docs/reference/aristotle-first-principles.md

Phase B: Classification (RLM-inspired):

Dimension	Values	Purpose
Complexity	1-10	Scope, risk, ambiguity
Information Density	CONSTANT / LINEAR / QUADRATIC	How answer scales
Context Requirement	FITS / CHUNKED / RECURSIVE	Decomposition needs

Workflow Routing:

Density	Context	Complexity	Route
CONSTANT	FITS	1-3	FAST_PATH (3 steps)
CONSTANT	FITS	4-10	STANDARD
LINEAR	CHUNKED	ANY	PARALLEL_CHUNKS
QUADRATIC	ANY	ANY	RECURSIVE_DECOMPOSE

Step 1: CLARIFY (Memory-Enhanced)

MUST_HAVE Questions (Blocking):

AskUserQuestion:
  questions:
    - question: "What is the primary goal?"
      header: "Goal"
      options:
        - label: "New feature"
        - label: "Bug fix"
        - label: "Refactoring"
        - label: "Performance"

Step 2: CLASSIFY (Model Routing)

Score	Complexity	Model	Adversarial
1-2	Trivial	GLM-4.7 / glm-5	No
3-4	Simple	GLM-4.7 / glm-5	No
5-6	Medium	Sonnet	Optional
7-8	Complex	Opus	Yes
9-10	Critical	Opus (thinking)	Yes

Step 3: PLAN + PERSIST

Write plan to .claude/orchestrator-analysis.md with:

• Summary (informed by memory)
• Files to modify/create
• Dependencies
• Testing strategy
• Risks (include known issues from memory)

Step 4: PLAN MODE

EnterPlanMode: {}  # Claude Code reads orchestrator-analysis.md

Exit with ExitPlanMode when approved.

Step 5: DELEGATE (Parallel-First with Swarm)

REQUIRED: Parallel execution for ALL independent tasks. Sequential only with documented dependency.

See rule: .claude/rules/parallel-first.md

# With swarm mode (v2.81+)
Task:
  subagent_type: "orchestrator"
  description: "Full orchestration with swarm"
  prompt: "$ARGUMENTS"
  model: "sonnet"
  team_name: "orchestration-team"
  name: "orchestrator-lead"
  mode: "delegate"

# ExitPlanMode with swarm launch:
ExitPlanMode:
  launchSwarm: true
  teammateCount: 3

Step 6: EXECUTE-WITH-SYNC

Nested loop with parallel substeps:

EXTERNAL RALPH LOOP (max 25)
└── For EACH step:
    ├── LSA-VERIFY (architecture check)
    ├── IMPLEMENT (parallel if independent)
    ├── PLAN-SYNC (drift detection)
    └── MICRO-GATE (max 3 retries)

CRITICAL: model: "sonnet" for all subagents

Step 7: VALIDATE (Quality-First)

Stage 1: CORRECTNESS (BLOCKING)

• Meets requirements?
• Edge cases handled?

Stage 2: QUALITY (BLOCKING)

• Security verified? (semgrep + gitleaks)
• Performance OK?
• Tests adequate?

Stage 3: CONSISTENCY (ADVISORY - not blocking)

• Follows patterns?
• Style matches?

Stage 4: ADVERSARIAL (if complexity >= 7)

ralph adversarial "Design review"

Step 8: RETROSPECTIVE (Mandatory)

ralph retrospective

Save learnings to memory:

ralph memvid save "Implemented OAuth2 successfully: [pattern details]"
ralph memvid save "AVOID: [error pattern] caused [issue]"

-> VERIFIED_DONE

Model Routing

Route	Primary	Secondary	Max Iter
FAST_PATH	sonnet	-	3
STANDARD (1-4)	glm-5	sonnet	25
STANDARD (5-6)	sonnet	opus	25
STANDARD (7-10)	opus	sonnet	25
PARALLEL_CHUNKS	sonnet (chunks)	opus (aggregate)	15/chunk
RECURSIVE	opus (root)	sonnet (sub)	15/sub

GLM-5 Teams Integration (--with-glm5)

When $ARGUMENTS contains --with-glm5:

Step 1: Parse Arguments

TASK=<everything before --with-glm5>
USE_GLM5=true

Step 2: Spawn GLM-5 Teammates

# GLM-5 Coder
.claude/scripts/glm5-teammate.sh "glm5-coder" "$CODER_TASK" "$TASK_ID-coder"

# GLM-5 Reviewer
.claude/scripts/glm5-teammate.sh "glm5-reviewer" "$REVIEW_TASK" "$TASK_ID-reviewer"

# GLM-5 Tester
.claude/scripts/glm5-teammate.sh "glm5-tester" "$TEST_TASK" "$TASK_ID-tester"

Step 3: Wait for Completion

cat .ralph/teammates/$TASK_ID-*/status.json

Step 4: Aggregate Results

• Collect outputs from .ralph/reasoning/
• Show thinking process for transparency
• Apply quality gates

Available Teammates

Teammate	Role	Best For
coder	Implementation	Writing code, fixing bugs
reviewer	Code Review	Quality checks, security
tester	Test Generation	Unit tests, coverage
orchestrator	Coordination	Complex multi-step tasks

Anti-Patterns

• Never start without smart memory search
• Never skip clarification
• Never use model: "haiku" for subagents
• Never skip retrospective
• Never attempt more than 3 fixes (3-Fix Rule)
• Never block on consistency issues (quality over consistency)
• Never ignore memory context (learn from history)

Completion Criteria

VERIFIED_DONE requires ALL:

1. Smart Memory Search complete
2. Task classified (3 dimensions)
3. MUST_HAVE questions answered
4. Plan approved
5. Implementation complete
6. CORRECTNESS passed (blocking)
7. QUALITY passed (blocking)
8. Adversarial passed (if complexity >= 7)
9. Retrospective done + learnings saved to memory
10. Parallel-first validated: Agent Teams used for complexity >= 3, independent tasks parallelized
11. Teammates spawned: At least 2 ralph-* teammates for non-trivial tasks

CLI Commands

# Standard orchestration
ralph orch "task description"

# With GLM-5 teammates
ralph orch "task description" --with-glm5
ralph orch "complex feature" --with-glm5 --teammates coder,reviewer,tester

# Quality gates
ralph gates
ralph adversarial "spec"

# Memory
ralph memory-search "query"
ralph fork-suggest "Add authentication"

Related Skills

• /iterate - Iterative execution until VERIFIED_DONE
• /gates - Quality validation gates
• /adversarial - Spec refinement
• /parallel - Parallel subagent execution
• /retrospective - Post-task analysis
• /clarify - Requirement clarification

Agent Teams Integration (v2.88)

Optimal Scenario: Integrated (Agent Teams + Custom Subagents)

This skill uses the INTEGRATED approach combining Agent Teams coordination with Custom Subagent specialization.

Why Scenario C for This Skill

• Multi-phase orchestration requires tight coordination across evaluate, clarify, plan, execute, validate phases
• Quality gates (TeammateIdle, TaskCompleted) are essential for VERIFIED_DONE guarantee
• Specialized ralph- agents* for different task types (coder, reviewer, tester, researcher)
• Shared task list for progress tracking and dependency management
• 10-step workflow benefits from both team coordination and agent specialization

Configuration

1. TeamCreate: Create team "orchestration-team-{timestamp}" on skill invocation
2. TaskCreate: Create tasks for each orchestration phase (evaluate, clarify, plan, execute, validate)
3. Spawn: Use ralph-coder, ralph-reviewer, ralph-tester, ralph-researcher as needed
4. Hooks: TeammateIdle + TaskCompleted for VERIFIED_DONE guarantee
5. Coordination: Shared task list at ~/.claude/tasks/{team}/

Workflow Pattern

TeamCreate(team_name, description)
  → TaskCreate(evaluate, clarify, classify, persist)
  → TaskCreate(plan-mode tasks)
  → Task(subagent_type="ralph-*", team_name) for execute phase
  → TaskUpdate(status="completed") as phases finish
  → Hooks validate quality at each stage
  → VERIFIED_DONE after retrospective

Ralph Agent Types (v2.88)

Agent	Role	Tools	Model
ralph-coder	Code implementation	Read, Edit, Write, Bash	Inherited from settings.json
ralph-reviewer	Code review (security, quality)	Read, Grep, Glob	Inherited from settings.json
ralph-tester	Testing & QA	Read, Edit, Write, Bash(test)	Inherited from settings.json
ralph-researcher	Research & exploration	Read, Grep, Glob, WebSearch	Inherited from settings.json

Note: All agents inherit their model from ~/.claude/settings.json via ANTHROPIC_DEFAULT_*_MODEL environment variables (v2.88 model-agnostic architecture).

VERIFIED_DONE Pattern with Hooks

The orchestrator ensures VERIFIED_DONE through these critical hooks:

Hook	Event	Purpose	Exit 2 Behavior
teammate-idle-quality-gate.sh	TeammateIdle	Quality check before idle	Keep working + feedback
task-completed-quality-gate.sh	TaskCompleted	Quality before task completion	Prevent completion + feedback
ralph-subagent-stop.sh	SubagentStop	Quality gate for ralph-* agents	Block if incomplete

Exit 2 Behavior: When hooks return exit code 2, the agent continues working instead of completing/idling, ensuring continuous execution until VERIFIED_DONE.

Team Coordination Example

# 1. Create team (automatic on skill invocation)
TeamCreate:
  team_name: "orchestration-team-20250214"
  description: "Orchestrating feature implementation"

# 2. Create tasks for teammates
TaskCreate:
  subject: "Implement OAuth2 flow"
  description: "Add OAuth2 authentication with Google provider"
  metadata:
    assigned_to: "ralph-coder"
    priority: "high"

TaskCreate:
  subject: "Review OAuth2 implementation"
  description: "Security and quality review of OAuth2 code"
  metadata:
    assigned_to: "ralph-reviewer"
    depends_on: ["implement-oauth2-flow"]

TaskCreate:
  subject: "Test OAuth2 authentication"
  description: "Unit and integration tests for OAuth2"
  metadata:
    assigned_to: "ralph-tester"
    depends_on: ["implement-oauth2-flow"]

# 3. Spawn teammates for parallel execution
Task:
  subagent_type: "ralph-coder"
  team_name: "orchestration-team-20250214"

Task:
  subagent_type: "ralph-reviewer"
  team_name: "orchestration-team-20250214"

Task:
  subagent_type: "ralph-tester"
  team_name: "orchestration-team-20250214"

# 4. Monitor progress and aggregate results
TaskList:
  status: "in_progress"

# 5. Mark tasks complete
TaskUpdate:
  taskId: "1"
  status: "completed"

# 6. Delete team when VERIFIED_DONE
TeamDelete:
  team_name: "orchestration-team-20250214"

Quality Standards (All Ralph Agents)

1. CORRECTNESS: Syntax must be valid, logic must be sound
2. QUALITY: No console.log, no TODO/FIXME, proper types
3. SECURITY: No hardcoded secrets, proper input validation
4. CONSISTENCY: Follow project style guides

Communication Pattern

Teammates communicate via the shared task list and SendMessage tool:

SendMessage:
  type: "message"
  recipient: "ralph-reviewer"
  content: "OAuth2 implementation complete, ready for review"
  summary: "Implementation ready for review"

Action Reporting (v2.93.0)

El orchestrator genera reportes automáticos completos para garantiza trazabilidad:

Reporte Automático

Cuando /orchestrator completa, se genera automáticamente:

1. En la conversación de Claude: Reporte visible con todos los detalles
2. En el repositorio: docs/actions/orchestrator/{timestamp}.md
3. Metadatos JSON: .claude/metadata/actions/orchestrator/{timestamp}.json

Contenido del Reporte

Cada reporte incluye:

• ✅ Summary: Descripción de la tarea ejecutada
• ✅ Execution Details: Duración, iteraciones, archivos modificados
• ✅ Git State: Branch, commit, archivos cambiados
• ✅ Errors: Errores encontrados (si aplicable)
• ✅ Recommendations: Próximos pasos sugeridos

Generación Manual (Opcional)

Si necesitas control manual del reporte:

# Al inicio
source .claude/lib/action-report-lib.sh
start_action_report "orchestrator" "Implementing OAuth2 with Google"

# Durante ejecución
mark_iteration  # Cada iteración del loop
mark_file_modified "src/auth/oauth.ts"  # Cada archivo modificado
record_error "Type mismatch in config"  # Si hay errores

# Al completar
complete_action_report \
    "success" \
    "OAuth2 implementation completed" \
    "1. Run tests: npm test
     2. Security audit: /security src/
     3. Create PR: gh pr create"

Ver Reportes Anteriores

# Listar todos los reportes del orchestrator
ls -lt docs/actions/orchestrator/

# Ver el reporte más reciente
cat $(ls -t docs/actions/orchestrator/*.md | head -1)

# Buscar reportes fallidos
grep -l "Status: FAILED" docs/actions/orchestrator/*.md

Estadísticas

source .claude/lib/action-report-generator.sh
get_skill_stats "orchestrator"

# Output:
# Skill: orchestrator
# Total Reports: 45
# Completed: 42
# Failed: 3
# Success Rate: 93%

Integración con Hooks

El sistema de reportes del orchestrator se integra con:

Hook	Propósito	Ubicación
action-report-tracker.sh	Genera reportes automáticos	.claude/hooks/
orchestrator-report.sh	Reportes de sesión	~/.ralph/reports/
progress-tracker.sh	Tracking en tiempo real	.claude/progress.md

Nota: Los reportes de acción (docs/actions/) son COMPLEMENTARIOS a los reportes de sesión (~/.ralph/reports/).

Referencias del Sistema de Reportes

• Action Reports System - Documentación completa
• action-report-lib.sh - Librería helper
• action-report-generator.sh - Generador

References

• Unified Architecture v2.87
• Skills/Commands Unification
• Claude Code Skills Documentation
• Claude Code Agent Teams Documentation

Anti-Rationalization

See master table: docs/reference/anti-rationalization.md

Excuse	Rebuttal
"Step 0 is just classification, I can skip it"	Step 0 includes Aristotle analysis. Never skip.
"Memory search is slow, I'll skip it"	Memory prevents repeated mistakes. Worth the wait.
"Complexity is 2, no need for full workflow"	FAST_PATH still has 3 steps. Follow them.
"The plan is obvious, no need for EnterPlanMode"	Plans catch assumptions you didn't question.
"I already know the answer"	Memory is unreliable across sessions. Verify.
"I'll add documentation later"	Documentation is part of the deliverable.
"The user seems to want a quick fix"	Quick != sloppy. FAST_PATH exists for speed with quality.