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