# ralph-teams - Loop epics and ai teams, Trust the Team-Lead, Run and Walk away

Lightweight orchestration for spec-driven AI delivery: Ralph Teams loops whole teams and epics, not tiny tasks, and uses small agent teams to move from PRD to merged implementation with minimal process overhead. 

The Teamlead decides on which agent to spawn and which model to use depending on the task complexity. 

It is built for developer who don't want to babysit their agents. Start the loop and walk away.

`ralph-teams` is a lightweight and budgetfriendly CLI for running Ralph Teams: a shell-based orchestrator that initializes and reads a `prd.json`, loops through epics (not user stories), and spawns AI coding agent teams to implement work story by story. One Agent Team per Epic with fresh context. Ralph-Teams can even work on multiple epics in parallel, if there are no dependencies
```bash
ralph-teams run --parallel={max_parallel_epics}
```

## Why Use Ralph-Teams

Many spec-driven tools are heavy, burn a lot of tokens, and are harder to adapt when the underlying agent capabilities change. Ralph's original idea was to trust the agent more and keep orchestration light. That bias fits the current direction of AI tooling: agents keep getting better, context windows keep growing, and models are increasingly able to coordinate teams of sub-agents on their own.

`ralph-teams` is built around that idea. Instead of heavy process layers, it loops whole epics with small agent teams and keeps the orchestration simple and configurable. In my experience, the epic and user-story structure tends to work well because the user-centric view and explicit acceptance criteria give the agents a clearer picture of what "done" means.

The default `balanced` mode is intentionally simple:
- the Team Lead orchestrates the epic
- for clearly easy, low-risk mechanical work, the Team Lead may implement directly
- it can spawn the epic planner if needed
- it spawns one Builder per story attempt
- it validates inline or spawns a validator when independent verification is needed
- it works through the user stories sequentially until the epic is done
- Ralph then moves to the next epic until all epics are done

## Quickest Start

```bash
npm install -g ralph-teams

# discuss with an agent and create the prd.json (epics and user stories)
ralph-teams init

# start the loop, by default uses claude
ralph-teams run
```

## Flow

This diagram shows the default `balanced` workflow only.

```mermaid
flowchart TD
    A[Start run] --> B[Validate PRD and create loop branch plus loop worktree]
    B --> C[Pick ready epic]
    C --> D[Create epic worktree and run-scoped epic branch]
    D --> E[Team Lead decides on epic planner]
    E --> F[Team Lead runs stories with builder]
    F --> G{Epic validator needed?}
    G -->|No| J[Team Lead merges epic branch and writes merge artifact]
    G -->|Yes| H[Run epic validator]
    H -->|PASS| J
    H -->|FAIL and retries left| I[Builder fixes epic-level findings]
    I --> H
    J --> K[If needed, fallback merge recovery handles leftovers]
    K --> L{More epics?}
    L -->|Yes| C
    L -->|No| P[Finish]
```

Other presets:

- `full`: adds optional story planner and optional story validator decisions inside each epic.
- `minimal`: disables planner and validator subagent stages. The Team Lead still coordinates builders and records per-story pass/fail results.

## What It Does

At a high level:
- `ralph.sh` owns the run loop, worktrees, merges, resume state, and backend process lifecycle.
- one Team Lead session runs per epic and delegates to planner, builder, validator, and merger roles as needed, or implements trivial work directly.
- `ralph.config.yml` controls backend choice, workflow toggles, parallelism, timeouts, and model selection.

Workflow presets:
- `balanced`: epic planning enabled, heuristic epic validation enabled (no final validation)
- `full`: `balanced`, plus story planning, heuristic story validation, and final validation
- `minimal`: planning and validation toggles disabled; no planner or validator subagents are spawned

Default agent model assignments:
- `teamLead`: `opus`
- `epicPlanner`: `opus`
- `epicValidator`: `opus`
- `finalValidator`: `opus`
- `builder`: `sonnet`
- `storyValidator`: `sonnet`
- `storyPlanner`: `opus`
- `merger`: `sonnet`

Ralph never writes code itself. It only schedules work, tracks results, and updates project state.

For detailed workflow semantics, validation behavior, config precedence, runtime files, and architecture, see [docs/architecture.md](docs/architecture.md).

