feat(ralph-specum): enforce team-based execution across all phases#93
Merged
feat(ralph-specum): enforce team-based execution across all phases#93
Conversation
Spec artifacts: - research.md: feasibility analysis and codebase exploration - requirements.md: user stories and acceptance criteria - design.md: architecture and technical decisions - tasks.md: POC-first implementation plan Ready for implementation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ssed Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
No structural issues found - all 5 command files pass: - Valid YAML frontmatter - Matched mandatory tags - Matched code fences - Correct heading hierarchy - All original sections present Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughThis PR updates the ralph-specum plugin version from 3.4.1 to 3.5.0 and refactors command documentation across research, requirements, design, tasks, and implementation phases to adopt a standardized Claude Code Teams lifecycle pattern (TeamCreate, TaskCreate, Spawn, Monitor, Shutdown, Collect, Delete) with orphaned team detection and cleanup, replacing previous single-agent and ad-hoc parallel execution approaches. Changes
Sequence Diagram(s)sequenceDiagram
actor Coordinator
participant TeamAPI as Team API
participant TaskAPI as Task API
participant Teammate as Teammate Agent
participant Monitor as Task Monitor
Coordinator->>Coordinator: Check for orphaned team
Coordinator->>Coordinator: Cleanup if needed
Coordinator->>TeamAPI: TeamCreate(phase-spec)
TeamAPI-->>Coordinator: Team ID
Coordinator->>TaskAPI: TaskCreate(work_item_1)
Coordinator->>TaskAPI: TaskCreate(work_item_2)
Coordinator->>Teammate: Task(team_id, subagent_type)
Coordinator->>Teammate: Task(team_id, subagent_type)
par Parallel Execution
Teammate->>Teammate: Execute work_item_1
Teammate->>Teammate: Execute work_item_2
end
Coordinator->>Monitor: TaskList(team_id)
Monitor-->>Coordinator: Status updates
Monitor-->>Coordinator: Completion signal
Coordinator->>TeamAPI: SendMessage(shutdown)
TeamAPI-->>Coordinator: Shutdown acknowledgment
Coordinator->>Coordinator: Collect & merge results
Coordinator->>TeamAPI: TeamDelete(team_id)
TeamAPI-->>Coordinator: Cleanup complete
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…view) Merge main into feat/enforce-teams-instead. Conflicts in design.md, requirements.md, and tasks.md resolved by keeping both our team-based execution steps AND the new Artifact Review sections from main. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (4)
plugins/ralph-specum/commands/requirements.md (1)
4-4: Consider enumerating required team tools instead of"*".
allowed-tools: "*"grants the coordinator access to all tools (including WebSearch, computer control, etc.) when only a specific subset is needed for orchestration:[Read, Write, Edit, Task, Bash, TaskCreate, TaskList, SendMessage, TeamCreate, TeamDelete, AskUserQuestion]. The wildcard follows the same pattern asresearch.mdintentionally, but violates least-privilege.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/ralph-specum/commands/requirements.md` at line 4, Replace the wildcard value in the allowed-tools key with an explicit enumerated list to follow least-privilege; update the allowed-tools entry from "*" to the specific array: Read, Write, Edit, Task, Bash, TaskCreate, TaskList, SendMessage, TeamCreate, TeamDelete, AskUserQuestion (i.e., set allowed-tools: ["Read","Write","Edit","Task","Bash","TaskCreate","TaskList","SendMessage","TeamCreate","TeamDelete","AskUserQuestion"]) so the coordinator only gets the necessary tool permissions.plugins/ralph-specum/commands/research.md (1)
566-598: Consider an explicit note that feedback-loop re-invocations intentionally skip the team lifecycle.The Handle Response section spawns bare subagents without team wrapping. Per the PR design, research re-invocations are intentionally excluded from the cleanup-and-recreate pattern (only requirements/design/tasks use it). A single inline note would prevent future editors from incorrectly "fixing" this to use teams.
✏️ Suggested inline note
**If "Need changes" or "Other"**: +<!-- NOTE: Research feedback uses direct Task calls intentionally. + Only requirements/design/tasks use the cleanup-and-recreate team pattern for re-invocations. --> 1. Ask: "What would you like changed?"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/ralph-specum/commands/research.md` around lines 566 - 598, Add an explicit inline note in the "Handle Response" / feedback-loop section of research.md clarifying that feedback-loop re-invocations (the research re-run described in the "If 'Need changes' or 'Other'" flow and the example prompt) intentionally skip the team lifecycle and do not spawn subagents wrapped in the team cleanup-and-recreate pattern; state that only the requirements, design, and tasks flows use the cleanup-and-recreate team pattern so future editors don't change the behavior.specs/enforce-teams-instead/design.md (2)
58-68: Missing language identifier on fenced code block (markdownlint MD040).✏️ Proposed fix
-``` +```text 1. Check for orphaned team: Read ~/.claude/teams/$phase-$spec/config.json🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@specs/enforce-teams-instead/design.md` around lines 58 - 68, The fenced code block starting with ``` in the design.md snippet lacks a language identifier, triggering markdownlint MD040; update the opening fence to include a language (for example change ``` to ```text) so the block becomes ```text ... ``` and ensure the closing ``` remains, which will satisfy the linter without altering the block contents.
42-43: Mermaid diagram: second arrow fromRbypassesTC(TeamCreate) without a label.
R --> TK --> RA(line 43) appears to depict research reaching TaskCreate directly, skipping TeamCreate. If this represents the fallback path (TeamCreate fails → bare Task calls), it should be labeled to match the documented fallback behavior. As-is, it reads as an alternative primary path, contradicting the design that all phases go through TeamCreate first.🔀 Option 1: Label as fallback
- R --> TC --> TK --> RA - R --> TK --> RA + R --> TC --> TK --> RA + R -->|fallback: TC fails| TK --> RA🗑️ Option 2: Remove the ambiguous line (fallback is prose-documented)
R --> TC --> TK --> RA - R --> TK --> RA🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@specs/enforce-teams-instead/design.md` around lines 42 - 43, The mermaid diagram shows an ambiguous path "R --> TK --> RA" that looks like an alternative primary flow; update the diagram so this arrow is explicitly labeled as the fallback (e.g., `R -->|TeamCreate failed / fallback| TK --> RA`) to match the prose, or alternatively remove the `R --> TK --> RA` line if you prefer to keep the fallback only documented in text; adjust the nodes R, TC, TK, RA accordingly so the design clearly indicates TeamCreate is the primary path and the unlabeled arrow is no longer misleading.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/ralph-specum/commands/implement.md`:
- Around line 354-360: The SendMessage shutdown call for each teammate omits the
content field; update the shutdown messages sent in the "Step 6: Shutdown
Teammates" block so each SendMessage(type: "shutdown_request", recipient:
"executor-$taskIndex") includes a content property (e.g., content: "Requirements
complete, shutting down") matching the other phase commands and ensuring
consistent teammate shutdown logging.
In `@plugins/ralph-specum/commands/requirements.md`:
- Around line 196-234: The fenced code block that documents the Task for the
product-manager (the block beginning with "Task(subagent_type: product-manager,
team_name: \"requirements-$spec\", name: \"pm-1\",") is missing a language
specifier and triggers MD040; fix it by adding a language token (for example
"text") after the opening triple backticks so the block becomes ```text and the
linter warning is resolved.
In `@specs/.index/index-state.json`:
- Around line 19-23: The index entry for the spec named "enforce-teams-instead"
is missing task count fields; add "taskIndex": 14 and "totalTasks": 14 to that
JSON object so tooling can compute progress (use the counts from tasks.md which
declares total_tasks: 14 and shows all 14 completed). Ensure the keys are added
at the same object level as "name"/"path"/"phase" so the record matches other
spec entries that track progress.
In `@specs/.index/index.md`:
- Around line 21-22: Update the table row to fix the spec name and phase enum:
change the spec identifier from "return-ralph-wrigum" to "return-ralph-wiggum"
and change the phase value from "complete" to "completed" so it matches the
other entries; edit the row containing "| return-ralph-wrigum | ./specs |
complete |" to read "| return-ralph-wiggum | ./specs | completed |".
In `@specs/enforce-teams-instead/.progress.md`:
- Around line 17-19: Remove the duplicated task label "2.2" and reorder the
checklist so task "2.1 Standardize team lifecycle documentation across all
command files" appears first followed by a single "2.2 Add error handling for
team operations"; ensure only one "2.2" remains and the numeric ordering is
ascending.
In `@specs/enforce-teams-instead/tasks.md`:
- Around line 67-93: Phase 2 lacks a quality checkpoint between the refactor
tasks (2.1–2.3); insert a mid-phase verification step after either task 2.1 or
2.2 (e.g., "2.1.1 Quality Checkpoint: validate structural consistency and
error-handling additions across the five command files") and document acceptance
criteria (compare team lifecycle sections, search for "fallback" or "TeamCreate
fails", and run a quick review of "Handle Response" updates) so the
refactor(ralph-specum): standardize team lifecycle across phases and
refactor(ralph-specum): add error handling for team operations commits include
this checkpoint record. Ensure the new checkpoint is reflected in Phase 2
checklist and "Done when"/"Verify" lines for traceability.
- Around line 15-65: Insert an intermediate quality checkpoint after Task 1.2:
add a new checklist item "1.3 Quality Checkpoint (after 1.2)" that requires
reviewing the two converted files (plugins/ralph-specum/commands/research.md and
plugins/ralph-specum/commands/requirements.md) to confirm consistent team
lifecycle pattern, correct team naming ($phase-$spec), orphaned team cleanup
presence, preserved non-team sections, and no markdown syntax errors; renumber
downstream tasks (original 1.3–1.5 → 1.4–1.6), update the POC Checkpoint
description to reflect the new indices, and commit with a message like
feat(ralph-specum): add checkpoint after initial conversions.
---
Nitpick comments:
In `@plugins/ralph-specum/commands/requirements.md`:
- Line 4: Replace the wildcard value in the allowed-tools key with an explicit
enumerated list to follow least-privilege; update the allowed-tools entry from
"*" to the specific array: Read, Write, Edit, Task, Bash, TaskCreate, TaskList,
SendMessage, TeamCreate, TeamDelete, AskUserQuestion (i.e., set allowed-tools:
["Read","Write","Edit","Task","Bash","TaskCreate","TaskList","SendMessage","TeamCreate","TeamDelete","AskUserQuestion"])
so the coordinator only gets the necessary tool permissions.
In `@plugins/ralph-specum/commands/research.md`:
- Around line 566-598: Add an explicit inline note in the "Handle Response" /
feedback-loop section of research.md clarifying that feedback-loop
re-invocations (the research re-run described in the "If 'Need changes' or
'Other'" flow and the example prompt) intentionally skip the team lifecycle and
do not spawn subagents wrapped in the team cleanup-and-recreate pattern; state
that only the requirements, design, and tasks flows use the cleanup-and-recreate
team pattern so future editors don't change the behavior.
In `@specs/enforce-teams-instead/design.md`:
- Around line 58-68: The fenced code block starting with ``` in the design.md
snippet lacks a language identifier, triggering markdownlint MD040; update the
opening fence to include a language (for example change ``` to ```text) so the
block becomes ```text ... ``` and ensure the closing ``` remains, which will
satisfy the linter without altering the block contents.
- Around line 42-43: The mermaid diagram shows an ambiguous path "R --> TK -->
RA" that looks like an alternative primary flow; update the diagram so this
arrow is explicitly labeled as the fallback (e.g., `R -->|TeamCreate failed /
fallback| TK --> RA`) to match the prose, or alternatively remove the `R --> TK
--> RA` line if you prefer to keep the fallback only documented in text; adjust
the nodes R, TC, TK, RA accordingly so the design clearly indicates TeamCreate
is the primary path and the unlabeled arrow is no longer misleading.
specs/.index/index.md
Outdated
Comment on lines
21
to
22
| | return-ralph-wrigum | ./specs | complete | | | ||
| | refactor-plugins | ./specs | new | | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check for spec directories with the specified pattern
echo "=== Spec directories matching 'return-ralph-w' ==="
fd -t d 'return-ralph-w' specs/ 2>/dev/null || echo "No matches found"
# Check unique phase values in the state file
echo -e "\n=== Unique phase values in index state ==="
if [ -f specs/.index/index-state.json ]; then
rg '"phase"\s*:\s*"[^"]*"' specs/.index/index-state.json -o | sort -u
else
echo "File not found: specs/.index/index-state.json"
fi
# Also check the index.md file to see all phase values
echo -e "\n=== Phase values in index.md ==="
if [ -f specs/.index/index.md ]; then
rg '\|\s+\w+\s+\|' specs/.index/index.md | grep -oE '(complete|completed|new|in-progress|tasks)' | sort | uniq -c
else
echo "File not found: specs/.index/index.md"
fi
# Check if there's a spec named with "wiggum" (correct spelling)
echo -e "\n=== All 'ralph' spec directories ==="
fd -t d 'ralph' specs/ 2>/dev/null | head -20Repository: tzachbon/smart-ralph
Length of output: 467
🏁 Script executed:
#!/bin/bash
# Get the actual content of lines 21-22 in the index file
echo "=== Lines 21-22 from specs/.index/index.md ==="
sed -n '21,22p' specs/.index/index.md
# Get more context around those lines
echo -e "\n=== Context: lines 19-25 ==="
sed -n '19,25p' specs/.index/index.md
# Check if there's any reference to "return-ralph" anywhere in the repo
echo -e "\n=== References to 'return-ralph' in the codebase ==="
rg 'return-ralph' specs/ --type md --type json 2>/dev/null | head -10Repository: tzachbon/smart-ralph
Length of output: 772
Fix the phase value from complete to completed and correct the spec name from wrigum to wiggum.
Line 21 uses complete while all other finished specs use completed—this enum inconsistency will break any tooling that matches phase values. The spec name return-ralph-wrigum is also misspelled; all other ralph specs use the correct Simpsons character spelling wiggum (e.g., fork-ralph-wiggum, implement-ralph-wiggum). The research.md for fork-ralph-wiggum documents this entry as abandoned.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@specs/.index/index.md` around lines 21 - 22, Update the table row to fix the
spec name and phase enum: change the spec identifier from "return-ralph-wrigum"
to "return-ralph-wiggum" and change the phase value from "complete" to
"completed" so it matches the other entries; edit the row containing "|
return-ralph-wrigum | ./specs | complete |" to read "| return-ralph-wiggum |
./specs | completed |".
Comment on lines
+15
to
+65
| - [x] 1.1 Convert research.md to team-based pattern | ||
| - **Do**: Replace the "Execute Research" section in `plugins/ralph-specum/commands/research.md` with a team-based flow matching start.md's pattern. Add sections for: (1) orphaned team check, (2) TeamCreate, (3) TaskCreate per research topic, (4) spawn teammates via Task with team_name, (5) wait for completion via TaskList, (6) shutdown teammates, (7) merge results (keep existing merge logic), (8) TeamDelete. Keep all other sections (Interview, Walkthrough, Review, Update State, Commit, Stop) unchanged. | ||
| - **Files**: `plugins/ralph-specum/commands/research.md` | ||
| - **Done when**: research.md Execute Research section uses TeamCreate/TaskCreate/SendMessage/TeamDelete lifecycle instead of bare multi-Task calls | ||
| - **Verify**: Read the file and confirm TeamCreate, TaskCreate, SendMessage(shutdown_request), and TeamDelete are all referenced in the Execute Research section | ||
| - **Commit**: `feat(ralph-specum): convert research.md to team-based execution` | ||
| - _Requirements: FR-1_ | ||
| - _Design: Component A_ | ||
|
|
||
| - [x] 1.2 Add team lifecycle to requirements.md | ||
| - **Do**: Replace the "Execute Requirements" section in `plugins/ralph-specum/commands/requirements.md` with a team-based flow. Add: (1) orphaned team check for `requirements-$spec`, (2) TeamCreate, (3) TaskCreate with existing product-manager prompt, (4) spawn single teammate via Task with team_name, (5) wait for completion, (6) shutdown teammate, (7) TeamDelete. Keep the review/feedback loop -- if user requests changes, the re-invocation of product-manager should also use the team pattern (or spawn a new teammate in the existing team). | ||
| - **Files**: `plugins/ralph-specum/commands/requirements.md` | ||
| - **Done when**: requirements.md Execute Requirements section uses team lifecycle with product-manager as a teammate | ||
| - **Verify**: Read the file and confirm TeamCreate and TeamDelete are referenced in Execute Requirements section | ||
| - **Commit**: `feat(ralph-specum): convert requirements.md to team-based execution` | ||
| - _Requirements: FR-2_ | ||
| - _Design: Component B_ | ||
|
|
||
| - [x] 1.3 Add team lifecycle to design.md | ||
| - **Do**: Replace the "Execute Design" section in `plugins/ralph-specum/commands/design.md` with the same team-based wrapper pattern used in requirements.md. Team name: `design-$spec`. Teammate name: `architect-1`. Use `architect-reviewer` subagent type. Keep all review/feedback/walkthrough sections unchanged. | ||
| - **Files**: `plugins/ralph-specum/commands/design.md` | ||
| - **Done when**: design.md Execute Design section uses team lifecycle with architect-reviewer as a teammate | ||
| - **Verify**: Read the file and confirm TeamCreate and TeamDelete are referenced in Execute Design section | ||
| - **Commit**: `feat(ralph-specum): convert design.md to team-based execution` | ||
| - _Requirements: FR-3_ | ||
| - _Design: Component C_ | ||
|
|
||
| - [x] 1.4 Add team lifecycle to tasks.md command | ||
| - **Do**: Replace the "Execute Tasks Generation" section in `plugins/ralph-specum/commands/tasks.md` with the team-based wrapper pattern. Team name: `tasks-$spec`. Teammate name: `planner-1`. Use `task-planner` subagent type. Keep all review/feedback/walkthrough sections unchanged. | ||
| - **Files**: `plugins/ralph-specum/commands/tasks.md` | ||
| - **Done when**: tasks.md Execute Tasks Generation section uses team lifecycle with task-planner as a teammate | ||
| - **Verify**: Read the file and confirm TeamCreate and TeamDelete are referenced in Execute Tasks Generation section | ||
| - **Commit**: `feat(ralph-specum): convert tasks.md to team-based execution` | ||
| - _Requirements: FR-4_ | ||
| - _Design: Component D_ | ||
|
|
||
| - [x] 1.5 Convert parallel execution in implement.md to team-based | ||
| - **Do**: Modify the "Parallel Execution" subsection of Section 6 "Task Delegation" in `plugins/ralph-specum/commands/implement.md`. Replace the current multi-Task parallel pattern with: (1) orphaned team check for `exec-$spec`, (2) TeamCreate, (3) TaskCreate per parallel task, (4) Task per executor with team_name, (5) wait via TaskList, (6) shutdown, (7) TeamDelete. Keep sequential execution and [VERIFY] task handling unchanged. Keep the stop-hook loop mechanism completely unchanged. | ||
| - **Files**: `plugins/ralph-specum/commands/implement.md` | ||
| - **Done when**: Parallel [P] task execution in implement.md uses TeamCreate/TaskCreate/TeamDelete lifecycle; sequential tasks unchanged | ||
| - **Verify**: Read Section 6 of implement.md and confirm team lifecycle is used for parallel batches but not for sequential tasks | ||
| - **Commit**: `feat(ralph-specum): convert parallel execution to team-based` | ||
| - _Requirements: FR-5_ | ||
| - _Design: Component E_ | ||
|
|
||
| - [x] 1.6 POC Checkpoint | ||
| - **Do**: Review all 5 modified command files to verify: (a) each has consistent team lifecycle pattern, (b) team naming follows `$phase-$spec` convention, (c) orphaned team cleanup is present in each, (d) no syntax errors in markdown structure, (e) existing non-team sections are preserved | ||
| - **Files**: `plugins/ralph-specum/commands/research.md`, `plugins/ralph-specum/commands/requirements.md`, `plugins/ralph-specum/commands/design.md`, `plugins/ralph-specum/commands/tasks.md`, `plugins/ralph-specum/commands/implement.md` | ||
| - **Done when**: All 5 files have consistent team lifecycle and the rest of each file is unchanged | ||
| - **Verify**: Read each file and check for TeamCreate and TeamDelete presence | ||
| - **Commit**: `feat(ralph-specum): complete POC for team-based phases` |
There was a problem hiding this comment.
Phase 1 has 5 consecutive tasks (1.1–1.5) before its first checkpoint — guideline requires one every 2–3 tasks.
An intermediate quality checkpoint is missing between tasks 1.2 and 1.4. A checkpoint around 1.2 (after converting the first two command files) would keep the cadence within the required range.
📋 Suggested structure
- [x] 1.2 Add team lifecycle to requirements.md
...
+- [x] 1.2.5 Checkpoint: Verify first two conversions
+ - **Do**: Review research.md and requirements.md for team lifecycle consistency (TeamCreate/TeamDelete present, naming convention, orphaned team check)
+ - **Done when**: Both files validated
+ - **Commit**: None (verification only)
+
- [x] 1.3 Add team lifecycle to design.mdBased on learnings, "Quality checkpoints must be inserted every 2-3 tasks throughout all phases in task specifications."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@specs/enforce-teams-instead/tasks.md` around lines 15 - 65, Insert an
intermediate quality checkpoint after Task 1.2: add a new checklist item "1.3
Quality Checkpoint (after 1.2)" that requires reviewing the two converted files
(plugins/ralph-specum/commands/research.md and
plugins/ralph-specum/commands/requirements.md) to confirm consistent team
lifecycle pattern, correct team naming ($phase-$spec), orphaned team cleanup
presence, preserved non-team sections, and no markdown syntax errors; renumber
downstream tasks (original 1.3–1.5 → 1.4–1.6), update the POC Checkpoint
description to reflect the new indices, and commit with a message like
feat(ralph-specum): add checkpoint after initial conversions.
Comment on lines
+67
to
+93
| ## Phase 2: Refactoring | ||
|
|
||
| After POC validated, clean up and standardize the team patterns across files. | ||
|
|
||
| - [x] 2.1 Standardize team lifecycle documentation across all command files | ||
| - **Do**: Ensure all 5 command files use the exact same team lifecycle structure: same step numbering, same section headers ("Step 1: Check for Orphaned Team", "Step 2: Create Team", etc.), same cleanup pattern. Extract any inconsistencies introduced during POC and make them uniform. Ensure the mandatory/critical blocks wrap the team sections properly. | ||
| - **Files**: `plugins/ralph-specum/commands/research.md`, `plugins/ralph-specum/commands/requirements.md`, `plugins/ralph-specum/commands/design.md`, `plugins/ralph-specum/commands/tasks.md`, `plugins/ralph-specum/commands/implement.md` | ||
| - **Done when**: All team lifecycle sections follow identical structure and naming conventions | ||
| - **Verify**: Compare team lifecycle sections across all 5 files for structural consistency | ||
| - **Commit**: `refactor(ralph-specum): standardize team lifecycle across phases` | ||
| - _Design: Architecture_ | ||
|
|
||
| - [x] 2.2 Add error handling for team operations | ||
| - **Do**: Add fallback behavior to each command file: if TeamCreate fails, fall back to direct Task delegation (no team). Add this as a documented pattern in each Execute section: "If TeamCreate fails, log warning and fall back to direct Task(subagent_type: ...) call without team." Also add timeout notes for teammate completion waiting. | ||
| - **Files**: `plugins/ralph-specum/commands/research.md`, `plugins/ralph-specum/commands/requirements.md`, `plugins/ralph-specum/commands/design.md`, `plugins/ralph-specum/commands/tasks.md`, `plugins/ralph-specum/commands/implement.md` | ||
| - **Done when**: Each command file documents fallback behavior for TeamCreate failure and teammate timeout | ||
| - **Verify**: Search all 5 files for "fallback" or "TeamCreate fails" text | ||
| - **Commit**: `refactor(ralph-specum): add error handling for team operations` | ||
| - _Design: Error Handling_ | ||
|
|
||
| - [x] 2.3 Update review/feedback loops to work with teams | ||
| - **Do**: In requirements.md, design.md, and tasks.md, update the "Handle Response" sections for when user requests changes. When the user says "Need changes", the re-invocation of the subagent should either: (a) spawn a new teammate in the existing team, or (b) create a new team for the re-invocation. Choose option (b) for simplicity -- cleanup and recreate team for each feedback iteration. Document this clearly. | ||
| - **Files**: `plugins/ralph-specum/commands/requirements.md`, `plugins/ralph-specum/commands/design.md`, `plugins/ralph-specum/commands/tasks.md` | ||
| - **Done when**: Feedback loops document team creation/cleanup for re-invocations | ||
| - **Verify**: Read "Handle Response" sections and confirm team lifecycle is addressed | ||
| - **Commit**: `refactor(ralph-specum): handle feedback loops with team pattern` | ||
| - _Requirements: FR-8_ |
There was a problem hiding this comment.
Phase 2 has 3 tasks (2.1–2.3) with no quality checkpoint.
The refactoring phase converts all 5 files and adds error handling across them — a mid-phase checkpoint after task 2.1 or 2.2 would catch structural regressions before the feedback-loop rework in 2.3.
📋 Suggested addition
- [x] 2.1 Standardize team lifecycle documentation across all command files
...
+- [x] 2.1.5 Checkpoint: Verify standardized structure
+ - **Do**: Confirm all 5 files share identical step numbering and section header names after 2.1
+ - **Done when**: Structural diff between all 5 lifecycle sections shows no deviations
+ - **Commit**: None (verification only)
+
- [x] 2.2 Add error handling for team operationsBased on learnings, "Quality checkpoints must be inserted every 2-3 tasks throughout all phases in task specifications."
🧰 Tools
🪛 LanguageTool
[style] ~72-~72: ‘exact same’ might be wordy. Consider a shorter alternative.
Context: ...o**: Ensure all 5 command files use the exact same team lifecycle structure: same step num...
(EN_WORDINESS_PREMIUM_EXACT_SAME)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@specs/enforce-teams-instead/tasks.md` around lines 67 - 93, Phase 2 lacks a
quality checkpoint between the refactor tasks (2.1–2.3); insert a mid-phase
verification step after either task 2.1 or 2.2 (e.g., "2.1.1 Quality Checkpoint:
validate structural consistency and error-handling additions across the five
command files") and document acceptance criteria (compare team lifecycle
sections, search for "fallback" or "TeamCreate fails", and run a quick review of
"Handle Response" updates) so the refactor(ralph-specum): standardize team
lifecycle across phases and refactor(ralph-specum): add error handling for team
operations commits include this checkpoint record. Ensure the new checkpoint is
reflected in Phase 2 checklist and "Done when"/"Verify" lines for traceability.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Bump version 3.5.0 → 3.5.1 (main already has 3.5.0 from PR #92) - implement.md: add content field to SendMessage shutdown - requirements.md: add language specifier to code block - research.md: add note that feedback loop skips team pattern - design.md: remove ambiguous mermaid arrow, add code block language - .progress.md: remove duplicated task 2.2 entry - index-state.json: add task counts for enforce-teams-instead - index.md: fix phase value for return-ralph-wrigum Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
All 5 phase commands (research, requirements, design, tasks, implement) now use Claude Code Teams lifecycle instead of bare Task/sub-agent calls.
What Changed
$phase-$specconvention (e.g.,research-my-feature,exec-my-feature)Key Decisions
allowed-toolschanged to"*"in requirements, design, and tasks commands to support team toolsModified Files
plugins/ralph-specum/commands/research.md— team lifecycle for parallel researchplugins/ralph-specum/commands/requirements.md— team lifecycle for product-managerplugins/ralph-specum/commands/design.md— team lifecycle for architect-reviewerplugins/ralph-specum/commands/tasks.md— team lifecycle for task-plannerplugins/ralph-specum/commands/implement.md— team lifecycle for parallel [P] batchesplugins/ralph-specum/.claude-plugin/plugin.json— version bump 3.4.1 → 3.5.0.claude-plugin/marketplace.json— matching version bumpVersion
Bumped to 3.5.0 (minor: new feature, no breaking changes)
🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes v3.5.0
New Features
Bug Fixes
Chores