refactor(plugins): apply plugin-dev best practices

[tzachbon]

Summary

Refactors both ralph-specum and ralph-speckit plugins to follow plugin-dev best practices:

• 11 new skills created - Extracted procedural logic into reusable skills for DRY code
• Simplified commands/agents - Major commands reduced 70-81% (e.g., implement.md from 1235→233 lines)
• Metadata fixes - Added color, version, matcher, examples fields where missing
• Legacy migration - Migrated ralph-speckit legacy commands, removed .claude/commands directory

Phase A: Metadata Fixes

• Added color field to all 14 agents (blue/cyan=analysis, green=execution, yellow=validation, magenta=transformation)
• Added 2+ <example> blocks to all agents for proper triggering
• Added version: 0.1.0 to all 21 skills
• Added matcher: "*" to all hook entries
• Migrated 8 legacy commands from .claude/commands/ to commands/
• Removed legacy commands directory

Phase B: Skill Consolidation

New skills extracted from commands/agents:

• failure-recovery - Recovery orchestration from implement.md
• verification-layers - 4-layer verification pattern
• coordinator-pattern - Task delegation pattern
• branch-management - Branch/worktree workflow
• intent-classification - Goal type detection
• spec-scanner - Spec discovery logic
• parallel-research - Multi-agent parallel execution
• phase-rules - POC/Refactor/Testing/Quality phase behaviors
• commit-discipline - Commit conventions and rules
• quality-checkpoints - [VERIFY] task insertion rules
• quality-commands - Package.json/Makefile command discovery

Commands/agents now reference skills via <skill-reference> blocks, reducing duplication significantly.

Test Plan

• Validation script passes: bash scripts/validate-plugins.sh
  • 14/14 agents have color field
  • 14/14 agents have 2+ example blocks
  • 21/21 skills have version field
  • 2/2 hooks.json files have matcher field
  • 0 legacy commands directories found
• All acceptance criteria verified programmatically
• CI passes

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Adds an automated plugin validation script and several new documented skills/patterns to guide workflows.

• Improvements

  • Enhanced plugin metadata: agent color tags, richer examples, and standardized front-matter across commands and skills.
  • Consolidated many command/agent flows into reusable skill-driven patterns (coordinator, verification, branch/commit discipline, research, etc.).

• Updates

  • Plugin version bumps: ralph-specum → 2.11.1, ralph-speckit → 0.5.1.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@tzachbon has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 5 minutes and 4 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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.

📝 Walkthrough

Walkthrough

Bumps two plugin versions, adds an automated plugin validation script and CLAUDE.md guidance, augments agent/skill front-matter (colors, examples, versions), introduces many SKILL.md artifacts and branch/commit/workflow skills, standardizes command frontmatter/style, adds hook matcher fields, and adds refactor planning specs and progress docs.

Changes

Cohort / File(s)	Summary
Marketplace & Plugin Manifests /.claude-plugin/marketplace.json, plugins/ralph-specum/.claude-plugin/plugin.json, plugins/ralph-speckit/.claude-plugin/plugin.json	Bumped marketplace and per-plugin versions: ralph-specum 2.10.0 → 2.11.1; ralph-speckit 0.4.0 → 0.5.1.
Validation Script & CLAUDE.md scripts/validate-plugins.sh, CLAUDE.md	Added executable plugin validation script and expanded CLAUDE.md with plugin-validation checklist and agent color conventions.
Agent Frontmatter plugins/ralph-speckit/agents/.../*.md, plugins/ralph-specum/agents/.../*.md	Converted single-line descriptions to YAML block scalars, added color fields and example blocks across many agent docs.
Commands — Frontmatter & Style plugins/ralph-speckit/commands/*.md, plugins/ralph-specum/commands/*.md	Added/standardized frontmatter (name, allowed-tools, argument-hint), reordered handoffs, replaced typographic arrows with ->, and shifted procedural detail toward skill references.
Deleted Legacy Command plugins/ralph-speckit/.claude/commands/speckit.implement.md	Removed legacy speckit implementation markdown file.
Hook Config Changes plugins/ralph-speckit/hooks/hooks.json, plugins/ralph-specum/hooks/hooks.json	Added matcher: "*" entries to Stop and SessionStart hook configurations (global matcher).
New & Updated Skills plugins/ralph-specum/skills/*, plugins/ralph-speckit/skills/*	Added many SKILL.md docs (branch-management, commit-discipline, coordinator-pattern, failure-recovery, verification-layers, parallel-research, phase-rules, quality-checkpoints, quality-commands, spec-scanner, etc.) and added version: 0.1.0/expanded descriptions for several existing skills.
Refactor Specs & Progress specs/refactor-plugins/{requirements,research,design,tasks,.progress.md}	Added comprehensive refactor planning artifacts: requirements, research, design, multi‑phase tasks, and progress tracking.

Sequence Diagram(s)

sequenceDiagram
    participant Runner as Runner (scripts/validate-plugins.sh)
    participant FS as File System / Repo
    participant Plugin as Plugin Dir (ralph-*/)
    participant Hooks as hooks.json

    Runner->>FS: enumerate plugin directories
    loop per-plugin
      Runner->>Plugin: read agent/skill .md files and hooks
      Plugin-->>Runner: frontmatter (color, examples, version) / hooks.json
      Runner->>Hooks: validate hooks.json matcher fields
      Runner->>Plugin: check skills for version, agents for examples/colors, legacy .claude/commands
      Plugin-->>Runner: pass/fail per-check
    end
    Runner->>Runner: aggregate results and print colored summary
    Runner-->>FS: exit with 0 if all pass, else exit 1

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• feat: Adaptive Interview System #65 — Overlaps many of the same command docs and skill refactors (start/research/requirements/design/tasks) and the new skill patterns.
• Enforce parallel execution in research command with detailed guidance #73 — Directly touches plugins/ralph-specum/commands/research.md and related parallel-research guidance (high overlap).
• Fix Ralph character name reference #62 — Related plugin manifest/version updates for ralph-* plugins (matches this PR's version bumps).

Poem

🐰 I hopped through manifests, docs, and hooks,

I left bright colors in agent books,
I planted skills where long guides sprawled,
A validator watches, tidy and tall,
Refactor carrots gathered—one and all.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'refactor(plugins): apply plugin-dev best practices' clearly and directly summarizes the main change: refactoring plugins to follow established best practices.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/refactor-plugins

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 11

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

plugins/ralph-speckit/commands/cancel.md (1)

2-36: ⚠️ Potential issue | 🟠 Major

allowed-tools doesn’t permit the Skill tool referenced in steps.

The command instructs using the Skill tool, but allowed-tools omits it—this will fail under tool gating. Add Skill (or change the instruction to a permitted tool). Also fixes the duplicate “loop” wording.