Current backends:

- `claude` via the `claude` CLI and `.claude/agents/*.md`
- `copilot` via `gh copilot` and `.github/agents/*.agent.md`
- `codex` via the `codex` CLI, repo-local `.codex/agents/*.toml`, and Codex multi-agent mode
- `opencode` via the `opencode` CLI and `.opencode/agents/*.md`
- shared worker-agent prompt source in `prompts/agents/*.md`, rendered to those backend-specific files via `npm run sync:agents`


## Requirements

- Node.js 18+
- Git available if you want Ralph to switch/create the target branch

Backend-specific requirements:

- Claude backend:
  - `claude` CLI in `PATH`
- Copilot backend:
  - `gh` CLI in `PATH`
  - GitHub Copilot CLI available through `gh copilot`
- Codex backend:
  - `codex` CLI in `PATH`
  - multi-agent feature enabled by the CLI (Ralph passes `--enable multi_agent` automatically)
- OpenCode backend:
  - `opencode` CLI in `PATH`

## Install

Install globally:

```bash
npm install -g ralph-teams
```

Or use it locally from this repo:

```bash
npm install
npm run build
npm link
```

Then verify:

```bash
ralph-teams --help
rjq --help
```

## Start

1. Create a PRD:

```bash
ralph-teams init
```

2. Validate it:

```bash
ralph-teams validate
```

3. Inspect the planned work:

```bash
ralph-teams summary
ralph-teams status
```

4. Run Ralph:

```bash
ralph-teams run
```

5. Check progress:

```bash
ralph-teams logs
```

Run `ralph.sh` directly when you want shell-level flags:

```bash
./ralph.sh prd.json --backend claude
./ralph.sh prd.json --backend copilot
./ralph.sh prd.json --backend codex
./ralph.sh prd.json --parallel 2
./ralph.sh prd.json --backend copilot --max-epics 1
```

## Commands

### `ralph-teams setup`

Runs interactive setup to create or update `ralph.config.yml` for your repository.

```bash
ralph-teams setup
```

Prompts for:
- Default backend (`claude`, `copilot`, `codex`, `opencode`)
- Planning/validation workflow setup: use a preset or configure each planning and validation step manually
- Workflow preset (`balanced`, `full`, `minimal`) with short inline explanations during setup
- Parallel epic execution and max parallel epics
- Overall loop timeout
- Agent model overrides (optional)

Workflow presets:
- `balanced`: epic planning enabled, heuristic epic validation enabled (no final validation)
- `full`: `balanced`, plus story planning, heuristic story validation, and final validation
- `minimal`: planning and validation toggles disabled; no planner or validator subagents are spawned

Preset behavior notes:
- `minimal` still lets the Team Lead validate stories inline and mark them passed or failed; it only disables the separate planner/validator subagent stages.

### `ralph-teams init`

Creates a new `prd.json` interactively in the current directory by launching an AI PRD-creator session. If `ralph.config.yml` does not already exist, `init` first runs interactive setup so you can configure Ralph for the repository.

```bash
ralph-teams init
ralph-teams init --backend claude
ralph-teams init --backend copilot
ralph-teams init --backend codex
ralph-teams init --backend opencode
```

Flow:

1. `init` launches an interactive agent session
2. the agent discusses the product with you directly
3. the agent asks follow-up questions until the requirements are clear
4. the agent generates the full `prd.json` with project metadata, epics, and user stories
5. if `./ralph.config.yml` is missing, `init` first runs `ralph-teams setup` interactively and writes the chosen config
6. the agent writes `./prd.json`
7. after writing the PRD, the init agent can either continue into implementation planning with you or stop there if you want to skip planning for now

Notes:

- `init` is grounded by `prd.json.example`
- `init` does not overwrite an existing `ralph.config.yml`
- `setup` lets you choose the default backend, use a planning/validation workflow preset or configure that workflow manually, set parallelism, and optionally override per-role models
- the agent generates epics and user stories automatically
- the agent should aim for about 5 user stories per epic when the scope supports it
- treat about 5 user stories as the current practical ceiling for an epic, not just a suggestion; this keeps the Team Lead session context under control and avoids overwhelming the epic planner
- `--backend` controls whether the interview/generation uses `claude`, `copilot`, `codex`, or `opencode`
- the discussion itself is handled by the agent, not by a hardcoded questionnaire in the CLI

