feat(walkthrough): add phase walkthrough summaries #78
Conversation
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
Two-phase approach: - Phase A: Metadata fixes (color, version, matcher, examples) - Phase B: Skill consolidation (11 new skills, simplified commands/agents) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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 (14 tasks) Ready for implementation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe PR bumps the ralph-specum plugin version from 2.10.0 to 2.11.0 across manifest files, adds "Generate Phase Walkthrough" documentation to four agent guides, introduces a Phase Walkthrough template section, and establishes comprehensive specification documents for implementing walkthrough generation and plugin refactoring initiatives. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 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. 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 |
PR: #78 Co-Authored-By: Claude Opus 4.5 <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: 4
🤖 Fix all issues with AI agents
In `@plugins/ralph-specum/templates/progress.md`:
- Around line 21-25: Update the table header in
plugins/ralph-specum/templates/progress.md so the columns match agent output by
replacing "Phase | Files Changed | Summary" with "File | Change Type | Summary"
and ensure the placeholder row stays compatible with appended agent entries;
then add two new manifest files named plugin.json and marketplace.json inside
plugins/ralph-specum containing initial version fields (e.g., a semantic
"version" key) so both manifests are present for version bumping on future
changes.
In `@specs/add-walk-through-of/tasks.md`:
- Around line 14-20: The spec currently defines five phases (Phase 1..Phase 5)
including a separate "PR Lifecycle" phase; update the tasks.md phase list so it
conforms to the mandated 4‑phase POC‑first workflow by merging the "PR
Lifecycle" items into Phase 4 (Quality Gates) or relabeling them as Phase 4
tasks, ensuring Phase 1 = Make It Work (POC), Phase 2 = Refactoring, Phase 3 =
Testing, and Phase 4 = Quality Gates (including lint, types, CI, PR
lifecycle/monitoring tasks); adjust the Phase headers and any bullet points
referring to "Phase 5" accordingly.
In `@specs/refactor-plugins/design.md`:
- Around line 168-173: The "Safety" section's claim "All changes are additive
(add fields, not remove)" conflicts with planned removals of legacy commands and
directories; update the Safety paragraph to either (A) scope the additive claim
to Phase A only (e.g., "All Phase A changes are additive — metadata edits only")
and explicitly call out later phases will remove legacy commands/directories, or
(B) remove the absolute claim and add a sentence that notes planned non‑additive
removals (legacy commands/directories) will occur in later phases; apply the
same clarification to the matching text around lines noted (the "Safety" block
and the repeated text at ~239-254) and reference the "Phase A" wording so
readers know which edits remain additive and which do not.
- Around line 300-337: The matcher check is too weak—replace the grep-based
check for hooks (the for loop over plugins/*/hooks/hooks.json and the grep -q
'"matcher"' call) with a JSON-aware per-entry validation using jq: for each
hooks.json run a jq query that iterates over the hooks array (or object entries)
and confirms every entry has a non-empty "matcher" field, and if any entry is
missing/empty increment ERRORS and print a FAIL message referencing that
hooks.json file; ensure the new check lives where the current "# 4. Check hooks
have matcher field" logic is and keeps the same error counting behavior.
Comment on lines
+21
to
+25
| ## Phase Walkthrough | ||
|
|
||
| | Phase | Files Changed | Summary | | ||
| |-------|---------------|---------| | ||
| | _No phases completed yet_ | | | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check template columns
echo "=== Template columns ==="
cat plugins/ralph-specum/templates/progress.md | sed -n '21,25p'
# Check agent instruction columns
echo -e "\n=== Agent task-planner.md ==="
rg -A 5 "Phase|File.*Change Type" plugins/ralph-specum/agents/task-planner.md -m 3
echo -e "\n=== Agent product-manager.md ==="
rg -A 5 "Phase|File.*Change Type" plugins/ralph-specum/agents/product-manager.md -m 3
# Check version files
echo -e "\n=== Version files ==="
echo "plugin.json:"
jq '.version' plugins/ralph-specum/plugin.json
echo "marketplace.json:"
jq '.version' plugins/ralph-specum/marketplace.jsonRepository: tzachbon/smart-ralph
Length of output: 1585
🏁 Script executed:
#!/bin/bash
# Search for plugin.json and marketplace.json
echo "=== Searching for version files ==="
fd "plugin\.json|marketplace\.json" plugins/ralph-specum/
# Check if ralph-specum directory exists and list its contents
echo -e "\n=== ralph-specum directory structure ==="
ls -la plugins/ralph-specum/ 2>/dev/null || echo "Directory not found at expected location"
# Check all plugins directory
echo -e "\n=== All plugin directories ==="
find plugins -maxdepth 2 -name "plugin.json" -o -name "marketplace.json"Repository: tzachbon/smart-ralph
Length of output: 680
Fix column header mismatch and missing version files.
The template defines table columns as Phase | Files Changed | Summary, but agent instructions (task-planner.md, product-manager.md) specify File | Change Type | Summary. This inconsistency will break formatting when agents append walkthroughs to the progress.md file.
Additionally, the coding guidelines require version bumping in BOTH plugin.json and marketplace.json when making ANY changes to plugin files. These version files are missing from the ralph-specum plugin directory and must be created.
Fixes needed:
- Update template columns to match agent output:
File | Change Type | Summary - Create
plugin.jsonandmarketplace.jsoninplugins/ralph-specum/with initial versions
🤖 Prompt for AI Agents
In `@plugins/ralph-specum/templates/progress.md` around lines 21 - 25, Update the
table header in plugins/ralph-specum/templates/progress.md so the columns match
agent output by replacing "Phase | Files Changed | Summary" with "File | Change
Type | Summary" and ensure the placeholder row stays compatible with appended
agent entries; then add two new manifest files named plugin.json and
marketplace.json inside plugins/ralph-specum containing initial version fields
(e.g., a semantic "version" key) so both manifests are present for version
bumping on future changes.
Comment on lines
+14
to
+20
| POC-first workflow with 5 phases: | ||
| 1. Phase 1: Make It Work (POC) - Add walkthrough to one agent | ||
| 2. Phase 2: Refactoring - Apply pattern to all agents | ||
| 3. Phase 3: Testing - Validate walkthroughs generated correctly | ||
| 4. Phase 4: Quality Gates - Local checks and PR creation | ||
| 5. Phase 5: PR Lifecycle - CI monitoring and review | ||
|
|
There was a problem hiding this comment.
Align phase structure to required 4‑phase POC‑first workflow.
This spec introduces a 5th “PR Lifecycle” phase, which conflicts with the mandated 4-phase workflow. Please fold PR lifecycle tasks into Phase 4 or note them as Phase 4 tasks.
🛠️ Suggested adjustment
-POC-first workflow with 5 phases:
+POC-first workflow with 4 phases:
1. Phase 1: Make It Work (POC) - Add walkthrough to one agent
2. Phase 2: Refactoring - Apply pattern to all agents
3. Phase 3: Testing - Validate walkthroughs generated correctly
-4. Phase 4: Quality Gates - Local checks and PR creation
-5. Phase 5: PR Lifecycle - CI monitoring and review
+4. Phase 4: Quality Gates - Local checks, PR creation, CI monitoring, review📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| POC-first workflow with 5 phases: | |
| 1. Phase 1: Make It Work (POC) - Add walkthrough to one agent | |
| 2. Phase 2: Refactoring - Apply pattern to all agents | |
| 3. Phase 3: Testing - Validate walkthroughs generated correctly | |
| 4. Phase 4: Quality Gates - Local checks and PR creation | |
| 5. Phase 5: PR Lifecycle - CI monitoring and review | |
| POC-first workflow with 4 phases: | |
| 1. Phase 1: Make It Work (POC) - Add walkthrough to one agent | |
| 2. Phase 2: Refactoring - Apply pattern to all agents | |
| 3. Phase 3: Testing - Validate walkthroughs generated correctly | |
| 4. Phase 4: Quality Gates - Local checks, PR creation, CI monitoring, review |
🤖 Prompt for AI Agents
In `@specs/add-walk-through-of/tasks.md` around lines 14 - 20, The spec currently
defines five phases (Phase 1..Phase 5) including a separate "PR Lifecycle"
phase; update the tasks.md phase list so it conforms to the mandated 4‑phase
POC‑first workflow by merging the "PR Lifecycle" items into Phase 4 (Quality
Gates) or relabeling them as Phase 4 tasks, ensuring Phase 1 = Make It Work
(POC), Phase 2 = Refactoring, Phase 3 = Testing, and Phase 4 = Quality Gates
(including lint, types, CI, PR lifecycle/monitoring tasks); adjust the Phase
headers and any bullet points referring to "Phase 5" accordingly.
Comment on lines
+168
to
+173
| **Safety**: | ||
| - All changes are additive (add fields, not remove) | ||
| - Skill references maintain full behavior | ||
| - Backward compatible - existing usage unchanged | ||
| - Phase A can be deployed independently | ||
|
|
There was a problem hiding this comment.
“All changes are additive” conflicts with planned removals.
The safety claim says all changes are additive, but the plan explicitly removes legacy commands and directories. Either scope the additive claim to Phase A metadata edits or note the removals as non‑additive.
Also applies to: 239-254
🤖 Prompt for AI Agents
In `@specs/refactor-plugins/design.md` around lines 168 - 173, The "Safety"
section's claim "All changes are additive (add fields, not remove)" conflicts
with planned removals of legacy commands and directories; update the Safety
paragraph to either (A) scope the additive claim to Phase A only (e.g., "All
Phase A changes are additive — metadata edits only") and explicitly call out
later phases will remove legacy commands/directories, or (B) remove the absolute
claim and add a sentence that notes planned non‑additive removals (legacy
commands/directories) will occur in later phases; apply the same clarification
to the matching text around lines noted (the "Safety" block and the repeated
text at ~239-254) and reference the "Phase A" wording so readers know which
edits remain additive and which do not.
Comment on lines
+300
to
+337
| ```bash | ||
| #!/bin/bash | ||
| # Plugin compliance validation | ||
|
|
||
| ERRORS=0 | ||
|
|
||
| # 1. Check agents have color field | ||
| for agent in plugins/*/agents/*.md; do | ||
| if ! grep -q "^color:" "$agent"; then | ||
| echo "FAIL: Missing color in $agent" | ||
| ((ERRORS++)) | ||
| fi | ||
| done | ||
|
|
||
| # 2. Check agents have <example> blocks (at least 2) | ||
| for agent in plugins/*/agents/*.md; do | ||
| count=$(grep -c "<example>" "$agent" || echo 0) | ||
| if [ "$count" -lt 2 ]; then | ||
| echo "FAIL: Need 2+ examples in $agent (found $count)" | ||
| ((ERRORS++)) | ||
| fi | ||
| done | ||
|
|
||
| # 3. Check skills have version field | ||
| for skill in plugins/*/skills/*/SKILL.md; do | ||
| if ! grep -q "^version:" "$skill"; then | ||
| echo "FAIL: Missing version in $skill" | ||
| ((ERRORS++)) | ||
| fi | ||
| done | ||
|
|
||
| # 4. Check hooks have matcher field | ||
| for hooks in plugins/*/hooks/hooks.json; do | ||
| if ! grep -q '"matcher"' "$hooks"; then | ||
| echo "FAIL: Missing matcher in $hooks" | ||
| ((ERRORS++)) | ||
| fi | ||
| done |
There was a problem hiding this comment.
Matcher validation is too weak (false‑pass risk).
grep -q '"matcher"' only proves the file contains a matcher, not that each required hook entry includes it. Use JSON-aware checks (e.g., jq) and validate per entry to avoid false compliance passes.
🔧 Proposed fix (per-entry matcher check)
-# 4. Check hooks have matcher field
-for hooks in plugins/*/hooks/hooks.json; do
- if ! grep -q '"matcher"' "$hooks"; then
- echo "FAIL: Missing matcher in $hooks"
- ((ERRORS++))
- fi
-done
+# 4. Check hooks have matcher field on every entry
+for hooks in plugins/*/hooks/hooks.json; do
+ missing=$(jq '[.[] | has("matcher")] | all' "$hooks" 2>/dev/null)
+ if [ "$missing" != "true" ]; then
+ echo "FAIL: Missing matcher on one or more entries in $hooks"
+ ((ERRORS++))
+ fi
+done📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ```bash | |
| #!/bin/bash | |
| # Plugin compliance validation | |
| ERRORS=0 | |
| # 1. Check agents have color field | |
| for agent in plugins/*/agents/*.md; do | |
| if ! grep -q "^color:" "$agent"; then | |
| echo "FAIL: Missing color in $agent" | |
| ((ERRORS++)) | |
| fi | |
| done | |
| # 2. Check agents have <example> blocks (at least 2) | |
| for agent in plugins/*/agents/*.md; do | |
| count=$(grep -c "<example>" "$agent" || echo 0) | |
| if [ "$count" -lt 2 ]; then | |
| echo "FAIL: Need 2+ examples in $agent (found $count)" | |
| ((ERRORS++)) | |
| fi | |
| done | |
| # 3. Check skills have version field | |
| for skill in plugins/*/skills/*/SKILL.md; do | |
| if ! grep -q "^version:" "$skill"; then | |
| echo "FAIL: Missing version in $skill" | |
| ((ERRORS++)) | |
| fi | |
| done | |
| # 4. Check hooks have matcher field | |
| for hooks in plugins/*/hooks/hooks.json; do | |
| if ! grep -q '"matcher"' "$hooks"; then | |
| echo "FAIL: Missing matcher in $hooks" | |
| ((ERRORS++)) | |
| fi | |
| done |
🤖 Prompt for AI Agents
In `@specs/refactor-plugins/design.md` around lines 300 - 337, The matcher check
is too weak—replace the grep-based check for hooks (the for loop over
plugins/*/hooks/hooks.json and the grep -q '"matcher"' call) with a JSON-aware
per-entry validation using jq: for each hooks.json run a jq query that iterates
over the hooks array (or object entries) and confirms every entry has a
non-empty "matcher" field, and if any entry is missing/empty increment ERRORS
and print a FAIL message referencing that hooks.json file; ensure the new check
lives where the current "# 4. Check hooks have matcher field" logic is and keeps
the same error counting behavior.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Adds walkthrough generation to spec agents per spec add-walk-through-of.
Summary
Changes
plugins/ralph-specum/templates/progress.mdplugins/ralph-specum/agents/research-analyst.mdplugins/ralph-specum/agents/product-manager.mdplugins/ralph-specum/agents/architect-reviewer.mdplugins/ralph-specum/agents/task-planner.mdTest plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Chores
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.