🔧 Proposed fix

-allowed-tools: [Read, Bash, Task]
+allowed-tools: [Read, Bash, Task, Skill]
@@
-1. Stop Ralph Loop loop (if running):
+1. Stop Ralph Loop (if running):

plugins/ralph-speckit/agents/qa-engineer.md (1)

309-318: ⚠️ Potential issue | 🟠 Major

Avoid VERIFICATION_PASS when all verification commands are skipped.

If every command is skipped (e.g., missing executables), this produces a false green without any real verification. Prefer failing so the task is retried or corrected.

🔧 Suggested adjustment

-| All commands SKIP | Output VERIFICATION_PASS (no failures) |
+| All commands SKIP | Output VERIFICATION_FAIL (no verification executed) |

plugins/ralph-specum/commands/requirements.md (1)

1-85: ⚠️ Potential issue | 🟠 Major

Bump plugin versions in both plugin.json and marketplace.json.

The command file requirements.md was modified, but the plugin versions were not updated. According to coding guidelines, you must bump the version in BOTH plugins/ralph-specum/.claude-plugin/plugin.json and ./.claude-plugin/marketplace.json (ralph-specum entry) whenever ANY changes are made to plugin files (commands, agents, hooks, templates, schemas). Update both versions using semantic versioning appropriate to the changes made.

🤖 Fix all issues with AI agents

In `@plugins/ralph-speckit/agents/task-planner.md`:
- Around line 1-21: The agent change requires a patch version bump in both
plugin manifest files: open plugins/ralph-speckit/.claude-plugin/plugin.json and
./.claude-plugin/marketplace.json, locate the "version" field (currently 0.5.0)
and update it to 0.5.1 so both files match, save and commit the two files
alongside the agent change; ensure the same semantic version string is used in
both manifests (plugin.json and marketplace.json).

