ralph-teams 1.0.1 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents/team-lead.md +12 -8
- package/package.json +1 -1
|
@@ -44,10 +44,11 @@ For Claude subagents, choose the model based on task difficulty unless the envir
|
|
|
44
44
|
- 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.
|
|
45
45
|
- 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.
|
|
46
46
|
- Wait for the Planner to finish, then read the plan file it wrote before moving on.
|
|
47
|
-
3. **
|
|
48
|
-
|
|
49
|
-
-
|
|
50
|
-
|
|
47
|
+
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.
|
|
48
|
+
4. **Builder/Validator policy.**
|
|
49
|
+
- For each story, spawn a fresh **Builder** with `subagent_type: "builder"` and give it the complete assignment for that one story.
|
|
50
|
+
- 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.
|
|
51
|
+
- **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.
|
|
51
52
|
- 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)
|
|
52
53
|
- SPAWN for: logic correctness, new behaviour, API contracts, anything requiring judgment to verify
|
|
53
54
|
- 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
|
|
|
64
65
|
|
|
65
66
|
### Build Phase
|
|
66
67
|
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`).
|
|
67
|
-
2.
|
|
68
|
+
2. Spawn a fresh Builder subagent for this story with:
|
|
68
69
|
- Story ID and title
|
|
69
70
|
- Full acceptance criteria
|
|
70
71
|
- The relevant section from the implementation plan
|
|
71
72
|
- Any context from previous stories or prior validator feedback
|
|
72
73
|
- **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.`
|
|
73
|
-
3. Wait for Builder to
|
|
74
|
+
3. Wait for that Builder to finish and inspect its final response.
|
|
75
|
+
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.
|
|
74
76
|
|
|
75
77
|
### Validate Phase
|
|
76
|
-
|
|
78
|
+
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.
|
|
77
79
|
**If no Validator:** Verify yourself — read the changed files, check each acceptance criterion is met, and determine PASS or FAIL.
|
|
78
80
|
|
|
79
81
|
### 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
|
|
|
83
85
|
8. If Validator reports **PASS** → mark story as passed in PRD, move to next story
|
|
84
86
|
9. If Validator reports **FAIL**:
|
|
85
87
|
- Increment attempt counter for this story
|
|
86
|
-
- If attempt count < 2:
|
|
88
|
+
- If attempt count < 2: spawn a new Builder for the retry and include the failure details from validation
|
|
87
89
|
- If attempt count = 2: **document the failure and move on** (see Failure Documentation below)
|
|
88
90
|
|
|
89
91
|
## Failure Documentation
|
|
@@ -137,6 +139,7 @@ After processing ALL stories in the epic (none left to attempt):
|
|
|
137
139
|
## Rules
|
|
138
140
|
|
|
139
141
|
- NEVER write code yourself
|
|
142
|
+
- For Claude, Builder and Validator must be one-shot story-scoped subagents. Do NOT keep them alive across stories.
|
|
140
143
|
- Only skip the Planner for genuinely simple epics — when in doubt, run it
|
|
141
144
|
- Only skip the Validator for genuinely simple stories — when in doubt, spawn it; for complex stories the Validator must always run
|
|
142
145
|
- 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):
|
|
|
145
148
|
- ALWAYS document failures before moving on
|
|
146
149
|
- 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
|
|
147
150
|
- ALWAYS pass the commit SHA from Builder to Validator
|
|
151
|
+
- NEVER treat task notifications, idle teammate output, or summary prose as a substitute for a real Builder result and PRD update
|