ralph-teams 1.0.2 → 1.0.3

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

@@ -41,6 +41,7 @@ When spawning sub-agents with Copilot, respect explicit config first and only fa
    - 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
+3. **Do NOT create a long-lived Builder or Validator mailbox.** For Copilot, Builder and Validator must be one-shot `task` invocations scoped to a single story attempt. Do NOT ask them to wait for future instructions across stories.
 
 ## Workflow Per Story
 
@@ -53,22 +54,23 @@ Before starting a story, check the `passes` field in the PRD file.
 
 ### 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:
+2. Use the `task` tool to spawn a fresh `builder` agent for this one story attempt 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
+3. Wait for Builder to complete and inspect its final output.
+4. Do NOT treat task lifecycle notifications, waiting messages, or generic completion prose as success. A Builder result only counts if it includes a concrete commit SHA in the expected format.
 
 ### 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.
+5. **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 via the `task` tool for this one story attempt.
    - 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)
+6. Wait for Validator verdict (if spawned)
 
 ### Pushback Loop (max 2 total build+validate cycles)
 
@@ -77,7 +79,7 @@ The first build+validate cycle is attempt 1. If it fails, you get one retry (att
 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: spawn a new Builder for the retry and include the failure details
    - If attempt count = 2: **document the failure and move on**
 
 ## Failure Documentation
@@ -128,6 +130,7 @@ After processing ALL stories in the epic:
 ## Rules
 
 - NEVER write code yourself
+- Builder and Validator must be one-shot story-scoped tasks. 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
@@ -135,3 +138,4 @@ After processing ALL stories in the epic:
 - 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
+- NEVER treat task notifications, idle teammate output, or summary prose as a substitute for a real Builder result and PRD update

package/package.json

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

package/ralph.sh

@@ -930,20 +930,23 @@ $PENDING_STORIES_JSON
    - DO NOT spawn for: adding/removing lines in named files, adding console.log statements, changing config values, renaming things, isolated copy tweaks, or similarly trivial low-risk edits
    - When you do spawn the Planner, explicitly tell it to write the plan to $ROOT_DIR/plans/plan-${EPIC_ID}.md, and wait for that file.
    - If your agent runtime supports named sub-agents, use the dedicated planner role for this and choose its model using the policy above
-2. Process ALL user stories in priority order — do NOT stop until every story has been attempted
-3. For each story: check if passes=true in the PRD (skip those — they are already done), then Builder implements → verify → max 2 total cycles
-   - If your agent runtime supports named sub-agents, use the dedicated builder role for implementation and choose its model using the policy above
+2. Do NOT create long-lived Builder or Validator mailboxes. Builder and Validator must be one-shot story-scoped teammate runs. Do NOT ask them to wait for future instructions across stories.
+3. Process ALL user stories in priority order — do NOT stop until every story has been attempted
+4. For each story: check if passes=true in the PRD (skip those — they are already done), then Builder implements → verify → max 2 total cycles
+   - Spawn a fresh Builder for each story attempt. If your agent runtime supports named sub-agents, use the dedicated builder role for implementation and choose its model using the policy above
    - Before assigning each story, check if guidance/guidance-{story-id}.md exists (e.g. guidance/guidance-US-003.md). If it does, explicitly include this in your Builder assignment: Guidance file for this story: guidance/guidance-{story-id}.md — read it before implementing and follow the instructions in it.
+   - Do NOT treat task lifecycle notifications, idle output, or generic completion summaries as success. A Builder result only counts if it includes a concrete commit SHA you can hand to verification.
    - **Validator — only spawn if truly needed.** Ask yourself: \"Can I verify this story is correct just by reading the changed files?\" If YES → do NOT spawn the Validator — self-verify by reading the files and checking each criterion. If NO → spawn the Validator.
    - DO NOT spawn Validator for: adding a line to a named file (read the file, check the line is there), build/typecheck (trust Builder output or run the command yourself)
    - SPAWN Validator for: logic correctness, new behaviour, API contracts, anything requiring judgment to verify
-   - If your agent runtime supports named sub-agents, use the dedicated validator role when spawning and choose its model using the policy above
+   - If you do spawn a Validator, spawn a fresh Validator for that one story attempt. If your agent runtime supports named sub-agents, use the dedicated validator role when spawning and choose its model using the policy above
    - After each story attempt, update the story object in $PRD_ABS_PATH:
      - if the story passes, set passes=true and failureReason=null
      - if the story fails, set passes=false and failureReason to a short concrete reason string from the validator feedback
-4. Document any failures and move on to the next story
-5. When ALL stories have been processed (or skipped because already passed), verify the PRD file has been updated for every story (passes: true or false).
-6. Print a summary line \"DONE: X/Y stories passed\" and exit the session. Do not remain idle.
+5. If a story fails validation and still has retries left, spawn a new Builder for the retry instead of reusing the previous Builder run.
+6. Document any failures and move on to the next story
+7. When ALL stories have been processed (or skipped because already passed), verify the PRD file has been updated for every story (passes: true or false).
+8. Print a summary line \"DONE: X/Y stories passed\" and exit the session. Do not remain idle.
 
 ## Critical Rules
 - Do NOT stop after the first story — process ALL stories before exiting
@@ -951,6 +954,7 @@ $PENDING_STORIES_JSON
 - 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
+- NEVER treat task notifications, idle teammate output, or summary prose as a substitute for a real Builder result and PRD update
 
 Begin."