### `ralph-teams run [path]`

Runs Ralph against a PRD file. Default path is `./prd.json`.

```bash
ralph-teams run
ralph-teams run ./my-prd.json
ralph-teams run --backend copilot
ralph-teams run --backend codex
ralph-teams run --parallel 2
```

Behavior:

- validates that the selected backend dependencies, `rjq`, and the PRD are available
- locates bundled `ralph.sh`
- streams Ralph output directly to the terminal
- exits with Ralph's exit code

Notes:

- `--backend` is forwarded to `ralph.sh`
- runs sequentially by default
- `--parallel <n>` enables the experimental parallel wave runner

Planning behavior:

- if an epic has `planned: true`, the Team Lead is expected to read `.ralph-teams/plans/plan-EPIC-xxx.md` and follow it
- if an epic is still unplanned and epic planning is enabled, medium- and high-complexity epics should spawn the epic planner before implementation
- only clearly low-complexity epics should skip planning during execution

### `ralph-teams task <prompt>`

Runs an ad hoc task in the current repository without creating a PRD, epic, or story structure.

```bash
ralph-teams task "fix the flaky auth test"
ralph-teams task "add rate limiting to login" --backend codex
```

Behavior:

- requires a checked out git branch and runs on that same branch
- asks once whether you want to plan the task first
- if you choose planning, starts a guided planning session with the agent
- otherwise starts direct Team Lead execution for the task

Notes:

- this mode does not create `prd.json` entries or worktrees
- `--backend` controls whether the task uses `claude`, `copilot`, or `codex`

### `ralph-teams plan [path]`

Starts a guided planning discussion for epics that are not yet marked as planned. Default path is `./prd.json`.

```bash
ralph-teams plan
ralph-teams plan ./my-prd.json
ralph-teams plan --backend claude
```

Behavior:

- loads epics with `planned !== true`
- starts an interactive agent discussion about implementation approach and sequencing
- asks the agent to write `.ralph-teams/plans/plan-EPIC-xxx.md`
- asks the agent to mark each agreed epic as `planned: true` in `prd.json`

Notes:

- this command is intended after `ralph-teams init`
- if you skip an epic during planning, it remains `planned: false`
- planned epics should not require the Team Lead to spawn another epic planner later

### `ralph-teams resume`

Resumes an interrupted run from `./.ralph-teams/ralph-state.json`.

```bash
ralph-teams resume
```

Behavior:

- reloads the saved PRD path, backend, and parallel settings
- reuses the current project config for timeouts and workflow settings
- restarts `ralph.sh`
- removes `.ralph-teams/ralph-state.json` after a successful resume

### `ralph-teams status [path]`

Shows epic and story pass/fail state from a PRD.

```bash
ralph-teams status
ralph-teams status ./my-prd.json
```

### `ralph-teams logs [--tail N]`

Shows `.ralph-teams/progress.txt` with light colorization.

```bash
ralph-teams logs
ralph-teams logs --tail 20
```

`--tail` shows the last `N` wave blocks from `.ralph-teams/progress.txt`.

### `ralph-teams reset [epicId] [path]`

Resets one epic to `pending` and sets all of its stories back to `passes: false`. When no epic ID is provided, resets all epics.

```bash
ralph-teams reset EPIC-002
ralph-teams reset          # resets all epics
```

### `ralph-teams validate [path]`

Validates PRD structure and dependency integrity.

```bash
ralph-teams validate
```

Checks include:

- required fields
- valid epic status values
- duplicate epic IDs
- duplicate story IDs
- invalid `dependsOn` values
- unknown `dependsOn` references
- circular epic dependencies

### `ralph-teams summary [path]`

Prints a dependency-oriented overview of epics.

```bash
ralph-teams summary
```

Shows:

- dependency arrows
- epic status
- story pass counts
- blocked epics

## Backends

### Claude Backend

Uses:

- `claude` CLI
- canonical worker prompts in `prompts/agents/`
- `.claude/agents/`
- structured JSON streaming from the Claude CLI

Example:

```bash
./ralph.sh prd.json --backend claude
```

### Copilot Backend

Uses:

