v4.0.0 — Plugin Best Practices v2

Breaking Changes

• Commands slimmed to thin orchestrators — procedural logic extracted into 13 references/ files (~60-88% line reduction per command)
• Sequential Review Pattern removed — Layer 5 (Artifact Review) is now the single reviewer invocation per task
• State updates require explicit jq merge — phase commands no longer use ambiguous JSON literals that could overwrite existing state fields

Highlights

• Reference extraction — 8 bloated command files decomposed into reusable references/ docs (coordinator-pattern, verification-layers, failure-recovery, quick-mode, etc.)
• 3 subagent dispatch templates — standardized prompts for executor, reviewer, and research agents
• Recovery mode fix — fix-task completions bypass verification layers; Layer 3 checkmark count adjusted for recovery mode
• Agent colors diversified — each role now has a distinct color (no more 5 agents sharing cyan)
• Internal skills hidden — 4 background skills (delegation-principle, reality-verification, interview-framework, communication-style) set to user-invocable: false
• Consistent paths — all references use ${CLAUDE_PLUGIN_ROOT} and $SPEC_PATH variable
• Explicit teammate names — spawn steps now set canonical names matching shutdown recipients
• ralph_find_spec() used in quick mode intent classification (supports non-default specs dirs)
• research-prompt.md — added {BASE_PATH} and {TOPIC_SLUG} placeholders

Stats

• 53 files changed, 5,022 additions, 6,190 deletions (net -1,168 lines)
• ralph-specum 3.10.0 → 4.0.0
• ralph-speckit 0.5.0 → 0.5.1

v3.1.1 - Self-contained execution loop

What's New

v3.0.0+ - Self-contained Execution Loop

Smart Ralph is now fully self-contained with no external plugin dependencies.

Key Changes:

• 🎉 No more ralph-loop dependency - The execution loop is handled by the built-in stop-hook
• 📦 Simpler installation - Just one plugin to install
• 🔧 No version compatibility issues between plugins

Migration from v2.x

1. Update Smart Ralph to v3.0.0+
2. Restart Claude Code
3. Existing specs continue working - no changes needed
4. Optionally uninstall ralph-loop if you don't use it elsewhere

Installation

/plugin marketplace add tzachbon/smart-ralph
/plugin install ralph-specum@smart-ralph

---

Full changelog: v2.12.0...v3.1.1

v2.0.0 - Ralph Wiggum Integration

Breaking Changes

Ralph Wiggum plugin now required for task execution.

Starting with v2.0.0, Smart Ralph delegates the execution loop to the official Ralph Wiggum plugin instead of using a custom stop-handler.

Before upgrading

Install the Ralph Wiggum dependency:

/plugin install ralph-wiggum@claude-plugins-official

Then restart Claude Code.

Migration Guide

See MIGRATION.md for detailed upgrade instructions.

What Changed

Before (v1.x)	After (v2.0.0)
Built-in stop-handler controlled loop	Ralph Wiggum plugin controls loop
/implement managed iterations directly	/implement invokes /ralph-loop
/cancel deleted state files only	/cancel calls /cancel-ralph + deletes state
~300 lines of bash for loop control	Thin wrapper around Ralph Wiggum

Highlights

• Deleted custom stop-handler.sh (274 lines)
• implement.md rewritten as thin wrapper invoking /ralph-loop
• Added stop-watcher.sh for logging/status (read-only, no loop control)
• cancel.md now calls /cancel-ralph for dual cleanup
• All existing spec files remain compatible (no changes needed)

Why This Change

• Less code to maintain
• Official plugin gets updates and bug fixes from Anthropic
• Better reliability for the execution loop
• Cleaner separation of concerns

Full Changelog

v1.7.0...v2.0.0