Skills

orchestrator

Installation
SKILL.md

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

References

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.
Related skills

More from alfredolopez80/multi-agent-ralph-loop

Installs
1
Repository
alfredolopez80/…lph-loop
GitHub Stars
108
First Seen
5 days ago