- `gh copilot`
- canonical worker prompts in `prompts/agents/`
- `.github/agents/`
- PTY-backed execution so live Copilot output is visible during runs

Example:

```bash
./ralph.sh prd.json --backend copilot
```

Notes:

- Copilot live output is routed through a PTY wrapper in `ralph.sh`
- without the PTY wrapper, `gh copilot` may not show incremental output in pipe mode
- Copilot difficulty-based defaults now use GPT-family models: `gpt-5-mini`, `gpt-5.3-codex`, and `gpt-5.4`

### Codex Backend

Uses:

- `codex exec`
- canonical worker prompts in `prompts/agents/`
- `.codex/agents/*.toml`
- Codex multi-agent mode with repo-local scoped planner, builder, and validator roles

Example:

```bash
./ralph.sh prd.json --backend codex
```

Notes:

- Ralph enables Codex multi-agent mode per run, so no global `~/.codex/config.toml` edits are required
- Codex runs from each epic worktree and is granted write access to the repo root so it can update the shared PRD
- Codex does not use a separate repo-local Team Lead role file; the Team Lead policy comes from the runtime prompt assembled in `ralph.sh`, while `.codex/agents/*.toml` define the spawned story-planner, epic-planner, builder, story-validator, epic-validator, final-validator, and merger roles
- Codex follows the same scoped planning/validation contract as Claude and Copilot; the runtime prompt in `ralph.sh` enforces that policy for Codex Team Leads
- Edit `prompts/agents/*.md` and run `npm run sync:agents` to regenerate the backend-specific worker agent files

### OpenCode Backend

Uses:

- `opencode` CLI
- canonical worker prompts in `prompts/agents/`
- `.opencode/agents/`

Example:

```bash
./ralph.sh prd.json --backend opencode
```

## PRD Format

Example:

```json
{
  "project": "MyApp",
  "branchName": "main",
  "description": "Short description of the project",
  "epics": [
    {
      "id": "EPIC-001",
      "title": "Authentication",
      "description": "Add login and session handling",
      "status": "pending",
      "planned": false,
      "dependsOn": [],
      "userStories": [
        {
          "id": "US-001",
          "title": "Login form",
          "description": "As a user, I want to sign in",
          "acceptanceCriteria": [
            "User can submit email and password",
            "Validation errors are shown clearly"
          ],
          "priority": 1,
          "passes": false,
          "failureReason": null
        }
      ]
    }
  ]
}
```

Important fields:

- `epics[].status`: `pending` | `completed` | `partial` | `failed` | `merge-failed`
- `epics[].planned`: whether the implementation plan for this epic has already been created and agreed
- `epics[].dependsOn`: epic IDs that must be completed first
- `userStories[].passes`: whether the story is currently marked as passing
- `userStories[].failureReason`: short reason for the latest failed attempt, or `null`

Authoring guideline:

- aim for about 5 user stories per epic when the scope can be split cleanly
- treat about 5 user stories as the current practical ceiling for an epic so the Team Lead session stays within a reasonable context window and the epic planner is not overloaded
- use fewer only when the epic is genuinely small or further splitting would be artificial

The `init` command uses `prd.json.example` as schema and style guidance when generating a new PRD.

## Files Ralph Produces

During a run, Ralph writes:

- `.ralph-teams/progress.txt`: high-level run log
- `.ralph-teams/.worktrees/EPIC-xxx/`: isolated git worktree for an active epic
- `.ralph-teams/state/EPIC-xxx.json`: per-epic story pass/fail state (Team Lead reads/writes)
- `.ralph-teams/state/merge-EPIC-xxx.json`: per-epic merge-result artifact written by the Team Lead or merge recovery path
- `.ralph-teams/plans/plan-EPIC-xxx.md`: epic-planner output for an epic
- planned epics are expected to use these files as their implementation contract
- `.ralph-teams/logs/loop-<timestamp>.log`: outer `ralph-teams run` orchestration log mirroring terminal output
- `.ralph-teams/logs/epic-EPIC-xxx-<timestamp>.log`: raw backend session log
- `.ralph-teams/ralph-state.json`: saved interrupt/resume state

Ralph also updates the original `prd.json` in place as epic status changes.

The outer run log and the team lead agent log for each epic are written to `.ralph-teams/logs/` regardless of backend.

