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 <[email protected]>"

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):

Task Type	Effort	Rationale
database.schema	high	Critical foundation
database.rls	high	Security critical
types	medium	Derived from schema
service	medium	Standard patterns
api	low	Repetitive patterns
frontend	medium	Variable complexity
tests	low	Established patterns

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