Orchestrator - Multi-Agent Ralph v2.52

Smart Memory-Driven Orchestration with 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"

Core Workflow (v2.52.0 - 8 Major Steps, 23 Sub-steps)

Step 0: EVALUATE (3-Dimension Classification)

0a. Classification (v2.46 RLM): | Dimension | Values | Purpose | |-----------|--------|---------| | Complexity | 1-10 | Scope, risk, ambiguity | | Information Density | CONSTANT / LINEAR / QUADRATIC | How answer scales | | Context Requirement | FITS / CHUNKED / RECURSIVE | Decomposition needs |

0b. SMART MEMORY SEARCH (v2.47 NEW):

┌────────────────────────────────────────────────────────────────┐
│              SMART MEMORY SEARCH (PARALLEL)                    │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│   │claude-mem│ │ memvid   │ │ handoffs │ │ ledgers  │        │
│   └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘        │
│        │ PARALLEL   │ PARALLEL   │ PARALLEL   │ PARALLEL      │
│        └────────────┴────────────┴────────────┘               │
│                         ↓                                      │
│              .claude/memory-context.json                       │
│              ├── past_successes                                │
│              ├── past_errors                                   │
│              ├── recommended_patterns                          │
│              └── fork_suggestions (top 5)                      │
└────────────────────────────────────────────────────────────────┘

AUTOMATIC: Triggered by PreToolUse hook on Task invocation.

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 0c: FAST_PATH Decision

If FAST_PATH eligible (complexity <= 3, CONSTANT, FITS):

DIRECT_EXECUTE -> MICRO_VALIDATE -> DONE (3 steps)

Otherwise, continue to Step 1.

Step 1: CLARIFY (Memory-Enhanced)

AUTOMATIC TLDR + MEMORY CONTEXT:

# 1. Check memory context for similar past implementations
cat .claude/memory-context.json | jq '.fork_suggestions[:3]'

# 2. Semantic search for existing code
tldr semantic "$USER_TASK_KEYWORDS" .

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 1b: GAP-ANALYST (Memory-Enhanced)

Pre-implementation gap analysis using memory context:

Check past_errors to avoid known pitfalls
Review recommended_patterns for best practices
Identify requirements not covered by memory

Step 1c: PARALLEL_EXPLORE (5 Concurrent + Memory)

Launch 5 parallel exploration tasks:

Semantic Search - Code patterns
Structure Analysis - Codebase overview
Dependency Scan - Understanding deps
Pattern Search - Similar implementations
Memory Correlation - Match with past sessions

Results aggregated to .claude/exploration-context.json

Step 2: CLASSIFY (3-Dimension)

| Score | Complexity | Model | Adversarial | |-------|------------|-------|-------------| | 1-2 | Trivial | MiniMax-lightning | No | | 3-4 | Simple | MiniMax M2.1 | No | | 5-6 | Medium | Sonnet | Optional | | 7-8 | Complex | Opus | Yes | | 9-10 | Critical | Opus (thinking) | Yes |

Step 2b: WORKTREE DECISION

AskUserQuestion:
  questions:
    - question: "Requires isolated worktree?"
      header: "Isolation"
      options:
        - label: "Yes, create worktree"
        - label: "No, current branch"

Step 3: PLAN (Memory-Informed)

Use memory context in planning:

# Review what worked before
cat .claude/memory-context.json | jq '.insights.past_successes'

# Review what to avoid
cat .claude/memory-context.json | jq '.insights.past_errors'

Write plan with:

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

Step 3b: PERSIST

Write to .claude/orchestrator-analysis.md

Step 3c: PLAN-STATE

Initialize .claude/plan-state.json with spec vs actual tracking.

Step 3d: RECURSIVE_DECOMPOSE (if needed)

For QUADRATIC or RECURSIVE tasks, spawn sub-orchestrators (max depth 3).

Step 4: PLAN MODE

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

Exit with ExitPlanMode when approved.

Step 5: DELEGATE (Parallel-First)

PRIORITY: Parallel execution when possible

# PARALLEL: Independent tasks
Task:
  subagent_type: "security-auditor"
  model: "opus"
  run_in_background: true
  prompt: "Audit: $FILES"

Task:
  subagent_type: "test-architect"
  model: "sonnet"
  run_in_background: true
  prompt: "Generate tests: $FILES"

# SEQUENTIAL: Dependent tasks
# Wait for results before continuing

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 6b.5: QUALITY-PARALLEL (NEW v2.80)

Trigger: complexity >= 5 OR security-related code

Launch parallel quality checks:

