starred/ralph-orchestrator

Fork 0

mirror of https://github.com/mikeyobrien/ralph-orchestrator.git synced 2026-04-25 15:15:57 +03:00

[GH-ISSUE #161] [Feature]: support Claude Agent Teams in ralph plan for parallel research and design #61

New issue

Closed

opened 2026-02-27 10:22:01 +03:00 by kerem · 4 comments

kerem commented

2026-02-27 10:22:01 +03:00

Owner

Originally created by @The-Zona-Zoo on GitHub (Feb 7, 2026).
Original GitHub issue: https://github.com/mikeyobrien/ralph-orchestrator/issues/161

Originally assigned to: @The-Zona-Zoo on GitHub.

Use case

ralph plan spawns a single interactive Claude session that executes the PDD (Prompt-Driven Development) SOP sequentially -- one research topic at a time, one design perspective at a time. For complex
features, the research phase (Step 4) and design phase (Step 6) become bottlenecks because a single agent must serially:

Explore codebase patterns
Investigate external libraries and approaches
Review prior art and existing implementations
Draft and iterate on the design

Claude Code now has an experimental Agent Teams feature that allows a session to spawn parallel teammates that work independently and communicate with each other. This is a natural fit for PDD's research and design phases:

Parallel research: One teammate investigates codebase patterns while another researches external approaches
Adversarial design review: A teammate plays devil's advocate on the design while another strengthens it
Competing hypotheses: Multiple teammates explore different architectural approaches and debate trade-offs

This aligns with Ralph's philosophy of "letting agents do the work" -- Agent Teams lets Claude self-organize the most effective research strategy rather than being constrained to sequential execution.

Proposed solution

Core plumbing (~20 lines across 2 files)

ralph plan already spawns Claude via spawn_interactive() using std::process::Command. The integration requires:

New CLI flag: ralph plan --teams "Build a rate limiter"
Environment variable injection: Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 on the spawned process when --teams is passed
Adjust disallowed tools: Remove TaskCreate, TaskUpdate, TaskList, TaskGet from --disallowedTools when teams are enabled (Agent Teams uses these internally for coordination)

SOP handling: separate team-aware variant

The PDD SOP content must differ based on whether teams are enabled. If the base pdd.md mentions teams when they're not available, the agent gets confused. If it doesn't mention teams when they are available, it won't leverage them.

Approach: Duplicate the SOP into pdd.md (current, unchanged) and pdd-teams.md (team-aware variant). The SOP runner selects which to use based on the --teams flag.

The team-aware variant would modify specific PDD steps:

Research (Step 4): Instruct Claude to spawn teammates for parallel codebase exploration, external research, and technology evaluation
Design (Step 6): Instruct Claude to spawn a design critic teammate for adversarial review
Iteration Checkpoints (Step 5): Synthesize findings from all teammates before asking the user to proceed

Files affected

File	Change
`crates/ralph-cli/src/main.rs`	Add `--teams` to `PlanArgs`, thread to `SopRunConfig`
`crates/ralph-cli/src/sop_runner.rs`	Accept `agent_teams` flag, select SOP variant, inject env var in `spawn_interactive()`, conditionally adjust `--disallowedTools`
`crates/ralph-cli/sops/pdd-teams.md`	New team-aware PDD SOP variant

Area

CLI

Backend(s) impacted

claude

Alternatives considered

1. Conditional prompt assembly (no SOP duplication)

Keep a single pdd.md and have build_prompt() conditionally append a <teams-guidance> section to the prompt only when --teams is passed. This avoids maintaining two SOP files but adds complexity to prompt assembly. Could be a follow-up refinement if the duplicated files drift out of sync.

2. Hat-level integration (agent teams in the orchestration loop)

Instead of enhancing ralph plan, integrate Agent Teams into the hat-based event loop so that any hat (e.g., Builder) could spawn a team. This is a much larger architectural change and doesn't address the specific pain point of slow planning/research. Could be a separate future feature.

3. Worktree-based parallelism for planning

Ralph already supports parallel loops via git worktrees. Multiple ralph plan sessions could theoretically run in parallel worktrees. However, worktrees are designed for isolated execution -- they don't enable the inter-agent communication (debate, synthesis, adversarial review) that makes Agent Teams valuable for research and design work.

Additional context

End-to-end flow

$ ralph plan --teams "Build a rate limiter"

CLI parses --teams flag into PlanArgs
plan_command() creates SopRunConfig { agent_teams: true, ... }
run_sop() selects pdd-teams.md SOP (instead of pdd.md)
build_prompt() wraps team-aware SOP in tags as usual
spawn_interactive() sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var
spawn_interactive() uses claude_interactive() WITHOUT TaskCreate/etc in disallowedTools
Claude enters interactive session with team-aware PDD instructions
During Research step, Claude self-organizes a team:
- Teammate A: explores codebase patterns
- Teammate B: researches external approaches
- Teammate C: investigates edge cases
During Design step, Claude spawns a critic teammate
User interacts with lead session as normal (same UX, gates still enforced)
Artifacts written to specs/{task_name}/ as usual

Key technical details

spawn_interactive() in sop_runner.rs uses std::process::Command which makes env var injection trivial (.env("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS", "1"))
Interactive Claude sessions use positional prompt (no -p flag), OutputFormat::Text, and inherit stdin/stdout/stderr
The PDD SOP is ~166 lines and compiled into the binary via include_str!("../sops/pdd.md")
Agent Teams is experimental and requires opt-in: https://code.claude.com/docs/en/agent-teams

Considerations

Experimental: Agent Teams has known limitations (no session resumption, task status lag, slow shutdown)
Cost: Each teammate is a separate Claude instance, increasing token usage
Claude-only: Non-Claude backends would ignore --teams with a warning
SOP duplication: Two-file approach trades drift risk for simplicity; the SOP is small (~166 lines) and changes infrequently

Originally created by @The-Zona-Zoo on GitHub (Feb 7, 2026). Original GitHub issue: https://github.com/mikeyobrien/ralph-orchestrator/issues/161 Originally assigned to: @The-Zona-Zoo on GitHub. ## Use case `ralph plan` spawns a single interactive Claude session that executes the PDD (Prompt-Driven Development) SOP sequentially -- one research topic at a time, one design perspective at a time. For complex features, the research phase (Step 4) and design phase (Step 6) become bottlenecks because a single agent must serially: - Explore codebase patterns - Investigate external libraries and approaches - Review prior art and existing implementations - Draft and iterate on the design Claude Code now has an experimental [Agent Teams](https://code.claude.com/docs/en/agent-teams) feature that allows a session to spawn parallel teammates that work independently and communicate with each other. This is a natural fit for PDD's research and design phases: - **Parallel research**: One teammate investigates codebase patterns while another researches external approaches - **Adversarial design review**: A teammate plays devil's advocate on the design while another strengthens it - **Competing hypotheses**: Multiple teammates explore different architectural approaches and debate trade-offs This aligns with Ralph's philosophy of "letting agents do the work" -- Agent Teams lets Claude self-organize the most effective research strategy rather than being constrained to sequential execution. ## Proposed solution ### Core plumbing (~20 lines across 2 files) `ralph plan` already spawns Claude via `spawn_interactive()` using `std::process::Command`. The integration requires: 1. **New CLI flag**: `ralph plan --teams "Build a rate limiter"` 2. **Environment variable injection**: Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` on the spawned process when `--teams` is passed 3. **Adjust disallowed tools**: Remove `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet` from `--disallowedTools` when teams are enabled (Agent Teams uses these internally for coordination) ### SOP handling: separate team-aware variant The PDD SOP content must differ based on whether teams are enabled. If the base `pdd.md` mentions teams when they're not available, the agent gets confused. If it doesn't mention teams when they are available, it won't leverage them. **Approach**: Duplicate the SOP into `pdd.md` (current, unchanged) and `pdd-teams.md` (team-aware variant). The SOP runner selects which to use based on the `--teams` flag. The team-aware variant would modify specific PDD steps: - **Research (Step 4)**: Instruct Claude to spawn teammates for parallel codebase exploration, external research, and technology evaluation - **Design (Step 6)**: Instruct Claude to spawn a design critic teammate for adversarial review - **Iteration Checkpoints (Step 5)**: Synthesize findings from all teammates before asking the user to proceed ### Files affected | File | Change | |------|--------| | `crates/ralph-cli/src/main.rs` | Add `--teams` to `PlanArgs`, thread to `SopRunConfig` | | `crates/ralph-cli/src/sop_runner.rs` | Accept `agent_teams` flag, select SOP variant, inject env var in `spawn_interactive()`, conditionally adjust `--disallowedTools` | | `crates/ralph-cli/sops/pdd-teams.md` | New team-aware PDD SOP variant | ## Area CLI ## Backend(s) impacted claude ## Alternatives considered ### 1. Conditional prompt assembly (no SOP duplication) Keep a single `pdd.md` and have `build_prompt()` conditionally append a `<teams-guidance>` section to the prompt only when `--teams` is passed. This avoids maintaining two SOP files but adds complexity to prompt assembly. Could be a follow-up refinement if the duplicated files drift out of sync. ### 2. Hat-level integration (agent teams in the orchestration loop) Instead of enhancing `ralph plan`, integrate Agent Teams into the hat-based event loop so that any hat (e.g., Builder) could spawn a team. This is a much larger architectural change and doesn't address the specific pain point of slow planning/research. Could be a separate future feature. ### 3. Worktree-based parallelism for planning Ralph already supports parallel loops via git worktrees. Multiple `ralph plan` sessions could theoretically run in parallel worktrees. However, worktrees are designed for isolated execution -- they don't enable the inter-agent communication (debate, synthesis, adversarial review) that makes Agent Teams valuable for research and design work. ## Additional context ### End-to-end flow `$ ralph plan --teams "Build a rate limiter"` 1. CLI parses --teams flag into PlanArgs 2. plan_command() creates SopRunConfig { agent_teams: true, ... } 3. run_sop() selects pdd-teams.md SOP (instead of pdd.md) 4. build_prompt() wraps team-aware SOP in tags as usual 5. spawn_interactive() sets CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 env var 6. spawn_interactive() uses claude_interactive() WITHOUT TaskCreate/etc in disallowedTools 7. Claude enters interactive session with team-aware PDD instructions 8. During Research step, Claude self-organizes a team: - Teammate A: explores codebase patterns - Teammate B: researches external approaches - Teammate C: investigates edge cases 9. During Design step, Claude spawns a critic teammate 10. User interacts with lead session as normal (same UX, gates still enforced) 11. Artifacts written to specs/{task_name}/ as usual ### Key technical details - `spawn_interactive()` in `sop_runner.rs` uses `std::process::Command` which makes env var injection trivial (`.env("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS", "1")`) - Interactive Claude sessions use positional prompt (no `-p` flag), `OutputFormat::Text`, and inherit stdin/stdout/stderr - The PDD SOP is ~166 lines and compiled into the binary via `include_str!("../sops/pdd.md")` - Agent Teams is experimental and requires opt-in: https://code.claude.com/docs/en/agent-teams ### Considerations - **Experimental**: Agent Teams has [known limitations](https://code.claude.com/docs/en/agent-teams#limitations) (no session resumption, task status lag, slow shutdown) - **Cost**: Each teammate is a separate Claude instance, increasing token usage - **Claude-only**: Non-Claude backends would ignore `--teams` with a warning - **SOP duplication**: Two-file approach trades drift risk for simplicity; the SOP is small (~166 lines) and changes infrequently

kerem

2026-02-27 10:22:01 +03:00

closed this issue
added the
enhancement
label

kerem commented

2026-02-27 10:22:01 +03:00

Author

Owner

@The-Zona-Zoo commented on GitHub (Feb 7, 2026):

Happy to work on this if it sounds like a good feature.

@The-Zona-Zoo commented on GitHub (Feb 7, 2026): Happy to work on this if it sounds like a good feature.

kerem commented

2026-02-27 10:22:01 +03:00

Author

Owner

@mikeyobrien commented on GitHub (Feb 7, 2026):

I like it. Go for it!

@mikeyobrien commented on GitHub (Feb 7, 2026): I like it. Go for it!

kerem commented

2026-02-27 10:22:01 +03:00

Author

Owner

@aappddeevv commented on GitHub (Feb 11, 2026):

I think I see that this requires a claude backend, is that right? Or can it be setup to work with different backends?

@aappddeevv commented on GitHub (Feb 11, 2026): I think I see that this requires a claude backend, is that right? Or can it be setup to work with different backends?

kerem commented

2026-02-27 10:22:01 +03:00

Author

Owner

@The-Zona-Zoo commented on GitHub (Feb 11, 2026):

I think I see that this requires a claude backend, is that right? Or can it be setup to work with different backends?

Only Claude. The feature being utilized under the hood is a claude code feature.

@The-Zona-Zoo commented on GitHub (Feb 11, 2026): > I think I see that this requires a claude backend, is that right? Or can it be setup to work with different backends? Only Claude. The feature being utilized under the hood is a claude code feature.

kerem referenced this issue

2026-02-27 10:22:17 +03:00

[PR #61] [CLOSED] fix: surface exception error in iteration failure msg #113