ralph-claude-orchestrator

Loop Orchestrator — Multi-Agent Patterns (Claude Code)

Orchestration patterns optimized for Claude Code's Agent tool. Analyzes tasks and recommends the best combination of sequential loops and parallel subagents.

Subagent Configuration (Claude Code Agent Tool)

Agent tool parameters:
- description: "short task description"
- prompt: "detailed instructions"
- subagent_type: "general-purpose" | "Explore" | "Plan" | "coder-fe" | "coder-be"
- isolation: "worktree"  (gives agent an isolated repo copy)
- run_in_background: true  (for parallel execution)

Best practices:

• Use subagent_type: "Explore" for read-only scanning — faster and safer
• Use isolation: "worktree" when agents write to files — prevents merge conflicts
• Launch parallel agents in a single message with multiple Agent tool calls
• Use run_in_background: true for truly independent work streams

Orchestration Patterns

Pattern 1: Parallel Explore then Sequential Implement

Best for: Large codebases where you need to understand before you change.

Phase 1 (Parallel Subagents via Agent tool):
├── Agent "fe-scan" (Explore, background): Scan src/frontend/** → .loophaus/reports/frontend.md
├── Agent "be-scan" (Explore, background): Scan src/backend/** → .loophaus/reports/backend.md
└── Agent "db-scan" (Explore, background): Scan src/db/** → .loophaus/reports/db.md

Phase 2 (Loop):
└── Read merged reports → implement fixes story by story via prd.json

Pattern 2: Divide by Ownership

Best for: Multi-service changes where files do not overlap.

Spawn agents with isolation: "worktree":
├── Agent "fe-dev" (worktree): ONLY touch src/frontend/** → commit per item
├── Agent "be-dev" (worktree): ONLY touch src/backend/** → commit per item
└── Agent "auth-dev" (worktree): ONLY touch src/auth/** → commit per item

After all complete: merge branches, run integration tests

Pattern 3: Fan-Out / Fan-In Research

Best for: Comprehensive analysis before any action.

Fan-Out (parallel Agent calls in single message):
├── Agent "security" (Explore): Audit for OWASP top 10 → findings.md
├── Agent "perf" (Explore): Profile and benchmark → findings.md
└── Agent "a11y" (Explore): Check accessibility → findings.md

Fan-In (Loop):
└── Synthesize all findings → create action plan → implement