# Launch 4 quality subagents in parallel
QUALITY_RESULT=$(./.claude/scripts/quality-coordinator.sh "$TARGET_FILE" "$COMPLEXITY")

# Parse result and extract run_id
RUN_ID=$(echo "$QUALITY_RESULT" | jq -r '.run_id')

# Store run_id for step 7
echo "$RUN_ID" > .claude/quality-results/current_run_id.txt

Quality Agents Launched (parallel, non-blocking):

Security (27 patterns, P0/P1/P2)
Code Review (4 agents, confidence ≥80)
Deslop (AI code cleanup)
Stop-Slop (AI prose cleanup)

Store RUN_ID for retrieval in step 7a.

Step 7: VALIDATE (Quality-First v2.46)

Step 7a: READ QUALITY RESULTS (NEW v2.80)

Check if quality checks completed:

# Read current run_id
if [[ -f .claude/quality-results/current_run_id.txt ]]; then
    CURRENT_RUN_ID=$(cat .claude/quality-results/current_run_id.txt)

    # Read aggregated results
    QUALITY_RESULTS=$(./.claude/scripts/read-quality-results.sh "$CURRENT_RUN_ID")

    # Parse results
    CRITICAL_COUNT=$(echo "$QUALITY_RESULTS" | jq -r '.summary.critical_findings // 0')
    TOTAL_FINDINGS=$(echo "$QUALITY_RESULTS" | jq -r '.summary.total_findings // 0')

    echo "Quality Results: $TOTAL_FINDINGS findings ($CRITICAL_COUNT critical)"
fi

Decision Logic:

CRITICAL_COUNT > 0: BLOCK and require fixes
TOTAL_FINDINGS == 0: Proceed to validation
TOTAL_FINDINGS > 0 but CRITICAL_COUNT == 0: Proceed with warnings

Step 7: VALIDATE (Quality-First v2.46)

Stage 1: CORRECTNESS (BLOCKING)

Meets requirements?
Edge cases handled?

Stage 2: QUALITY (BLOCKING)

Security verified?
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

NEW v2.47: Save learnings to memory for future sessions:

# Save successful patterns
ralph memvid save "Implemented OAuth2 successfully: [pattern details]"

# Record errors to avoid
ralph memvid save "AVOID: [error pattern] caused [issue]"

-> VERIFIED_DONE

Model Routing (v2.47)

| Route | Primary | Secondary | Max Iter | |-------|---------|-----------|----------| | FAST_PATH | sonnet | - | 3 | | STANDARD (1-4) | minimax-m2.1 | 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 |

Integration Points

| Component | Role | When | |-----------|------|------| | smart-memory-search.sh | PARALLEL memory search | Step 0b (NEW) | | /smart-fork | Find relevant sessions | Manual invocation | | /fast-path-check | Trivial task detection | Step 0c | | /parallel-explore | 5 concurrent exploration | Step 1c | | /classify | 3-dimension classification | Step 2 | | /gates | Quality validation | Step 7 | | /adversarial | Spec refinement | Step 7 | | /retrospective | Post-analysis | Step 8 |

Memory Sources (Searched in Parallel)

| Source | Content | Speed | |--------|---------|-------| | claude-mem MCP | Semantic observations | Fast | | memvid | Vector-encoded context | Sub-5ms | | handoffs | Session snapshots | Fast | | ledgers | Continuity data | Fast |

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:

Smart Memory Search complete (memory-context.json exists)
Task classified (3 dimensions)
MUST_HAVE questions answered
Plan approved
Implementation complete
CORRECTNESS passed (blocking)
QUALITY passed (blocking)
Adversarial passed (if complexity >= 7)
Retrospective done + learnings saved to memory

Examples

Standard Task with Memory

User: "Add JWT authentication"

Step 0a: Classify -> Complexity: 7, LINEAR, FITS
Step 0b: Smart Memory Search
  -> Found: 3 past sessions with auth implementations
  -> past_successes: "Use passport.js for OAuth"
  -> past_errors: "Don't store tokens in localStorage"
  -> fork_suggestion: session-abc123

Step 1: Clarify (informed by memory)
  -> Skip questions about token storage (already known)
  -> Focus on new requirements

... (continue with memory-informed implementation)

Step 8: Retrospective
  -> Save: "JWT with refresh tokens implemented successfully"
  -> Save: "AVOID: Token expiry not handled - fix applied"

CLI Commands (v2.47)

# Smart memory search
ralph memory-search "OAuth implementation"
ralph fork-suggest "Add authentication"
ralph memory-stats

# Standard orchestration
ralph orch "task description"
ralph gates
ralph adversarial "spec"