In `@plugins/ralph-speckit/commands/tasks.md`:
- Around line 96-101: Update the first "CORRECT" example line "- [ ] T001 Create
project structure per implementation plan" so it includes a file path consistent
with the rule and the other examples (e.g., append a path like "in
src/<appropriate_file>.py" or add "in src/<dir>/README.md"); ensure the task ID
"T001" remains and formatting matches the other examples such as "- [ ] T005 [P]
Implement authentication middleware in src/middleware/auth.py".

In `@plugins/ralph-specum/commands/start.md`:
- Around line 147-152: The markdown table containing the keys `problem`,
`constraints`, `success`, and `additionalContext` has pipes with no surrounding
spaces which triggers MD060; update the table so each cell pipe has a single
space on both sides (e.g., "| 1 | What problem... | Required | `problem` |")
including the header and separator rows to satisfy markdownlint spacing rules.

In `@plugins/ralph-specum/skills/intent-classification/SKILL.md`:
- Around line 47-105: Tables in SKILL.md have pipes without spaces which
triggers markdownlint MD060; update each Markdown table (for example the headers
"Keyword | Confidence Boost", "Match Count | Confidence | Action", and "Intent |
Min Questions | Max Questions") to have a single space before and after every
pipe delimiter (e.g., "Keyword | Confidence Boost" -> "Keyword | Confidence
Boost"), and ensure all rows follow the same spacing convention so each pipe is
surrounded by spaces throughout the file.

In `@plugins/ralph-specum/skills/quality-commands/SKILL.md`:
- Around line 74-79: The markdown table in SKILL.md uses compact pipe spacing
that triggers MD060; update the table rows (the block showing File Exists |
Package Manager | Run Prefix around the `pnpm-lock.yaml`, `yarn.lock`,
`bun.lockb`, `package-lock.json` entries) and the second table at lines ~127-133
to use a single space on both sides of each pipe (e.g., " | " between columns)
and align columns consistently so markdownlint MD060 is satisfied; ensure the
header separator row also has matching spacing (the row with dashes and pipes)
to keep the table format valid.
- Line 47: Update the heading "### 3. CI Configs (.github/workflows/*.yml)" to
capitalize GitHub (change "CI Configs" line to "### 3. CI Configs
(GitHub/.github/workflows/*.yml)" or simply "### 3. CI Configs
(.github/workflows/*.yml) — GitHub" as appropriate); locate the heading text
string in SKILL.md and replace the lowercase "GitHub" instance to "GitHub" so
the heading correctly capitalizes the platform name.

In `@plugins/ralph-specum/skills/spec-scanner/SKILL.md`:
- Around line 198-211: The Example 3 matching is incorrect because the "Keywords
extracted" list (the Keywords extracted entry) does not contain "jwt" yet the
"Matching" section claims user-auth has 3 matches including "jwt"; update the
"Matching" section to only count actual overlaps with the extracted keywords
(e.g., set user-auth to 2 matches for "authentication" and "token",
token-refresh to 2, api-auth to 1 or 2 depending on overlaps) or explicitly
state that a stemming/fuzzy match was used and document that behavior;
specifically edit the "Keywords extracted" and "Matching" blocks in Example 3
and adjust the user-auth, token-refresh, and api-auth match counts and
matched-terms to be consistent.

In `@scripts/validate-plugins.sh`:
- Around line 26-34: The arithmetic increments in log_fail and log_warn (the
((errors++)) and ((warnings++)) calls) can cause the script to exit under set -e
because ((errors++)) returns the old value (0) as the exit status; change these
to a safe increment that never yields a zero exit status such as assigning the
incremented value (e.g., errors=$((errors+1)) and warnings=$((warnings+1))) so
log_fail and log_warn update the counters without triggering set -e; update both
functions accordingly.

In `@specs/refactor-plugins/requirements.md`:
- Around line 15-19: The Markdown tables in this file (e.g., the table row
starting with "Primary users | Both developers and end users" and the rows for
"Priority tradeoffs" and "Success criteria") use compact pipe separators that
trigger MD060; update these table rows and any other tables in the file to
include a single space before and after each pipe (e.g., " | ") and ensure
consistent spacing for the header separator line as well so all table pipes have
surrounding spaces throughout the document.

In `@specs/refactor-plugins/tasks.md`:
- Around line 10-511: The spec currently defines five phases (Phase 1..5) but
must follow the repo standard four-phase POC-first workflow; update
specs/refactor-plugins/tasks.md to consolidate the PR lifecycle/PR creation and
monitoring steps (the content under "Phase 5: PR Lifecycle" and the PR steps in
"Phase 4: Quality Gates" / item 4.2) into the Phase 4 "Quality Gates" section or
move them to a Notes/Appendix section, and rename/ensure the top-level headings
match exactly: Phase 1: Make It Work (POC), Phase 2: Refactoring, Phase 3:
Testing, Phase 4: Quality Gates; adjust or remove the separate "Phase 5" heading
and ensure references to PR steps (4.2, 5.1, PR creation/monitoring) are present
only under Phase 4 or an appendix so the document enforces the required 4‑phase
workflow.
- Around line 561-565: The markdown table in specs/refactor-plugins/tasks.md
violates MD060 because the pipe characters in the header and rows lack
consistent spaces; update the three table lines (the header line "| Phase |
Files Changed | Files Created | Files Deleted |" the separator
"|-------|---------------|---------------|---------------|" and each data row "|
Phase A | 32 | 9 | 9 |", "| Phase B | 10 | 11 | 0 |", "| **Total** | **42** |
**20** | **9** |") so that there is a single space before and after each pipe
delimiter (i.e., ensure " | " between columns) to satisfy markdownlint spacing
rules.

🧹 Nitpick comments (4)

plugins/ralph-specum/skills/intent-classification/SKILL.md (1)

76-190: Align examples and tie‑break behavior with the keyword rules.

Example 2 lists “new” as a matched keyword, but “new” isn’t present in the GREENFIELD table; also, tie‑break behavior is implicit (TRIVIAL wins on equal scores). Please either add “new” to the table or update the example, and document tie‑break priority explicitly to avoid ambiguity.

Also applies to: 112-133

plugins/ralph-speckit/skills/speckit-workflow/SKILL.md (1)

3-120: Align phase model with the required 4-phase POC-first workflow.
This doc defines a 6‑phase flow, which conflicts with the required 4‑phase model. Consider mapping or reconciling the phases so the skill reflects the mandated workflow.

Based on learnings: "All specs must follow the 4-phase POC-first workflow: Phase 1 (Make It Work - POC validation, skip tests), Phase 2 (Refactoring - code cleanup), Phase 3 (Testing - unit, integration, e2e), Phase 4 (Quality Gates - lint, types, CI, PR)".

plugins/ralph-specum/skills/spec-workflow/SKILL.md (1)

3-45: Reconcile phase naming with the 4‑phase POC‑first workflow.
Current phase labels don’t align with the mandated 4‑phase model; consider adding a mapping or updating the phase flow to match.

Based on learnings: "All specs must follow the 4-phase POC-first workflow: Phase 1 (Make It Work - POC validation, skip tests), Phase 2 (Refactoring - code cleanup), Phase 3 (Testing - unit, integration, e2e), Phase 4 (Quality Gates - lint, types, CI, PR)".

plugins/ralph-specum/skills/branch-management/SKILL.md (1)

200-209: Consider tightening the default branch protection exception.

The mandatory block correctly prohibits direct pushes to the default branch, but Line 208 introduces an exception "if the user explicitly requests pushing to the default branch." This loophole could undermine the protection policy, as users might request it without fully understanding the consequences.

Consider one of these approaches:

• Remove the exception entirely and require feature branches in all cases
• Add additional verification steps (e.g., require confirmation with a warning about team workflow implications)
• Document specific scenarios where direct pushes are acceptable (e.g., hotfixes, single-maintainer repos)

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find and inspect plugin.json for ralph-speckit
echo "=== ralph-speckit plugin.json ==="
find plugins/ralph-speckit -name "plugin.json" -type f | head -5
find plugins/ralph-speckit -name "plugin.json" -type f -exec cat {} \;

echo -e "\n=== marketplace.json search ==="
find . -name "marketplace.json" -type f | head -10
find . -name "marketplace.json" -type f -exec cat {} \; 2>/dev/null | head -100

Repository: tzachbon/smart-ralph

Length of output: 1642

---

🏁 Script executed:

#!/bin/bash
# Check git diff for version changes
echo "=== Git diff for plugin.json ==="
git diff plugins/ralph-speckit/.claude-plugin/plugin.json

echo -e "\n=== Git diff for marketplace.json ==="
git diff ./.claude-plugin/marketplace.json

Repository: tzachbon/smart-ralph

Length of output: 135

---

Version bumps required: Plugin.json and marketplace.json were not updated for this agent change.

The agent file plugins/ralph-speckit/agents/task-planner.md was modified, but neither plugins/ralph-speckit/.claude-plugin/plugin.json nor ./.claude-plugin/marketplace.json were updated. Per coding guidelines, you must bump the version in BOTH files whenever making ANY changes to agent files. Consider incrementing from 0.5.0 to 0.5.1 (patch) using semantic versioning unless this is part of a larger feature release.

🤖 Prompt for AI Agents

In `@plugins/ralph-speckit/agents/task-planner.md` around lines 1 - 21, The agent
change requires a patch version bump in both plugin manifest files: open
plugins/ralph-speckit/.claude-plugin/plugin.json and
./.claude-plugin/marketplace.json, locate the "version" field (currently 0.5.0)
and update it to 0.5.1 so both files match, save and commit the two files
alongside the agent change; ensure the same semantic version string is used in
both manifests (plugin.json and marketplace.json).

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Align spec phases to the required 4‑phase POC‑first workflow.

This spec defines five phases, but the repo standard mandates exactly four (POC → Refactor → Testing → Quality Gates). Please merge PR lifecycle steps into Phase 4 or move them to Notes/appendix.

Based on learnings: “All specs must follow the 4-phase POC-first workflow: Phase 1 (Make It Work - POC validation, skip tests), Phase 2 (Refactoring - code cleanup), Phase 3 (Testing - unit, integration, e2e), Phase 4 (Quality Gates - lint, types, CI, PR)”.

🤖 Prompt for AI Agents

In `@specs/refactor-plugins/tasks.md` around lines 10 - 511, The spec currently
defines five phases (Phase 1..5) but must follow the repo standard four-phase
POC-first workflow; update specs/refactor-plugins/tasks.md to consolidate the PR
lifecycle/PR creation and monitoring steps (the content under "Phase 5: PR
Lifecycle" and the PR steps in "Phase 4: Quality Gates" / item 4.2) into the
Phase 4 "Quality Gates" section or move them to a Notes/Appendix section, and
rename/ensure the top-level headings match exactly: Phase 1: Make It Work (POC),
Phase 2: Refactoring, Phase 3: Testing, Phase 4: Quality Gates; adjust or remove
the separate "Phase 5" heading and ensure references to PR steps (4.2, 5.1, PR
creation/monitoring) are present only under Phase 4 or an appendix so the
document enforces the required 4‑phase workflow.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix markdown table spacing (MD060).

The table pipes lack spacing, which markdownlint flags.

✅ Suggested fix

-| Phase | Files Changed | Files Created | Files Deleted |
-|-------|---------------|---------------|---------------|
-| Phase A | 32 | 9 | 9 |
-| Phase B | 10 | 11 | 0 |
-| **Total** | **42** | **20** | **9** |
+| Phase | Files Changed | Files Created | Files Deleted |
+|-------|---------------|---------------|---------------|
+| Phase A | 32 | 9 | 9 |
+| Phase B | 10 | 11 | 0 |
+| **Total** | **42** | **20** | **9** |

🧰 Tools

🪛 markdownlint-cli2 (0.20.0)

[warning] 562-562: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 562-562: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

---

[warning] 562-562: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 562-562: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

---

[warning] 562-562: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 562-562: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

---

[warning] 562-562: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 562-562: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

🤖 Prompt for AI Agents

In `@specs/refactor-plugins/tasks.md` around lines 561 - 565, The markdown table
in specs/refactor-plugins/tasks.md violates MD060 because the pipe characters in
the header and rows lack consistent spaces; update the three table lines (the
header line "| Phase | Files Changed | Files Created | Files Deleted |" the
separator "|-------|---------------|---------------|---------------|" and each
data row "| Phase A | 32 | 9 | 9 |", "| Phase B | 10 | 11 | 0 |", "| **Total** |
**42** | **20** | **9** |") so that there is a single space before and after
each pipe delimiter (i.e., ensure " | " between columns) to satisfy markdownlint
spacing rules.

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

plugins/ralph-specum/commands/start.md (1)

102-109: ⚠️ Potential issue | 🟠 Major

Align phase model with required 4-phase POC-first workflow.

The phase list and state initialization omit the required phases (POC validation, refactoring, testing, quality gates), which conflicts with the mandated workflow. Please update the phase taxonomy and flow steps to include Phase 1–4 explicitly.

💡 Suggested direction (update phases and state)

-| Phase | Action |
-|-------|--------|
-| research | Invoke research-analyst agent |
-| requirements | Invoke product-manager agent |
-| design | Invoke architect-reviewer agent |
-| tasks | Invoke task-planner agent |
-| execution | Invoke spec-executor for current task |
+| Phase | Action |
+|-------|--------|
+| poc | Invoke research-analyst agent; validate POC (skip tests) |
+| refactor | Invoke architect-reviewer agent; clean up and harden |
+| testing | Invoke qa-engineer agent; unit/integration/e2e |
+| quality-gates | Run lint/types/CI/PR checks |

-6. Initialize `.ralph-state.json` with phase "research"
+6. Initialize `.ralph-state.json` with phase "poc"

Based on learnings: “All specs must follow the 4-phase POC-first workflow: Phase 1 (Make It Work - POC validation, skip tests), Phase 2 (Refactoring - code cleanup), Phase 3 (Testing - unit, integration, e2e), Phase 4 (Quality Gates - lint, types, CI, PR)”.

Also applies to: 124-124

plugins/ralph-speckit/agents/qa-engineer.md (1)

311-317: ⚠️ Potential issue | 🟠 Major

Align “command not found” handling with VERIFICATION_FAIL rules.

The mandatory section states any verification command failure should yield VERIFICATION_FAIL, but the error table says “Command not found” is SKIP. That inconsistency can allow missing commands to pass.

🛠️ Suggested fix

-| Command not found | Mark as SKIP, log warning, continue |
+| Command not found | Mark as FAIL, report missing command |

🤖 Fix all issues with AI agents

In `@plugins/ralph-speckit/agents/qa-engineer.md`:
- Around line 1-21: The plugin’s version in plugin.json needs to be bumped
because agents/qa-engineer.md for the ralph-speckit plugin was modified; open
the plugin.json for the ralph-speckit plugin, update the "version" field to a
new valid semver (increment patch for a fix, minor for a feature, major for
breaking change), save and commit the change so the plugin version reflects the
agents/qa-engineer.md modification.

In `@plugins/ralph-specum/skills/quality-commands/SKILL.md`:
- Around line 41-43: Replace the overly restrictive grep pattern '^[a-z]+:' in
the SKILL.md example with a broader pattern that also matches digits, hyphens,
underscores and dots (e.g. grep -E '^[A-Za-z0-9._-]+:' Makefile) so targets like
test-unit, build_app or e2e are not missed; update the literal pattern string in
the doc (the grep example) to this new regex.

In `@plugins/ralph-specum/skills/spec-scanner/SKILL.md`:
- Around line 82-89: The tables in SKILL.md use compact pipe separators causing
markdownlint MD060 errors; update every table (including the "Stop Words",
"Scoring Rules" and "Edge Cases" tables) to add a single space before and after
each pipe and ensure each separator row uses the same column dashes and spacing
style (e.g., "| --- | --- |") so the header, separator, and data rows are
consistently spaced across the file.

In `@scripts/validate-plugins.sh`:
- Around line 84-95: The current check uses grep -q '"matcher"' which can be
fooled by unrelated strings; replace it with a jq-based validation on hooks_file
that asserts every hook object contains the matcher key (e.g., use jq -e
'all(.hooks[]; has("matcher"))' or 'all(.[]; has("matcher"))' depending on the
schema) and then call log_pass or log_fail for that hooks_file/plugin_name
accordingly; update the conditional that references hooks_file and keep using
PLUGINS_DIR, plugin_name, log_pass and log_fail to locate and report the result.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find and display plugin.json and marketplace.json versions in ralph-speckit
echo "=== Checking plugin.json versions ==="
fd -a 'plugin.json' plugins/ralph-speckit -x cat {} 2>/dev/null | head -50

echo ""
echo "=== Checking marketplace.json versions ==="
fd -a 'marketplace.json' plugins/ralph-speckit -x cat {} 2>/dev/null | head -50

Repository: tzachbon/smart-ralph

Length of output: 145

---

🏁 Script executed:

#!/bin/bash
# List the structure of ralph-speckit plugin
echo "=== Structure of plugins/ralph-speckit ==="
find plugins/ralph-speckit -type f -name "*.json" | head -20

echo ""
echo "=== Full directory tree of plugins/ralph-speckit ==="
tree plugins/ralph-speckit -L 3 2>/dev/null || find plugins/ralph-speckit -type f | sort

echo ""
echo "=== Search for all plugin.json files in repository ==="
fd -a 'plugin.json' plugins/ 

echo ""
echo "=== Search for all marketplace.json files in repository ==="
fd -a 'marketplace.json' plugins/

Repository: tzachbon/smart-ralph

Length of output: 1384

---

🏁 Script executed:

#!/bin/bash
# Read the plugin.json file to check versioning
echo "=== Content of plugin.json ==="
cat plugins/ralph-speckit/.claude-plugin/plugin.json

Repository: tzachbon/smart-ralph

Length of output: 472

---

🏁 Script executed:

#!/bin/bash
# Check git status/diff to see if plugin.json was modified in this PR
echo "=== Check git diff for plugin.json ==="
git diff HEAD -- plugins/ralph-speckit/.claude-plugin/plugin.json 2>/dev/null || echo "No git diff available"

echo ""
echo "=== Check git status ==="
git status plugins/ralph-speckit/.claude-plugin/plugin.json 2>/dev/null || echo "No git status available"

echo ""
echo "=== Check recent commits touching plugin.json ==="
git log --oneline -5 -- plugins/ralph-speckit/.claude-plugin/plugin.json 2>/dev/null || echo "No git log available"

echo ""
echo "=== Check if any changes exist in staging or working tree ==="
git diff --name-only 2>/dev/null | grep -E "(plugin\.json|marketplace\.json)" || echo "No plugin metadata changes in diff"

Repository: tzachbon/smart-ralph

Length of output: 392

---

Bump plugin version for this agent change.

The file plugins/ralph-speckit/agents/qa-engineer.md requires a version bump to plugin.json (plugins/ralph-speckit/.claude-plugin/plugin.json) since changes to agent files trigger the version bump requirement. According to the coding guidelines, all modifications to files in plugins/*/agents/ must have the plugin version updated. Please bump the version using semantic versioning (patch for fixes, minor for features, major for breaking changes).

🤖 Prompt for AI Agents

In `@plugins/ralph-speckit/agents/qa-engineer.md` around lines 1 - 21, The
plugin’s version in plugin.json needs to be bumped because agents/qa-engineer.md
for the ralph-speckit plugin was modified; open the plugin.json for the
ralph-speckit plugin, update the "version" field to a new valid semver
(increment patch for a fix, minor for a feature, major for breaking change),
save and commit the change so the plugin version reflects the
agents/qa-engineer.md modification.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Broaden the Makefile target regex to avoid missing common targets.

^[a-z]+: skips targets like test-unit, build_app, or e2e. Consider matching common target characters.

♻️ Suggested tweak

-grep -E '^[a-z]+:' Makefile
+grep -E '^[[:alnum:]_-]+:' Makefile

🤖 Prompt for AI Agents

In `@plugins/ralph-specum/skills/quality-commands/SKILL.md` around lines 41 - 43,
Replace the overly restrictive grep pattern '^[a-z]+:' in the SKILL.md example
with a broader pattern that also matches digits, hyphens, underscores and dots
(e.g. grep -E '^[A-Za-z0-9._-]+:' Makefile) so targets like test-unit, build_app
or e2e are not missed; update the literal pattern string in the doc (the grep
example) to this new regex.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix table pipe spacing to satisfy markdownlint (MD060).

The tables in this file still use compact separators. Please add spaces around pipes and keep the separator rows consistent across all tables (Stop Words, Scoring Rules, Edge Cases).

🧹 Example fix (apply to all tables)

-|----------|-------|
+| -------- | ----- |

📝 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

	| Category | Words |
	|----------|-------|
	| Articles | the, a, an |
	| Prepositions | to, for, with, on, in, of |
	| Conjunctions | and, or |
	| Pronouns | it, this, that |
	| Verbs (common) | is, be |
	| Category | Words |
	| -------- | ----- |
	| Articles | the, a, an |
	| Prepositions | to, for, with, on, in, of |
	| Conjunctions | and, or |
	| Pronouns | it, this, that |
	| Verbs (common) | is, be |

🧰 Tools

🪛 markdownlint-cli2 (0.20.0)

[warning] 83-83: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 83-83: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

---

[warning] 83-83: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 83-83: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

🤖 Prompt for AI Agents

In `@plugins/ralph-specum/skills/spec-scanner/SKILL.md` around lines 82 - 89, The
tables in SKILL.md use compact pipe separators causing markdownlint MD060
errors; update every table (including the "Stop Words", "Scoring Rules" and
"Edge Cases" tables) to add a single space before and after each pipe and ensure
each separator row uses the same column dashes and spacing style (e.g., "| --- |
--- |") so the header, separator, and data rows are consistently spaced across
the file.

[tzachbon]

hit to use gh cli as fallback

[coderabbitai]

Actionable comments posted: 6

🤖 Fix all issues with AI agents

In `@plugins/ralph-specum/commands/design.md`:
- Line 26: Reword step 3 to explicitly list the sequence of operations: first
read the `.ralph-state.json` file, then set the awaitingApproval property to
false, and finally write the updated JSON back to disk (i.e., "Read
`.ralph-state.json`, set `awaitingApproval: false`, and write back"). Mention
the `.ralph-state.json` file and the awaitingApproval field so implementers know
exactly which file/field to modify.

In `@plugins/ralph-specum/commands/requirements.md`:
- Around line 67-73: Replace the bold-as-heading "Skip if --quick flag." in the
"Review Loop" section with a proper Markdown heading (e.g., "Skip if --quick
flag") followed by a normal sentence explaining to ask the user to review
generated requirements and to re-invoke the product-manager with feedback until
approved; keep the existing note about skipping when --quick is provided and
ensure the "Update State" instruction that writes .ralph-state.json remains
unchanged.
- Around line 40-49: The markdown table under the "### Requirements Interview
Question Pool" header needs surrounding blank lines and consistent spacing
around pipe characters to satisfy MD058/MD060; edit the table rows and header
(including the separator row with ---) so each cell is separated by a single
space on both sides of "|" (e.g., " | ") and add one blank line before the table
and one blank line after it (the table stores responses in `.progress.md` under
"### Requirements Interview (from requirements.md)"—ensure that heading remains
intact and the `primaryUsers`, `priorityTradeoffs`, `successCriteria`, and
`additionalReqContext` keys and options columns keep the same content while you
normalize the pipe spacing and blank lines).

In `@plugins/ralph-specum/commands/research.md`:
- Around line 92-122: The markdown tables in the Research template are missing
separator rows; after each header row — "| Spec | Relevance | Relationship | May
Need Update |", "| Type | Command | Source |", and "| Aspect | Assessment |
Notes |" — insert the corresponding Markdown separator row (e.g. "| --- | --- |
--- | --- |", "| --- | --- | --- |", and "| --- | --- | --- |") immediately
beneath each header so the tables render correctly; update the template around
the "Related Specs", "Quality Commands", and "Feasibility Assessment" sections
accordingly.

In `@plugins/ralph-specum/commands/tasks.md`:
- Around line 46-49: The {goal} placeholder in the interview questions is
ambiguous; update the tasks.md "Gather Context" section to explicitly define how
{goal} is populated by stating that goal is extracted from the requirements.md
(e.g., "goal = extract primary objective from requirements.md"), or
alternatively note that {goal} is a literal shown to users—add this
clarification next to the "Gather Context" heading and reference the {goal}
placeholder so readers know to pull it from requirements.md (or that it will be
displayed verbatim).
- Around line 35-38: Update the skill-reference entry in
plugins/ralph-specum/commands/tasks.md to use the full repository-root path:
replace the relative `skills/interview-framework/SKILL.md` with
`plugins/ralph-specum/skills/interview-framework/SKILL.md` inside the
<skill-reference> block so it matches the convention used in start.md,
research.md, and implement.md; ensure the token `Apply skill` text remains
unchanged aside from the path.

🧹 Nitpick comments (1)

plugins/ralph-specum/commands/design.md (1)

43-49: Optional: Fix table formatting for consistency.

Static analysis detected minor table formatting issues: missing blank line around the table and missing spaces around pipe characters. While these don't affect functionality, fixing them would improve consistency with markdown style guidelines.

📋 Proposed formatting fix

 | 3 | How should this integrate with existing systems? | Required | `integrationApproach` | Use existing APIs / Create new layer / Minimal integration / Other |
 | 4 | Any other design context? (or 'done') | Optional | `additionalDesignContext` | No, proceed / Yes, more details / Other |
+
-Store responses in `.progress.md` under `### Design Interview (from design.md)`
+Store responses in `.progress.md` under `### Design Interview (from design.md)`

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Clarify the read-and-update operation sequence.

The instruction "Read .ralph-state.json and clear approval flag" describes two operations but is phrased as a single step. Consider being explicit about the sequence: "Read .ralph-state.json, set awaitingApproval: false, and write back" to prevent ambiguity during execution.

✍️ Suggested clarification

-3. Read `.ralph-state.json` and clear approval flag: `awaitingApproval: false`
+3. Read `.ralph-state.json`, set `awaitingApproval: false`, and write back

📝 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

	3. Read `.ralph-state.json` and clear approval flag: `awaitingApproval: false`
	3. Read `.ralph-state.json`, set `awaitingApproval: false`, and write back

🤖 Prompt for AI Agents

In `@plugins/ralph-specum/commands/design.md` at line 26, Reword step 3 to
explicitly list the sequence of operations: first read the `.ralph-state.json`
file, then set the awaitingApproval property to false, and finally write the
updated JSON back to disk (i.e., "Read `.ralph-state.json`, set
`awaitingApproval: false`, and write back"). Mention the `.ralph-state.json`
file and the awaitingApproval field so implementers know exactly which
file/field to modify.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix table formatting (blank lines + pipe spacing).
markdownlint flags MD058/MD060 around the question pool table. Add blank lines around the table and ensure spaces around pipes.

🔧 Proposed markdown fixes

 ### Requirements Interview Question Pool
-
-| # | Question | Required | Key | Options |
-|---|----------|----------|-----|---------|
-| 1 | Who are the primary users of this feature? | Required | `primaryUsers` | Internal devs / End users via UI / Both / Other |
-| 2 | What priority tradeoffs for {goal}? | Required | `priorityTradeoffs` | Speed of delivery / Code quality / Feature completeness / Other |
-| 3 | What defines success for this feature? | Required | `successCriteria` | Works as specified / High performance / User satisfaction / Other |
-| 4 | Any other requirements context? (or 'done') | Optional | `additionalReqContext` | No, proceed / Yes, more details / Other |
-
-Store responses in `.progress.md` under `### Requirements Interview (from requirements.md)`
+
+| # | Question | Required | Key | Options |
+| --- | --- | --- | --- | --- |
+| 1 | Who are the primary users of this feature? | Required | `primaryUsers` | Internal devs / End users via UI / Both / Other |
+| 2 | What priority tradeoffs for {goal}? | Required | `priorityTradeoffs` | Speed of delivery / Code quality / Feature completeness / Other |
+| 3 | What defines success for this feature? | Required | `successCriteria` | Works as specified / High performance / User satisfaction / Other |
+| 4 | Any other requirements context? (or 'done') | Optional | `additionalReqContext` | No, proceed / Yes, more details / Other |
+
+Store responses in `.progress.md` under `### Requirements Interview (from requirements.md)`

📝 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

	### Requirements Interview Question Pool
	| # | Question | Required | Key | Options |
	|---|----------|----------|-----|---------|
	| 1 | Who are the primary users of this feature? | Required | `primaryUsers` | Internal developers only / End users via UI / Both developers and end users / Other |
	| 2 | What priority tradeoffs should we consider for {goal}? | Required | `priorityTradeoffs` | Prioritize speed of delivery / Prioritize code quality and maintainability / Prioritize feature completeness / Other |
	| 3 | What defines success for this feature? | Required | `successCriteria` | Feature works as specified / High performance/reliability required / User satisfaction metrics / Other |
	| 4 | Any other requirements context? (or say 'done' to proceed) | Optional | `additionalReqContext` | No, let's proceed / Yes, I have more details / Other |
	### Store Requirements Interview Responses
	After interview, append to `.progress.md` under the "Interview Responses" section:
	```markdown
	### Requirements Interview (from requirements.md)
	- Primary users: [responses.primaryUsers]
	- Priority tradeoffs: [responses.priorityTradeoffs]
	- Success criteria: [responses.successCriteria]
	- Additional requirements context: [responses.additionalReqContext]
	[Any follow-up responses from "Other" selections]
	```
	| 1 | Who are the primary users of this feature? | Required | `primaryUsers` | Internal devs / End users via UI / Both / Other |
	| 2 | What priority tradeoffs for {goal}? | Required | `priorityTradeoffs` | Speed of delivery / Code quality / Feature completeness / Other |
	| 3 | What defines success for this feature? | Required | `successCriteria` | Works as specified / High performance / User satisfaction / Other |
	| 4 | Any other requirements context? (or 'done') | Optional | `additionalReqContext` | No, proceed / Yes, more details / Other |
	### Interview Context Format
	Pass the combined context (prior + new responses) to the Task delegation prompt:
	```text
	Interview Context:
	- Primary users: [Answer]
	- Priority tradeoffs: [Answer]
	- Success criteria: [Answer]
	- Follow-up details: [Any additional clarifications]
	```
	Store this context to include in the Task delegation prompt.
	Store responses in `.progress.md` under `### Requirements Interview (from requirements.md)`
	### Requirements Interview Question Pool
	| # | Question | Required | Key | Options |
	| --- | --- | --- | --- | --- |
	| 1 | Who are the primary users of this feature? | Required | `primaryUsers` | Internal devs / End users via UI / Both / Other |
	| 2 | What priority tradeoffs for {goal}? | Required | `priorityTradeoffs` | Speed of delivery / Code quality / Feature completeness / Other |
	| 3 | What defines success for this feature? | Required | `successCriteria` | Works as specified / High performance / User satisfaction / Other |
	| 4 | Any other requirements context? (or 'done') | Optional | `additionalReqContext` | No, proceed / Yes, more details / Other |
	Store responses in `.progress.md` under `### Requirements Interview (from requirements.md)`

🧰 Tools

🪛 markdownlint-cli2 (0.20.0)

[warning] 48-48: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

[warning] 49-49: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 49-49: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

---

[warning] 49-49: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 49-49: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

---

[warning] 49-49: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 49-49: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

---

[warning] 49-49: Table column style
Table pipe is missing space to the right for style "compact"

(MD060, table-column-style)

---

[warning] 49-49: Table column style
Table pipe is missing space to the left for style "compact"

(MD060, table-column-style)

🤖 Prompt for AI Agents

In `@plugins/ralph-specum/commands/requirements.md` around lines 40 - 49, The
markdown table under the "### Requirements Interview Question Pool" header needs
surrounding blank lines and consistent spacing around pipe characters to satisfy
MD058/MD060; edit the table rows and header (including the separator row with
---) so each cell is separated by a single space on both sides of "|" (e.g., " |
") and add one blank line before the table and one blank line after it (the
table stores responses in `.progress.md` under "### Requirements Interview (from
requirements.md)"—ensure that heading remains intact and the `primaryUsers`,
`priorityTradeoffs`, `successCriteria`, and `additionalReqContext` keys and
options columns keep the same content while you normalize the pipe spacing and
blank lines).

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Avoid bold-as-heading in review loop.
markdownlint MD036 flags the bold sentence; use a heading + sentence instead.

✍️ Proposed tweak

-**Skip if --quick flag.** Ask user to review generated requirements. If changes needed, invoke product-manager again with feedback and repeat until approved.
+### Quick mode
+Skip if --quick flag. Ask user to review generated requirements. If changes needed, invoke product-manager again with feedback and repeat until approved.

📝 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

	## Review Loop
	Check if `--quick` appears anywhere in `$ARGUMENTS`. If present, skip directly to "Update State".
	### Requirements Review Questions
	After the requirements have been created by the product-manager agent, ask the user to review them and provide feedback.
	**Review Question Flow:**
	1. **Read the generated requirements.md** to understand what was created
	2. **Ask initial review questions** to confirm the requirements meet their expectations:
	| # | Question | Key | Options |
	|---|----------|-----|---------|
	| 1 | Do the user stories capture your intended functionality? | `userStoriesApproval` | Yes, complete / Missing some stories / Need refinement / Other |
	| 2 | Are the acceptance criteria clear and testable? | `acceptanceCriteriaApproval` | Yes, clear / Need more details / Some are unclear / Other |
	| 3 | Are the priorities and scope appropriate? | `prioritiesApproval` | Yes, appropriate / Need adjustment / Missing items / Other |
	| 4 | Any other feedback on the requirements? (or say 'approved' to proceed) | `requirementsFeedback` | Approved, let's proceed / Yes, I have feedback / Other |
	### Store Requirements Review Responses
	After review questions, append to `.progress.md` under a new section:
	```markdown
	### Requirements Review (from requirements.md)
	- User stories approval: [responses.userStoriesApproval]
	- Acceptance criteria approval: [responses.acceptanceCriteriaApproval]
	- Priorities approval: [responses.prioritiesApproval]
	- Requirements feedback: [responses.requirementsFeedback]
	[Any follow-up responses from "Other" selections]
	```
	### Update Requirements Based on Feedback
	<mandatory>
	If the user provided feedback requiring changes (any answer other than "Yes, complete", "Yes, clear", "Yes, appropriate", or "Approved, let's proceed"), you MUST:
	1. Collect specific change requests from the user
	2. Invoke product-manager again with update instructions
	3. Repeat the review questions after updates
	4. Continue loop until user approves
	</mandatory>
	**Update Flow:**
	If changes are needed:
	1. **Ask for specific changes:**
	```
	What specific changes would you like to see in the requirements?
	```
	2. **Invoke product-manager with update prompt:**
	```
	You are updating the requirements for spec: $spec
	Spec path: ./specs/$spec/
	Current requirements: ./specs/$spec/requirements.md
	User feedback:
	$user_feedback
	Your task:
	1. Read the existing requirements.md
	2. Understand the user's feedback and concerns
	3. Update the requirements to address the feedback
	4. Maintain consistency with research findings
	5. Update requirements.md with the changes
	6. Append update notes to .progress.md explaining what changed
	Focus on addressing the specific feedback while maintaining requirements quality.
	```
	3. **After update, repeat review questions** (go back to "Requirements Review Questions")
	4. **Continue until approved:** Loop until user responds with approval
	**Skip if --quick flag.** Ask user to review generated requirements. If changes needed, invoke product-manager again with feedback and repeat until approved.
	## Update State
	After requirements complete and approved:
	1. Update `.ralph-state.json`:
	```json
	{
	"phase": "requirements",
	"awaitingApproval": true,
	...
	}
	```
	2. Update `.progress.md`:
	- Mark research as implicitly approved
	- Set current phase to requirements
	Update `.ralph-state.json`: `{ "phase": "requirements", "awaitingApproval": true }`
	## Review Loop
	### Quick mode
	Skip if --quick flag. Ask user to review generated requirements. If changes needed, invoke product-manager again with feedback and repeat until approved.
	## Update State
	Update `.ralph-state.json`: `{ "phase": "requirements", "awaitingApproval": true }`

🤖 Prompt for AI Agents

In `@plugins/ralph-specum/commands/requirements.md` around lines 67 - 73, Replace
the bold-as-heading "Skip if --quick flag." in the "Review Loop" section with a
proper Markdown heading (e.g., "Skip if --quick flag") followed by a normal
sentence explaining to ask the user to review generated requirements and to
re-invoke the product-manager with feedback until approved; keep the existing
note about skipping when --quick is provided and ensure the "Update State"
instruction that writes .ralph-state.json remains unchanged.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Fix incomplete markdown tables in the template.

The research.md template contains three table headers without separator rows, which will cause the tables to not render properly in the generated output:

• Line 110: | Spec | Relevance | Relationship | May Need Update |
• Line 113: | Type | Command | Source |
• Line 116: | Aspect | Assessment | Notes |

Each table header must be followed by a separator row for proper markdown rendering.

📋 Proposed fix to add table separators

 ## Related Specs
 | Spec | Relevance | Relationship | May Need Update |
+|------|-----------|--------------|-----------------|
 
 ## Quality Commands
 | Type | Command | Source |
+|------|---------|--------|
 
 ## Feasibility Assessment
 | Aspect | Assessment | Notes |
+|--------|------------|-------|

📝 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

	```markdown
	# Research: $spec
	**Task 3 - Codebase Analysis (Explore):**
	```yaml
	subagent_type: Explore
	thoroughness: very thorough
	## Executive Summary
	[Synthesize key findings - 2-3 sentences]
	Topic: Existing API and caching patterns in codebase
	Output: ./specs/$spec/.research-codebase.md
	## External Research
	### Best Practices
	### Prior Art
	### Pitfalls to Avoid
	1. Search for existing API implementations
	2. Find any caching code or patterns
	3. Identify relevant dependencies
	4. Document patterns with file paths
	```
	## Codebase Analysis
	### Existing Patterns
	### Dependencies
	### Constraints
	**Task 4 - Quality Commands (Explore):**
	```yaml
	subagent_type: Explore
	thoroughness: quick
	## Related Specs
	| Spec | Relevance | Relationship | May Need Update |
	Topic: Quality commands discovery
	Output: ./specs/$spec/.research-quality.md
	## Quality Commands
	| Type | Command | Source |
	1. Check package.json scripts
	2. Check Makefile if exists
	3. Check CI workflow commands
	4. Output as table: Type | Command | Source
	```
	## Feasibility Assessment
	| Aspect | Assessment | Notes |
	**Task 5 - Related Specs (Explore):**
	```yaml
	subagent_type: Explore
	thoroughness: medium
	## Recommendations for Requirements
	Topic: Related specs discovery
	Output: ./specs/$spec/.research-related-specs.md
	## Open Questions
	1. Scan ./specs/ for existing specs
	2. Read each spec's progress and requirements
	3. Identify overlaps with GraphQL/caching goal
	4. Output as table: Name | Relevance | Relationship | mayNeedUpdate
	## Sources
	```

🤖 Prompt for AI Agents

In `@plugins/ralph-specum/commands/research.md` around lines 92 - 122, The
markdown tables in the Research template are missing separator rows; after each
header row — "| Spec | Relevance | Relationship | May Need Update |", "| Type |
Command | Source |", and "| Aspect | Assessment | Notes |" — insert the
corresponding Markdown separator row (e.g. "| --- | --- | --- | --- |", "| --- |
--- | --- |", and "| --- | --- | --- |") immediately beneath each header so the
tables render correctly; update the template around the "Related Specs",
"Quality Commands", and "Feasibility Assessment" sections accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify interview-framework skill exists and check path conventions

echo "=== Checking if interview-framework skill exists in plugin ==="
find plugins/ralph-specum -name "SKILL.md" -o -name "interview-framework" -type d 2>/dev/null

echo ""
echo "=== Listing all SKILL.md files in plugins/ralph-specum ==="
find plugins/ralph-specum -name "SKILL.md" 2>/dev/null

echo ""
echo "=== Checking skill-reference patterns in commands ==="
rg '<skill-reference>' plugins/ralph-specum/commands/ -A3 2>/dev/null | head -40

echo ""
echo "=== Checking tasks.md context around lines 35-38 ==="
sed -n '30,45p' plugins/ralph-specum/commands/tasks.md 2>/dev/null

Repository: tzachbon/smart-ralph

Length of output: 5619

---

🏁 Script executed:

#!/bin/bash
# Check for all skill-reference patterns to identify convention

echo "=== All skill-reference paths used in commands ==="
rg '<skill-reference>' plugins/ralph-specum/commands/ -A1 | grep "Apply skill" | sort | uniq -c

echo ""
echo "=== Commands using relative paths (skills/) ==="
rg 'Apply skill.*`skills/' plugins/ralph-specum/commands/ -l

echo ""
echo "=== Commands using full paths (plugins/ralph-specum/skills/) ==="
rg 'Apply skill.*`plugins/ralph-specum/skills/' plugins/ralph-specum/commands/ -l

echo ""
echo "=== Check if there's a plugin-dev documentation ==="
find . -path "*/plugin-dev*" -type f 2>/dev/null | head -20

Repository: tzachbon/smart-ralph

Length of output: 1835

---

🏁 Script executed:

#!/bin/bash
# Search for documentation on path conventions or README files

echo "=== Searching for command documentation or README ==="
find plugins/ralph-specum -name "README*" -o -name "*.md" -path "*command*" | head -10

echo ""
echo "=== Check for any comments in commands about path convention ==="
rg -i "path|convention|reference" plugins/ralph-specum/commands/ --type md | head -20

echo ""
echo "=== Check the command files that use full paths vs relative ==="
echo "--- design.md (relative path) ---"
head -5 plugins/ralph-specum/commands/design.md

echo ""
echo "--- start.md (full path) ---"
head -5 plugins/ralph-specum/commands/start.md

echo ""
echo "=== Check if there's any pattern in file modification dates or grouping ==="
ls -la plugins/ralph-specum/commands/ | grep -E 'design|requirements|tasks|start|research|implement'

Repository: tzachbon/smart-ralph

Length of output: 3861

---

Use full path convention for skill reference.

The skill reference uses skills/interview-framework/SKILL.md, but the established convention across most commands is to use the full path from repository root: plugins/ralph-specum/skills/interview-framework/SKILL.md. Update to match the standard used in start.md, research.md, and implement.md.

🤖 Prompt for AI Agents

In `@plugins/ralph-specum/commands/tasks.md` around lines 35 - 38, Update the
skill-reference entry in plugins/ralph-specum/commands/tasks.md to use the full
repository-root path: replace the relative `skills/interview-framework/SKILL.md`
with `plugins/ralph-specum/skills/interview-framework/SKILL.md` inside the
<skill-reference> block so it matches the convention used in start.md,
research.md, and implement.md; ensure the token `Apply skill` text remains
unchanged aside from the path.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Clarify {goal} placeholder population.

The interview questions use a {goal} placeholder (e.g., "What testing depth for {goal}?"), but there's no indication in the command of where this value should come from or how it should be populated.

The "Gather Context" section (line 31) reads requirements, design, research, and progress files, but doesn't explicitly extract or define {goal}. Consider either:

1. Documenting that {goal} should be extracted from requirements.md
2. Showing explicit extraction: goal = [extract from requirements]
3. Clarifying if this is meant to be a literal placeholder string that the user sees

📝 Suggested clarification

Add after line 31:

 Read: `./specs/$spec/requirements.md`, `./specs/$spec/design.md`, `./specs/$spec/research.md` (if exists), `./specs/$spec/.progress.md`
+
+Extract `goal` from requirements.md frontmatter or summary section to use in interview questions.

🤖 Prompt for AI Agents

In `@plugins/ralph-specum/commands/tasks.md` around lines 46 - 49, The {goal}
placeholder in the interview questions is ambiguous; update the tasks.md "Gather
Context" section to explicitly define how {goal} is populated by stating that
goal is extracted from the requirements.md (e.g., "goal = extract primary
objective from requirements.md"), or alternatively note that {goal} is a literal
shown to users—add this clarification next to the "Gather Context" heading and
reference the {goal} placeholder so readers know to pull it from requirements.md
(or that it will be displayed verbatim).