ralph-teams 1.0.0 → 1.0.2

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

@@ -44,10 +44,11 @@ For Claude subagents, choose the model based on task difficulty unless the envir
    - 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. **Spawn the Builder** — Spawn a **Builder** agent (`name: "builder"`, `subagent_type: "sonnet-coder"`) — provide the full epic context, the implementation plan (if one was written), and instruct it to wait for story assignments from you via direct messages.
-   - 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.
-4. **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.
+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.
@@ -64,16 +65,17 @@ Before starting a story, check the `passes` field in the PRD file (at the path p
 
 ### 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. Send Builder a direct message with:
+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 Builder to complete and message back with the commit SHA
+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
-4. **If Validator was spawned:** Send Validator a direct message 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.
+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)
@@ -83,7 +85,7 @@ The first build+validate cycle is attempt 1. If it fails, you get one retry (att
 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: send Builder the failure details, reassign the story task (this is the retry)
+   - 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
@@ -137,6 +139,7 @@ After processing ALL stories in the epic (none left to attempt):
 ## 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)
@@ -145,3 +148,4 @@ After processing ALL stories in the epic (none left to attempt):
 - 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/README.md

@@ -37,7 +37,6 @@ The runtime is file-based. During a run, Ralph treats these files as the working
 - `plans/`: implementation plans for epics that were explicitly planned
 - `progress.txt`: narrative progress log
 - `logs/`: raw backend logs
-- `results/`: per-epic final result markers
 - `ralph-state.json`: interrupt/resume state
 
 ## Flow
@@ -74,7 +73,7 @@ flowchart TB
         SP[Mark story passed in PRD]
         F[Record failure]
         M{More stories}
-        RF[Write result file]
+        RF[Print DONE summary]
 
         TL --> PP
         PP -->|Yes| Q
@@ -440,7 +439,7 @@ Example:
 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 and result files
+- 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
 
 ## PRD Format
@@ -501,7 +500,6 @@ During a run, Ralph writes:
 - `progress.txt`: high-level run log
 - `plans/plan-EPIC-xxx.md`: planner output for an epic
 - planned epics are expected to use these files as their implementation contract
-- `results/result-EPIC-xxx.txt`: final pass/partial/fail result per epic
 - `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
@@ -527,7 +525,7 @@ The current execution contract is:
 - 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
 - the validator checks output independently from the builder's reasoning
-- after writing `results/result-EPIC-xxx.txt`, the team lead must print the same result and exit the session immediately
+- 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`
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-teams",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI tool for Ralph Teams",
   "bin": {
     "ralph-teams": "dist/index.js",

package/ralph.sh

@@ -871,10 +871,8 @@ spawn_epic_bg() {
   PENDING_STORIES_JSON=$(rjq read "$PRD_FILE" ".epics[$EPIC_INDEX].userStories" | \
     node -e 'const fs=require("fs"); const stories=JSON.parse(fs.readFileSync(0,"utf8")); process.stdout.write(JSON.stringify(stories.filter(s => s.passes !== true)));')
 
-  local RESULT_FILE="${ROOT_DIR}/results/result-${EPIC_ID}.txt"
   local EPIC_LOG="${ROOT_DIR}/logs/epic-${EPIC_ID}-$(date +%s).log"
-  mkdir -p "${ROOT_DIR}/results" "${ROOT_DIR}/logs"
-  rm -f "$RESULT_FILE"
+  mkdir -p "${ROOT_DIR}/logs"
 
   # Create isolated worktree for this epic
   local WORKTREE_PATH
@@ -950,7 +948,7 @@ $PENDING_STORIES_JSON
 ## Critical Rules
 - Do NOT stop after the first story — process ALL stories before exiting
 - Idle or waiting messages from teammates are NORMAL — they do not mean the session should end
-- Once the final result is written, end the session immediately. Do not wait for more input.
+- Once the final PRD updates are complete and you have printed the DONE summary, end the session immediately. Do not wait for more input.
 - Process stories sequentially: build → validate → next. Do not stop early.
 - After each story result (pass or fail), update $PRD_ABS_PATH to keep both passes and failureReason accurate for that story
 
@@ -1220,7 +1218,6 @@ while true; do
       for slot in "${!active_pids[@]}"; do
         local finished_epic_id
         finished_epic_id=$(rjq read "$PRD_FILE" ".epics[${active_indices[$slot]}].id")
-        local result_file="${ROOT_DIR}/results/result-${finished_epic_id}.txt"
         local process_finished=false
 
         emit_new_log_output "$finished_epic_id" "${active_logs[$slot]}" "${active_log_lines[$slot]:-0}"
@@ -1326,22 +1323,23 @@ while true; do
           process_finished=true
         fi
 
-        if [ "$process_finished" = true ] || [ -f "$result_file" ]; then
-          # If the result file exists, the epic is complete even if the backend
-          # session is still idling. Terminate the lingering job and advance.
+        local total_s passed_s
+        total_s=$(rjq length "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories")
+        passed_s=$(rjq count-where "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories" "passes=true")
+        local all_done=false
+        [ "$passed_s" -eq "$total_s" ] && [ "$total_s" -gt 0 ] && all_done=true
+
+        if [ "$process_finished" = true ] || [ "$all_done" = true ]; then
+          # Treat fully-passed stories in the PRD as the authoritative completion
+          # signal, even if the backend session is still idling.
           if [ "$process_finished" = false ]; then
             terminate_process_tree "${active_pids[$slot]}"
           fi
           wait "${active_pids[$slot]}" 2>/dev/null || true
 
-          # Check if this was a crash (process exited, no result file, not all stories done)
-          local total_s passed_s
-          total_s=$(rjq length "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories")
-          passed_s=$(rjq count-where "$PRD_FILE" ".epics[${active_indices[$slot]}].userStories" "passes=true")
-          local all_done=false
-          [ "$passed_s" -eq "$total_s" ] && [ "$total_s" -gt 0 ] && all_done=true
-
-          if [ ! -f "$result_file" ] && [ "$all_done" = false ]; then
+          # If the process exited before the epic reached all stories passed,
+          # consider it a crash and retry when possible.
+          if [ "$all_done" = false ]; then
             local retry_count
             retry_count="$(get_crash_retry_count "$finished_epic_id")"
             if [ "$retry_count" -lt "$MAX_CRASH_RETRIES" ]; then