ralph-orchestrator

Files (1)

• SKILL.md

SKILL.md (first lines)

# Loop Orchestrator — Multi-Agent Loop Patterns

You are an expert at designing optimal execution strategies for Loop tasks.
When asked to orchestrate a task, analyze its structure and recommend the best combination of sequential loops, parallel subagents, and phased execution.

## Core Concept

Not every task should run in a single linear loop. Complex tasks benefit from:

- **Parallel exploration** — spawn subagents to search/analyze independently, then merge results
- **Divide and conquer** — split work by service/directory/concern with isolated agents
- **Pipeline stages** — sequential phases where each feeds into the next
- **Hybrid patterns** — combine parallel research with sequential implementation

## When to Use Subagents

### Use Subagents (Parallel) When:

| Signal                      | Example                                                    |
| --------------------------- | ---------------------------------------------------------- |
| **Broad codebase search**   | "Find all API endpoints that lack auth checks"             |
| **Independent file groups** | Frontend components + backend routes + database migrations |
| **Multi-service changes**   | auth-service + api-gateway + frontend simultaneously       |
| **Audit/review tasks**      | Security audit + performance audit + accessibility audit   |
| **Pattern extraction**      | Scan 50+ files for inconsistent patterns                   |

### Do NOT Use Subagents When:

| Signal                      | Reason                                               |
| --------------------------- | ---------------------------------------------------- |
| **Sequential dependencies** | Step 2 needs Step 1's output                         |
| **Shared mutable state**    | Multiple agents editing the same file = conflicts    |
| **Small scope (< 5 files)** | Overhead outweighs benefit                           |
| **Context-heavy tasks**     | Agent needs deep understanding of full codebase flow |

## Orchestration Patterns

### Pattern 1: Parallel Explore → Sequential Implement

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

```
Phase 1 (Parallel Subagents):
├── Agent A: Scan src/frontend/** for pattern X → report-frontend.md
├── Agent B: Scan src/backend/** for pattern X → report-backend.md
└── Agent C: Scan src/shared/** for pattern X → report-shared.md

Phase 2 (Sequential Loop):
└── Loop: Read all reports → implement fixes in priority order
```

**Prompt pattern for Phase 1:**

```
## Subagent Tasks (run in parallel)
Use the Agent tool to spawn these subagents simultaneously:

1. Agent "frontend-scan": Search src/frontend/** for [pattern].
   Write findings to .loophaus/reports/frontend-scan.md
2. Agent "backend-scan": Search src/backend/** for [pattern].
   Write findings to .loophaus/reports/backend-scan.md
3. Agent "shared-scan": Search src/shared/** for [pattern].
   Write findings to .loophaus/reports/shared-scan.md

After ALL agents complete, merge reports into .loophaus/reports/merged.md
with a unified priority list.
```

### Pattern 2: Divide by Ownership

Best for: Multi-service changes where files don't overlap.

```
Phase 1 (Parallel Implementation):
├── Agent "fe-dev": Modify src/frontend/** only → commit per item
├── Agent "be-dev": Modify src/backend/** only → commit per item
└── Agent "auth-dev": Modify src/auth/** only → commit per item

Phase 2 (Integration Verification):
└── Loop: Run full test suite, fix any integration issues
```

**Prompt pattern:**

```
## Parallel Work Streams
Spawn these agents with strict file ownership:

1. Agent "fe-dev" (isolation: worktree):
   - ONLY touch files in src/frontend/**
   - Tasks: [frontend items]
   - Commit each fix individually

2. Agent "be-dev" (isolation: worktree):
   - ONLY touch files in src/backend/**
   - Tasks: [backend items]
   - Commit each fix individually

After all agents complete, merge their branches and run integration tests.
```

### Pattern 3: Fan-Out / Fan-In Research

Best for: Tasks that need comprehensive analysis before any action.

```
Fan-Out (Parallel):
├── Agent 1: Analyze problem from angle A → findings-a.md
├── Agent 2: Analyze problem from angle B → findings-b.md
└── Agent 3: Analyze problem from angle C → findings-c.md

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

### Pattern 4: Pipeline with Checkpoints

Best for: Complex multi-stage transformations.

From vcz-Gray/loophaus, MIT.

More from vcz-Gray/loophaus