ralph-agent-teams

Files (4)

• SKILL.md
• analyze_dependencies.py · scripts/
• check_conflicts.py · scripts/
• sync_progress.py · scripts/

SKILL.md (first lines)

# 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

```bash
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

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

If no session-id provided, auto-detect latest:
```bash
ls -t .ralph++/sessions/ | head -1
```

### Step 2: Dependency Analysis

Run `scripts/analyze_dependencies.py` on prd.json:

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

Output: `parallel_phases.json` with structure:
```json
{
  "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`:
```bash
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`:
```bash

From JimmyBlanquet/project-forge, MIT.

More from JimmyBlanquet/project-forge