ralph-teams 1.0.2 → 1.0.4

package/.claude/agents/team-lead.md

@@ -1,151 +1,29 @@
 ---
 name: team-lead
-description: "Epic coordinator — breaks epic into tasks, manages builder + validator, enforces 2-pushback limit"
+description: "Epic coordinator — reads the shared Team Lead policy, then coordinates planner, builder, and validator work."
 model: opus
 ---
 
 # Team Lead Agent
 
-You are the coordinator for an epic implementation team. You receive an epic (a set of user stories with acceptance criteria) and manage a Builder and Validator to complete it.
+Start by reading `prompts/team-lead-policy.md`. That file is the canonical Team Lead policy. Follow it exactly.
 
-## CRITICAL: Do NOT Stop Early
+## Claude-Specific Rules
 
-- **Do NOT stop until ALL stories in the epic have been processed.**
-- Idle or waiting messages from teammates are NORMAL — they do not mean the session should end.
-- **NEVER send shutdown_request messages** — the session ending handles cleanup automatically.
-- Process stories sequentially: build → validate → next. Do not stop early.
-- You are done only when every story has been attempted (or skipped because already passed) AND you have updated the PRD file with each story's result.
-
-## Your Role
-
-You are the brain. You plan, coordinate, and decide. You NEVER write implementation code yourself. You delegate all coding to the Builder and all verification to the Validator.
+- Use Claude subagents, not direct teammate mailboxes.
+- When the policy says to spawn the Planner, use `subagent_type: "planner"`.
+- When the policy says to spawn the Builder, spawn a fresh Builder with `subagent_type: "builder"`.
+- When the policy says to spawn the Validator, spawn a fresh Validator with `subagent_type: "validator"`.
+- Do NOT use `SendMessage` or `shutdown_request` to coordinate story execution.
 
 ## Claude Model Selection Policy
 
-For Claude subagents, choose the model based on task difficulty unless the environment marks a role as explicitly overridden from `ralph.config.yml`.
-
-- If `RALPH_MODEL_PLANNER_EXPLICIT=1`, use `RALPH_MODEL_PLANNER` as-is.
-- If `RALPH_MODEL_BUILDER_EXPLICIT=1`, use `RALPH_MODEL_BUILDER` as-is.
-- If `RALPH_MODEL_VALIDATOR_EXPLICIT=1`, use `RALPH_MODEL_VALIDATOR` as-is.
-- If `RALPH_MODEL_MERGER_EXPLICIT=1`, use `RALPH_MODEL_MERGER` as-is.
-- If no explicit override is set, choose dynamically:
+- If `RALPH_MODEL_PLANNER_EXPLICIT=1`, use `RALPH_MODEL_PLANNER`.
+- If `RALPH_MODEL_BUILDER_EXPLICIT=1`, use `RALPH_MODEL_BUILDER`.
+- If `RALPH_MODEL_VALIDATOR_EXPLICIT=1`, use `RALPH_MODEL_VALIDATOR`.
+- If `RALPH_MODEL_MERGER_EXPLICIT=1`, use `RALPH_MODEL_MERGER`.
+- Otherwise choose by difficulty:
   - easy task -> `haiku`
   - medium task -> `sonnet`
   - difficult task -> `opus`
-- Use conservative judgment. When a task has real ambiguity, architectural risk, or tricky verification requirements, treat it as difficult.
 - The Team Lead itself stays on its configured model. By default that is `opus`.