## Runtime Rules

The current execution contract is:

- Ralph loops through epics in PRD order
- blocked epics are skipped until dependencies are complete
- runs sequentially by default
- experimental wave parallelism is enabled only with `--parallel <n>`
- at run start Ralph auto-commits any dirty source-worktree changes, then creates a fresh loop branch and checks it out in `.ralph-teams/.worktrees/loop`
- each epic gets its own worktree and a run-scoped branch rooted from that loop branch, using `ralph/epic/<loop-run>/<epic-id>`
- before the Team Lead starts, Ralph creates the worktree and expects the Team Lead to establish that epic worktree's setup once, then hand the exact bootstrap, build, and test commands to Builders
- agents are expected to prefer repo-defined scripts and docs over generic ecosystem defaults when choosing setup and verification commands
- the shell-built Team Lead prompt must keep literal filenames shell-safe; do not add raw Markdown backticks inside that Bash string because Bash will treat them as command substitution
- when an epic completes successfully, the Team Lead is expected to merge its epic branch back into the loop branch and write the merge-result artifact
- the backend team processes one epic per session
- stories run sequentially inside that epic
- already-passed stories are skipped
- rerunning Ralph automatically resets `failed` and `partial` epics back to `pending` so only unfinished work is retried
- each story gets at most two build/validate cycles
- Builder and Validator are one-shot story-scoped workers, never long-lived mailboxes shared across stories
- a Builder attempt only counts when the Team Lead receives a concrete commit SHA for that story attempt
- scoped validators check output independently from the builder's reasoning
- the Team Lead is expected to delegate early and not inspect the codebase beyond the minimum needed before delegation
- for clearly easy, low-risk mechanical tasks, the Team Lead may implement directly instead of delegating
- `DONE: X/Y stories passed` is a required session footer, but it is not enough to complete an epic on its own
- the durable epic-completion contract is: projected story state plus a valid merge-result artifact
- if PRD state says an epic is pending but the current loop branch already contains prior merge history for that run-scoped epic branch, Ralph fails fast instead of silently reusing stale history
- pressing `Ctrl-C` writes `.ralph-teams/ralph-state.json` so the run can be resumed later with `ralph-teams resume`

## Troubleshooting

### `zsh: command not found: ralph-teams`

Install or relink the package:

```bash
npm install -g ralph-teams
```

Or from this repo:

```bash
npm link
```

The package also installs `rjq`, which `ralph.sh` uses internally.

### `Error: 'claude' CLI not found`

Install Claude Code and ensure `claude` is on your `PATH`.

### `Error: 'gh' CLI not found`

Install GitHub CLI and ensure `gh` is on your `PATH`.

### `Error: 'codex' CLI not found`

Install Codex CLI and ensure `codex` is on your `PATH`.

### `Error: 'opencode' CLI not found`

Install OpenCode CLI and ensure `opencode` is on your `PATH`.

### `Error: GitHub Copilot CLI not available`

Make sure `gh copilot` is installed and working:

```bash
gh copilot -- --version
```

### Copilot backend runs but shows no live output

This repo runs Copilot through a PTY wrapper in `ralph.sh` because plain pipe mode does not reliably stream visible output from `gh copilot`.

If output still looks stuck, test the backend directly:

```bash
./ralph.sh prd.json --backend copilot --max-epics 1
```

If that still does not stream, the issue is likely in the local `gh copilot` environment rather than the CLI wrapper.

Install Claude Code and ensure `claude` is on your `PATH`.

### `Error: 'rjq' not found`

Install or relink the package so the bundled JSON CLI is on your `PATH`:

```bash
npm install -g ralph-teams
```

### Ralph needs a clean base commit before creating the loop worktree

Ralph auto-commits current source-worktree changes before creating the loop branch and loop worktree. If you do not want that commit, clean up the worktree yourself before starting the run.

## Development

Useful commands in this repo:

```bash
npm run build
npm run typecheck
npm test
npm link
```

Packaged binaries:

- `ralph-teams`: main CLI entrypoint (`dist/index.js`)
- `rjq`: bundled JSON query/manipulation CLI used by `ralph.sh` (`dist/json-tool.js`)

The runtime orchestrator is `ralph.sh`.