Ralph Agent Teams

Ralph Agent Teams

Orchestrate parallel implementation of Ralph++ PRD sub-stories using Agent Teams. Analyzes dependencies, groups parallelizable tasks by phase, spawns multiple agents, and coordinates their work.

Prerequisites

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Workflow Overview

1. Load PRD → Parse prd.json and progress.txt
2. Analyze → Build dependency graph, identify parallel groups
3. Execute phases → For each phase:
   a. Spawn agents (max 4) for independent sub-stories
   b. Coordinate via shared task list
   c. Resolve file conflicts
   d. Sync progress.txt
   e. Commit atomically per sub-story
4. Report → Show metrics (time saved, parallel efficiency)

Scripts

This skill includes helper scripts for orchestration:

• scripts/analyze_dependencies.py - Analyzes PRD and generates parallel phases
• scripts/check_conflicts.py - Detects file conflicts between sub-stories
• scripts/sync_progress.py - Merges progress from parallel agents

Execution

Step 1: Session Detection

SESSION_DIR=.ralph++/sessions/{session-id}
# Required: prd.json, progress.txt

If no session-id provided, auto-detect latest:

ls -t .ralph++/sessions/ | head -1

Step 2: Dependency Analysis

Run scripts/analyze_dependencies.py on prd.json:

python scripts/analyze_dependencies.py $SESSION_DIR/prd.json

Output: parallel_phases.json with structure:

{
  "phases": [
    {
      "id": 1,
      "substories": ["US-000-1"],
      "parallel": false,
      "reason": "foundation"
    },
    {
      "id": 2,
      "substories": ["US-000-2", "US-000-3"],
      "parallel": true,
      "max_agents": 2
    }
  ]
}

Step 3: Phase Execution

For each phase in parallel_phases.json:

Sequential phase (parallel: false):

• Use standard ralph-loop for single agent execution

Parallel phase (parallel: true):

• Spawn up to max_agents agents (default 4, configurable)
• Each agent receives:
  • Sub-story details (id, title, AC, files)
  • Codebase patterns from progress.txt
  • Quality gates to validate
  • File lock list (files other agents are modifying)

Step 4: Agent Coordination

Shared Task List Pattern:

Each agent:
1. Claims sub-story via TaskUpdate (status: in_progress, owner: agent-id)
2. Implements sub-story
3. Validates quality gates
4. Reports completion via TaskUpdate (status: completed)

File Conflict Resolution:

Before spawning agents, run scripts/check_conflicts.py:

python scripts/check_conflicts.py $SESSION_DIR/prd.json --substories US-001-1 US-001-2

• No conflicts → Run in parallel
• Conflicts detected → Follow suggested groupings

Conflict strategies:

1. lock_files (default): First agent locks, others wait
2. sequential_fallback: Revert to sequential if any overlap
3. merge_after: Agents work on temp branches, merge after

Step 5: Progress Synchronization

After each phase completion, run scripts/sync_progress.py:

python scripts/sync_progress.py $SESSION_DIR --phase 2

1. Agent writes learnings to temp file: progress_{agent-id}.txt
2. Script merges all temp files into progress.txt
3. Next phase agents receive merged context

Merge format:

## Phase {n} Learnings (Parallel)

### {sub-story-id}: {title}
**Agent:** {agent-id}
**Completed:** {timestamp}
**Learnings:**
- {pattern discovered}
- {gotcha encountered}

Step 6: Atomic Commits

One commit per sub-story (same as ralph-loop):

git add {filesAffected}
git commit -m "{sub-story.id}: {sub-story.title}

{description}

Acceptance criteria:
{list of criteria}

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

Step 7: Metrics Report

╔════════════════════════════════════════════════════════════════╗
║           RALPH++ AGENT TEAMS COMPLETE                        ║
╚════════════════════════════════════════════════════════════════╝

Feature: {project}
Branch: {branchName}

📊 Parallel Execution Metrics:
- Total Sub-Stories: {total}
- Parallel Phases: {parallelPhases} / {totalPhases}
- Max Concurrent Agents: {maxAgents}
- Sequential Time (estimated): {seqTime}
- Actual Time: {actualTime}
- Time Saved: {timeSaved} ({percentage}%)

✅ Phase Summary:
Phase 1 (sequential): US-000-1 ✅
Phase 2 (parallel x2): US-000-2 ✅, US-000-3 ✅
Phase 3 (parallel x3): US-001-1 ✅, US-001-2 ✅, US-002-2 ✅
...

Effort Tuning

Optimize cost by task type (requires effort-optimizer skill):

Error Handling

Agent Failure

• Retry up to 3 times with error context
• If still failing, mark sub-story blocked
• Continue with other agents in phase
• Report blocked stories at end

Conflict Detection

• If agents modify same file simultaneously
• Orchestrator detects via file locks
• Triggers sequential fallback for affected sub-stories

Quality Gate Failure

• Agent must fix before completing
• Backpressure ensures only passing work commits
• Failed gates prevent marking sub-story complete

Inter-Agent Communication

Research preview: The --channels flag (Claude Code v2.1.80+) enables MCP push messages between parallel agents, allowing real-time feedback and coordination without polling the filesystem. This could replace the current file-based progress sync for lower-latency inter-agent communication.

Configuration

# .ralph/agent-teams.yaml
enabled: true
max_parallel_agents: 4
conflict_strategy: lock_files  # lock_files | sequential_fallback | merge_after
effort_tuning: true
progress_sync_interval: 30s

Usage

# Basic (auto-detect session)
/ralph-agent-teams

# With options
/ralph-agent-teams --max-agents 4 --session-id 1768747324000

# Effort tuning enabled
/ralph-agent-teams --effort-tuning

Source: JimmyBlanquet/project-forge — distributed by TomeVault.