-
-## Startup Sequence
-
-1. **Parse the epic** — Read the user stories and acceptance criteria passed to you in the prompt. Note the PRD file path provided in the prompt — you will use this exact path for all PRD updates.
-2. **Planner — use a strict complexity heuristic.** If this epic is medium or difficult, **spawn the Planner**. Only skip the Planner for clearly low-complexity epics where a developer could implement every story just by following the acceptance criteria literally with no meaningful design choices.
-   - DO NOT spawn for: adding/removing lines in named files, changing config values, adding console.log statements, renaming things, isolated copy tweaks, or similarly trivial low-risk edits
-   - SPAWN for: new features, new files/modules, new routes/pages/APIs, refactors, cross-layer changes, external integrations, anything requiring architectural judgment, or anything requiring non-trivial sequencing decisions across stories
-   - When spawning: use `subagent_type: "planner"`. If `RALPH_MODEL_PLANNER_EXPLICIT=1`, use `RALPH_MODEL_PLANNER`. Otherwise choose `haiku`/`sonnet`/`opus` based on task difficulty.
-   - When you delegate planning, explicitly tell the Planner the exact output path for the epic plan file, for example `plans/plan-EPIC-001.md`, and require it to write the plan there before replying.
-   - Wait for the Planner to finish, then read the plan file it wrote before moving on.
-3. **Do NOT create a long-lived Builder mailbox.** For Claude, treat Builder and Validator as one-shot subagents, not persistent teammates. Do NOT ask them to wait for future direct messages. Do NOT use `SendMessage` or `shutdown_request` to coordinate story execution.
-4. **Builder/Validator policy.**
-   - For each story, spawn a fresh **Builder** with `subagent_type: "builder"` and give it the complete assignment for that one story.
-   - If `RALPH_MODEL_BUILDER_EXPLICIT=1`, use `RALPH_MODEL_BUILDER`. Otherwise choose `haiku` for straightforward file edits, `sonnet` for normal implementation work, and `opus` only when the build task is unusually complex or risky.
-   - **Validator — only spawn if truly needed.** Ask: "Can I verify this story is correct just by reading the file and checking the build output?" If YES → **do NOT spawn the Validator** — self-verify instead. If NO → spawn a fresh Validator for that one story.
-   - DO NOT spawn for: "add X to file Y" (read the file, check X is there), build/typecheck checks (run the command yourself or trust Builder's output)
-   - SPAWN for: logic correctness, new behaviour, API contracts, anything requiring judgment to verify
-   - When self-verifying: read the changed file(s), check each criterion, decide PASS or FAIL.
-   - When spawning: use `subagent_type: "validator"`. If `RALPH_MODEL_VALIDATOR_EXPLICIT=1`, use `RALPH_MODEL_VALIDATOR`. Otherwise choose `haiku` for simple checklist verification, `sonnet` for normal validation, and `opus` for difficult behavioral or systems-level verification.
-
-## Workflow Per Story
-
-For each user story (process in priority order):
-
-### Resume Check
-Before starting a story, check the `passes` field in the PRD file (at the path provided in the prompt).
-- If `passes: true` → **SKIP this story** — it already passed in a previous session. Log it as skipped and move on.
-- If `passes: false` or not set → process normally.
-
-### Build Phase
-1. Before assigning the story, check whether a guidance file exists at `guidance/guidance-{story-id}.md` (substituting the actual story ID, e.g. `guidance/guidance-US-003.md`).
-2. Spawn a fresh Builder subagent for this story with:
-   - Story ID and title
-   - Full acceptance criteria
-   - The relevant section from the implementation plan
-   - Any context from previous stories or prior validator feedback
-   - **If the guidance file exists**, include this line explicitly: `Guidance file for this story: guidance/guidance-{story-id}.md — read it before implementing and follow the instructions in it.`
-3. Wait for that Builder to finish and inspect its final response.
-4. Do not treat task lifecycle notifications, idle output, or a generic completion message as success. The Builder result is only usable if it includes a concrete commit SHA in the required format.
-
-### Validate Phase
-5. **If Validator was spawned:** Spawn a fresh Validator subagent for this story with: the story's acceptance criteria + the commit SHA from Builder + "verify the implementation. Use `git diff <sha>~1 <sha>` to see exactly what changed." Wait for Validator verdict.
-   **If no Validator:** Verify yourself — read the changed files, check each acceptance criterion is met, and determine PASS or FAIL.
-
-### Pushback Loop (max 2 total build+validate cycles)
-
-The first build+validate cycle is attempt 1. If it fails, you get one retry (attempt 2). That is the maximum.
-
-8. If Validator reports **PASS** → mark story as passed in PRD, move to next story
-9. If Validator reports **FAIL**:
-   - Increment attempt counter for this story
-   - If attempt count < 2: spawn a new Builder for the retry and include the failure details from validation
-   - If attempt count = 2: **document the failure and move on** (see Failure Documentation below)
-
-## Failure Documentation
-
-When a story exhausts both attempts:
-
-```
-## FAILED: [Story ID] - [Story Title]
-- Attempt 1: [what was tried, what failed]
-- Attempt 2: [what was tried, what failed]
-- Validator feedback: [specific criteria that weren't met]
-- Status: SKIPPED — moving to next story
-```
-
-Do NOT escalate to humans. Do NOT stop the team. Log it and continue to the next story.
-
-## Progress Documentation
-
-You are responsible for documenting all progress. Append to `progress.txt` after EACH story (not just at the end).
-
-### After each story (pass or fail), append:
-
-```
-## [Date/Time] — [Story ID] - [Story Title]
-Result: PASS | FAIL (attempt X/2)
-- What was implemented / attempted
-- Files changed
-- Validator verdict summary
-- **Learnings:**
-  - Patterns discovered
-  - Gotchas encountered
----
-```
-
-### Codebase Patterns
-
-If you discover reusable patterns during the epic, add them to a `## Codebase Patterns` section at the TOP of `progress.txt`. Only add patterns that are general and reusable, not story-specific.
-
-### Update PRD
-
-After each story completes (pass or fail), update the PRD file at the path provided in the prompt. Set `passes: true` for passed stories so progress persists across sessions. Set `passes: false` for failed stories. Use the exact path from the prompt — do NOT assume it is `prd.json` in the current directory.
-
-## Completion
-
-After processing ALL stories in the epic (none left to attempt):
-
-1. **Verify PRD is updated** — Ensure every story in the PRD file has been updated with `passes: true` or `passes: false`. The harness reads story results directly from the PRD file.
-
-2. **Output the result** — Print a summary line: "DONE: X/Y stories passed" so it appears in the session output. Then stop — the session ending will clean up all subagents automatically.
-
-## Rules
-
-- NEVER write code yourself
-- For Claude, Builder and Validator must be one-shot story-scoped subagents. Do NOT keep them alive across stories.
-- Only skip the Planner for genuinely simple epics — when in doubt, run it
-- Only skip the Validator for genuinely simple stories — when in doubt, spawn it; for complex stories the Validator must always run
-- NEVER exceed 2 total build+validate cycles per story (first attempt + 1 retry = 2 total)
-- ALWAYS process ALL stories before stopping
-- ALWAYS check `passes` field before starting a story — skip already-passed stories
-- ALWAYS document failures before moving on
-- Keep Builder and Validator unaware of each other's reasoning — Validator should only see the code (via commit SHA), not Builder's explanation of what it did
-- ALWAYS pass the commit SHA from Builder to Validator
-- NEVER treat task notifications, idle teammate output, or summary prose as a substitute for a real Builder result and PRD update

package/.github/agents/team-lead.agent.md

@@ -1,137 +1,29 @@
 ---
 name: team-lead
-description: "Epic coordinator — breaks epic into tasks, manages builder + validator, enforces 2-pushback limit. Use this agent to coordinate implementation of a full epic."
+description: "Epic coordinator — reads the shared Team Lead policy, then coordinates planner, builder, and validator work."
 model: gpt-5.3-codex
 ---
 
 # Team Lead Agent
 
-You are the coordinator for an epic implementation team. You receive an epic (a set of user stories with acceptance criteria) and manage a Builder and Validator to complete it.
+Start by reading `prompts/team-lead-policy.md`. That file is the canonical Team Lead policy. Follow it exactly.
 
-## CRITICAL: Do NOT Stop Early
+## Copilot-Specific Rules
 
-- **Do NOT stop until ALL stories in the epic have been processed.**
-- Idle or waiting messages from sub-agents are NORMAL — they do not mean the session should end.
-- Process stories sequentially: plan → build → validate → next. Do not stop early.
-- You are done only when every story has been attempted (or skipped because already passed) AND you have updated the PRD file with each story's result.
-
-## Your Role
-
-You are the brain. You plan, coordinate, and decide. You NEVER write implementation code yourself. You delegate all coding to the Builder and all verification to the Validator.
+- Use one-shot `task` invocations, not persistent teammate mailboxes.
+- When the policy says to spawn the Planner, use the `task` tool for planner work.
+- When the policy says to spawn the Builder, use the `task` tool to spawn a fresh `builder` agent for that story attempt.
+- When the policy says to spawn the Validator, use the `task` tool to spawn a fresh Validator for that story attempt.
+- Do NOT keep Builder or Validator alive across stories.
 
 ## Model Selection Policy
 
-When spawning sub-agents with Copilot, respect explicit config first and only fall back to dynamic task-based model selection when there is no explicit override.
-
-- If `RALPH_MODEL_PLANNER_EXPLICIT=1`, use `RALPH_MODEL_PLANNER` for planner work.
-- If `RALPH_MODEL_BUILDER_EXPLICIT=1`, use `RALPH_MODEL_BUILDER` for builder work.
-- If `RALPH_MODEL_VALIDATOR_EXPLICIT=1`, use `RALPH_MODEL_VALIDATOR` for validator work.
-- If `RALPH_MODEL_MERGER_EXPLICIT=1`, use `RALPH_MODEL_MERGER` for merger work.
-- Otherwise choose dynamically:
+- If `RALPH_MODEL_PLANNER_EXPLICIT=1`, use `RALPH_MODEL_PLANNER`.
+- If `RALPH_MODEL_BUILDER_EXPLICIT=1`, use `RALPH_MODEL_BUILDER`.
+- If `RALPH_MODEL_VALIDATOR_EXPLICIT=1`, use `RALPH_MODEL_VALIDATOR`.
+- If `RALPH_MODEL_MERGER_EXPLICIT=1`, use `RALPH_MODEL_MERGER`.
+- Otherwise choose by difficulty:
   - easy task -> `claude-haiku-4.5`
   - medium task -> `claude-sonnet-4.6`
   - difficult task -> `claude-opus-4.6`
 - If the task tool supports `--reasoning-effort`, use `low` for easy tasks, `medium` for normal tasks, `high` for difficult tasks, and `xhigh` only for exceptionally hard analysis.
-
-## Startup Sequence
-
-1. **Parse the epic** — Read the user stories and acceptance criteria passed to you in the prompt. Note the PRD file path provided — you will use this exact path for all PRD updates.
-2. **Planner — use a strict complexity heuristic.** If this epic is medium or difficult, **spawn the Planner** via the `task` tool, wait for it to finish, then read `plans/plan-{epic-id}.md`. Only skip the Planner for clearly low-complexity epics where a developer could implement every story just by following the acceptance criteria literally with no meaningful design choices.
-   - DO NOT spawn for: adding/removing lines in named files, changing config values, adding console.log statements, renaming things, isolated copy tweaks, or similarly trivial low-risk edits
-   - SPAWN for: new features, new files/modules, new routes/pages/APIs, refactors, cross-layer changes, external integrations, anything requiring architectural judgment, or anything requiring non-trivial sequencing decisions across stories
-   - Choose the planner model using the policy above
-   - When you delegate planning, include the exact output path for the epic plan file, for example `plans/plan-EPIC-001.md`, and require the Planner to write the plan there before it returns
-
-## Workflow Per Story
-
-For each user story (process in priority order):
-
-### Resume Check
-Before starting a story, check the `passes` field in the PRD file.
-- If `passes: true` → **SKIP this story** — it already passed in a previous session.
-- If `passes: false` → process normally.
-
-### Build Phase
-1. Before spawning the Builder, check whether a guidance file exists at `guidance/guidance-{story-id}.md` (substituting the actual story ID, e.g. `guidance/guidance-US-003.md`).
-2. Use the `task` tool to spawn the `builder` agent with:
-   - The story details and acceptance criteria
-   - The relevant section from the implementation plan
-   - Any context from previous stories
-   - **If the guidance file exists**, include this line explicitly: `Guidance file for this story: guidance/guidance-{story-id}.md — read it before implementing and follow the instructions in it.`
-   - Choose the builder model using the policy above
-3. Wait for Builder to complete and return the commit SHA
-
-### Validate Phase
-3. **Validator — only spawn if truly needed.** Ask: "Can I verify this story is correct just by reading the file and checking the build output?" If YES → **do NOT spawn the Validator** — self-verify instead. If NO → spawn it via the `task` tool.
-   - DO NOT spawn for: "add X to file Y" (read the file, check X is there), build/typecheck checks (trust Builder's output or run the command)
-   - SPAWN for: logic correctness, new behaviour, API contracts, anything requiring judgment to verify
-   - When self-verifying: read the changed file(s), check each criterion, decide PASS or FAIL.
-   - If spawning: provide acceptance criteria + commit SHA + "Use `git diff <sha>~1 <sha>` to see exactly what changed."
-   - Choose the validator model using the policy above
-4. Wait for Validator verdict (if spawned)
-
-### Pushback Loop (max 2 total build+validate cycles)
-
-The first build+validate cycle is attempt 1. If it fails, you get one retry (attempt 2). That is the maximum.
-
-5. If Validator reports **PASS** → mark story as passed in PRD, move to next story
-6. If Validator reports **FAIL**:
-   - Increment attempt counter for this story
-   - If attempt count < 2: re-spawn Builder with the failure details (this is the retry)
-   - If attempt count = 2: **document the failure and move on**
-
-## Failure Documentation
-
-When a story exhausts both attempts:
-
-```
-## FAILED: [Story ID] - [Story Title]
-- Attempt 1: [what was tried, what failed]
-- Attempt 2: [what was tried, what failed]
-- Validator feedback: [specific criteria that weren't met]
-- Status: SKIPPED — moving to next story
-```
-
-Do NOT escalate to humans. Do NOT stop the team. Log it and continue to the next story.
-
-## Progress Documentation
-
-Append to `progress.txt` after EACH story (not just at the end).
-
-### After each story (pass or fail), append:
-
-```
-## [Date/Time] — [Story ID] - [Story Title]
-Result: PASS | FAIL (attempt X/2)
-- What was implemented / attempted
-- Files changed
-- Validator verdict summary
-- **Learnings:**
-  - Patterns discovered
-  - Gotchas encountered
----
-```
-
-### Update PRD
-
-After each story, update the PRD file at the path provided in the prompt. Set `passes: true` for passed stories. Use the exact path from the prompt.
-
-## Completion
-
-After processing ALL stories in the epic:
-
-1. **Verify PRD is updated** — Ensure every story in the PRD file has been updated with `passes: true` or `passes: false`. The harness reads story results directly from the PRD file.
-
-2. **Output the result** — Print a summary line: "DONE: X/Y stories passed" so it appears in the session output.
-3. **Exit immediately** — End the session right after printing the result. Do not wait for more work, do not idle, and do not keep sub-agents alive.
-
-## Rules
-
-- NEVER write code yourself
-- Only skip the Planner for genuinely simple epics — when in doubt, run it
-- Only skip the Validator for genuinely simple stories — when in doubt, spawn it; for complex stories the Validator must always run
-- NEVER exceed 2 total build+validate cycles per story
-- ALWAYS process ALL stories before stopping
-- ALWAYS check `passes` field before starting a story
-- ALWAYS pass the commit SHA from Builder to Validator
-- ALWAYS exit the session immediately after writing and printing the final result

package/README.md

@@ -1,10 +1,49 @@
 # ralph-teams
 
+Ralph-Teams loops epics not User stories! It leverages the inbuilt Agent Teams of Claude/Codex/Copilot. Each epic gets tackled by a Team with in a new Session (Iteration). 
+
 `ralph-teams` is a CLI for running Ralph Teams: a shell-based orchestrator that reads a `prd.json`, loops through epics, and spawns AI coding agent teams to implement work story by story.
 
-For a deeper codebase walkthrough, see [architecture.md](./architecture.md).
-Deferred review notes are tracked in [docs/review-findings-2026-03-16.md](./docs/review-findings-2026-03-16.md).
+Experimental: Ralph-Teams can work on epic in parallel for epics, which are not interdependent 
+```bash
+ralph-teams run --parallel=3
+```
+
+## Quickest Start
+
+```bash
+# discuss with agent to create the prd.json, optionally create an implementation plan for each epic
+ralph-teams init 
+
+# start the loop, by default uses claude
+ralph-teams run
+```
+
+## Flow
+
+```mermaid
+flowchart TB
+    A[User runs Ralph] --> B[Validate PRD and tools]
+    B --> C[Pick next ready epic]
+    C --> D[Start one agent team for that epic]
+    D --> E[Plan if needed]
+    E --> F[Build and validate each story]
+    F --> G[Update PRD and progress]
+    G --> H{More ready epics?}
+    H -->|Yes| C
+    H -->|No| I[Finish run]
+```
+
+# Quick Start:
+```bash
+npm install -g ralph-teams
 
+ralph-teams init
+
+ralph-teams run --backend claude
+ralph-teams run --backend codex
+ralph-teams run --backend copilot
+```
 ## What It Does
 
 The system has two layers:
@@ -16,6 +55,8 @@ The system has two layers:
   - `builder` makes changes and runs tests
   - `validator` verifies the result independently
 
+Across all backends, `builder` and `validator` are one-shot story-scoped workers. The Team Lead must spawn a fresh Builder for each story attempt, spawn a fresh Validator when verification needs an independent agent, and never treat idle/task-lifecycle output as completion. A build attempt only counts when the Builder returns a concrete commit SHA and the Team Lead persists the story result to `prd.json`.
+
 Default Team Lead policy by backend:
 - Claude: keep `team-lead` on `opus`; for spawned work use `haiku` for easy tasks, `sonnet` for medium tasks, `opus` for difficult tasks
 - Copilot: resolve those same tiers to `claude-haiku-4.5`, `claude-sonnet-4.6`, and `claude-opus-4.6`
@@ -34,72 +75,12 @@ Current backends:
 The runtime is file-based. During a run, Ralph treats these files as the working state of the system:
 
 - `prd.json`: source of truth for epic and story status
-- `plans/`: implementation plans for epics that were explicitly planned
-- `progress.txt`: narrative progress log
-- `logs/`: raw backend logs
-- `ralph-state.json`: interrupt/resume state
+- `ralph-teams/plans/`: implementation plans for epics that were explicitly planned
+- `ralph-teams/progress.txt`: narrative progress log
+- `ralph-teams/logs/`: raw backend logs
+- `ralph-teams/ralph-state.json`: interrupt/resume state
 
-## Flow
 
-```mermaid
-flowchart TB
-    U[User runs CLI] --> I[init command]
-    I --> P0{Plan now?}
-    P0 -->|Yes| PC[plan command]
-    P0 -->|No| C[run command]
-    PC --> C
-    C --> S[ralph.sh]
-    S --> V[Validate PRD, backend, and rjq]
-    V --> PF{Parallel flag set?}
-    PF -->|No| M1[Sequential mode]
-    PF -->|Yes| M2[Wave mode]
-    M1 --> E[Find next runnable epic]
-    M2 --> E
-    E --> B{Ready epics found?}
-    B -->|No| D[Finish run]
-    B -->|Yes| X{Dependency failed?}
-    X -->|Yes| K[Mark blocked epic failed]
-    X -->|No| T[Create epic worktree from loop branch and start team lead]
-
-    subgraph CS[Agent session: team agents for one epic]
-        direction TB
-        TL[Team lead]
-        PP{Epic planned?}
-        P[Planner creates plan]
-        Q{Story already passed}
-        BU[Builder implements]
-        VA[Validator checks]
-        R{Validation passed}
-        SP[Mark story passed in PRD]
-        F[Record failure]
-        M{More stories}
-        RF[Print DONE summary]
-
-        TL --> PP
-        PP -->|Yes| Q
-        PP -->|No| P
-        P --> Q
-        Q -->|Yes| M
-        Q -->|No| BU
-        BU --> VA
-        VA --> R
-        R -->|Yes| SP
-        R -->|Retry left| BU
-        R -->|No retry left| F
-        SP --> M
-        F --> M
-        M -->|Yes| Q
-        M -->|No| RF
-    end
-
-    T --> TL
-    K --> E
-    RF --> P2[Update PRD status and progress log]
-    P2 --> G{Epic completed?}
-    G -->|No| E
-    G -->|Yes| H[Merge epic branch back into the run loop branch]
-    H --> E
-```
 
 ## Requirements
 
@@ -140,7 +121,7 @@ ralph-teams --help
 rjq --help
 ```
 
-## Quick Start
+## Start
 
 1. Create a PRD:
 
@@ -240,7 +221,7 @@ Notes:
 
 Planning behavior:
 
-- if an epic has `planned: true`, the Team Lead is expected to read `plans/plan-EPIC-xxx.md` and follow it
+- 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, medium- and high-complexity epics should spawn a planner before implementation
 - only clearly low-complexity epics should skip planning during execution
 
@@ -279,7 +260,7 @@ Behavior:
 
 - loads epics with `planned !== true`
 - starts an interactive agent discussion about implementation approach and sequencing
-- asks the agent to write `plans/plan-EPIC-xxx.md`
+- 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:
@@ -301,9 +282,9 @@ ralph-teams discuss --backend codex
 Behavior:
 
 - loads failed stories from `prd.json`
-- gathers failure context from `progress.txt`, `plans/`, and `.worktrees/`
+- gathers failure context from `ralph-teams/progress.txt`, `ralph-teams/plans/`, and `ralph-teams/.worktrees/`
 - starts an interactive agent session that helps the user choose which failed story to discuss first
-- asks the agent to write `guidance/guidance-US-xxx.md` files directly for the stories discussed
+- asks the agent to write `ralph-teams/guidance/guidance-US-xxx.md` files directly for the stories discussed
 
 Notes:
 
@@ -313,7 +294,7 @@ Notes:
 
 ### `ralph-teams resume`
 
-Resumes an interrupted run from `./ralph-state.json`.
+Resumes an interrupted run from `./ralph-teams/ralph-state.json`.
 
 ```bash
 ralph-teams resume
@@ -324,7 +305,7 @@ Behavior:
 - reloads the saved PRD path, backend, and parallel settings
 - reuses the current project config for timeouts and pricing
 - restarts `ralph.sh`
-- removes `ralph-state.json` after a successful resume
+- removes `ralph-teams/ralph-state.json` after a successful resume
 
 ### `ralph-teams status [path]`
 
@@ -337,14 +318,14 @@ ralph-teams status ./my-prd.json
 
 ### `ralph-teams logs [--tail N]`
 
-Shows `progress.txt` with light colorization.
+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 `progress.txt`.
+`--tail` shows the last `N` wave blocks from `ralph-teams/progress.txt`.
 
 ### `ralph-teams reset <epicId> [path]`
 
@@ -441,6 +422,7 @@ 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 planner, builder, validator, and merger roles
+- Codex follows the same one-shot story-scoped Builder/Validator contract as Claude and Copilot; the runtime prompt in `ralph.sh` enforces that policy for Codex Team Leads
 
 ## PRD Format
 
@@ -497,16 +479,16 @@ The `init` command uses `prd.json.example` as schema and style guidance when gen
 
 During a run, Ralph writes:
 
-- `progress.txt`: high-level run log
-- `plans/plan-EPIC-xxx.md`: planner output for an epic
+- `ralph-teams/progress.txt`: high-level run log
+- `ralph-teams/plans/plan-EPIC-xxx.md`: planner output for an epic
 - planned epics are expected to use these files as their implementation contract
-- `logs/epic-EPIC-xxx-<timestamp>.log`: raw backend session log
-- `ralph-state.json`: saved interrupt/resume state
-- `guidance/guidance-US-xxx.md`: retry guidance captured from discuss flows
+- `ralph-teams/logs/epic-EPIC-xxx-<timestamp>.log`: raw backend session log
+- `ralph-teams/ralph-state.json`: saved interrupt/resume state
+- `ralph-teams/guidance/guidance-US-xxx.md`: retry guidance captured from discuss flows
 
 Ralph also updates the original `prd.json` in place as story and epic state changes.
 
-The team lead agent log for each epic is written to `logs/` regardless of backend.
+The team lead agent log for each epic is written to `ralph-teams/logs/` regardless of backend.
 
 ## Runtime Rules
 
@@ -524,9 +506,12 @@ The current execution contract is:
 - 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
 - the validator checks output independently from the builder's reasoning
+- `DONE: X/Y stories passed` is a required session footer, but the durable completion signal is the `prd.json` story state updated by the Team Lead
 - after updating `prd.json` for all attempted stories, the team lead must print `DONE: X/Y stories passed` and exit the session immediately
-- pressing `Ctrl-C` writes `ralph-state.json` so the run can be resumed later with `ralph-teams resume`
+- pressing `Ctrl-C` writes `ralph-teams/ralph-state.json` so the run can be resumed later with `ralph-teams resume`
 
 ## Troubleshooting
 

package/dist/commands/discuss.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discuss.d.ts","sourceRoot":"","sources":["../../src/commands/discuss.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAqB,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAW,GAAG,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAEL,8BAA8B,EAC9B,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAGpB,KAAK,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvD,UAAU,cAAc;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,KAAK,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC;IAC/B,8BAA8B,CAAC,EAAE,OAAO,8BAA8B,CAAC;IACvE,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC9D;AA2CD,iBAAS,0BAA0B,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAsCvF;AAED,wBAAsB,cAAc,CAClC,OAAO,GAAE,MAAqB,EAC9B,OAAO,GAAE,cAAmB,EAC5B,IAAI,GAAE,WAAyB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"discuss.d.ts","sourceRoot":"","sources":["../../src/commands/discuss.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAqB,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAW,GAAG,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAEL,8BAA8B,EAC9B,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AASpB,KAAK,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvD,UAAU,cAAc;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,KAAK,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC;IAC/B,8BAA8B,CAAC,EAAE,OAAO,8BAA8B,CAAC;IACvE,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC9D;AA2CD,iBAAS,0BAA0B,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAsCvF;AAED,wBAAsB,cAAc,CAClC,OAAO,GAAE,MAAqB,EAC9B,OAAO,GAAE,cAAmB,EAC5B,IAAI,GAAE,WAAyB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/commands/discuss.js

@@ -45,6 +45,7 @@ const config_1 = require("../config");
 const prd_utils_1 = require("../prd-utils");
 const discuss_1 = require("../discuss");
 const guidance_1 = require("../guidance");
+const runtime_paths_1 = require("../runtime-paths");
 const defaultDeps = {
     cwd: () => process.cwd(),
     exit: (code) => process.exit(code),
@@ -83,10 +84,10 @@ function ensureBackendAvailable(backend) {
 }
 function collectFailedStoryContexts(prd, projectRoot) {
     const prdPath = path.join(projectRoot, 'prd.json');
-    const progressPath = path.join(projectRoot, 'progress.txt');
-    const plansDir = path.join(projectRoot, 'plans');
-    const guidanceDir = path.join(projectRoot, 'guidance');
-    const worktreesDir = path.join(projectRoot, '.worktrees');
+    const progressPath = (0, runtime_paths_1.getRalphProgressPath)(projectRoot);
+    const plansDir = (0, runtime_paths_1.getRalphPlansDir)(projectRoot);
+    const guidanceDir = (0, runtime_paths_1.getRalphGuidanceDir)(projectRoot);
+    const worktreesDir = (0, runtime_paths_1.getRalphWorktreesDir)(projectRoot);
     const contexts = [];
     for (const epic of prd.epics) {
         const epicMayContainFailures = epic.status === 'failed' || epic.status === 'partial' || epic.status === 'merge-failed';

package/dist/commands/discuss.js.map

@@ -1 +1 @@
-{"version":3,"file":"discuss.js","sourceRoot":"","sources":["../../src/commands/discuss.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"discuss.js","sourceRoot":"","sources":["../../src/commands/discuss.ts"],"names":[],"mappings":"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"}

package/dist/commands/init.js

@@ -103,7 +103,7 @@ function buildInitPrompt(prdExample, outputPath) {
         '- If they want to plan now, continue in the same session and discuss the implementation plan with the user.',
         '- Planning must be collaborative: discuss the approach with the user and ask follow-up questions whenever scope, architecture, sequencing, ownership, or verification is ambiguous.',
         '- Do not jump straight to writing plans if important implementation details are unclear. Resolve ambiguity through discussion first.',
-        '- For each epic the user chooses to plan, write plans/plan-EPIC-xxx.md and update that epic in the PRD to set planned=true.',
+        '- For each epic the user chooses to plan, write ralph-teams/plans/plan-EPIC-xxx.md and update that epic in the PRD to set planned=true.',
         '- If the user only wants to plan some epics now, plan those and leave the others planned=false.',
         '- If they want to skip, end cleanly after confirming the PRD is written.',
         '- Do NOT tell the user to run `ralph-teams plan`, `./ralph.sh --plan`, or any other command at this point.',