refactor(plugins): apply plugin-dev best practices

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "ralph-specum",
       "description": "Spec-driven development with research, requirements, design, tasks, and autonomous execution. Fresh context per task.",
-      "version": "2.11.0",
+      "version": "2.11.2",
       "author": {
         "name": "tzachbon"
       },
@@ -21,7 +21,7 @@
     {
       "name": "ralph-speckit",
       "description": "Spec-driven development using GitHub spec-kit methodology. Constitution-first approach with specify, plan, tasks, and implement phases.",
-      "version": "0.4.0",
+      "version": "0.5.1",
       "author": {
         "name": "tzachbon"
       },

CLAUDE.md

@@ -35,6 +35,28 @@ claude --plugin-dir ./plugins/ralph-specum
 
 No build step required. Changes take effect on Claude Code restart.
 
+### Plugin Validation
+
+Run the validation script to check all plugins for compliance:
+
+```bash
+bash scripts/validate-plugins.sh
+```
+
+This checks:
+- Agent `color:` fields and `<example>` blocks
+- Skill `version:` fields
+- Hook `matcher` fields
+- No legacy command directories
+
+### Agent Color Conventions
+
+Assign colors by function for visual consistency:
+- **blue/cyan** - Analysis agents (research-analyst, architect-reviewer)
+- **green** - Execution agents (spec-executor)
+- **yellow** - Validation agents (qa-engineer)
+- **magenta** - Transformation agents (task-planner, product-manager)
+
 ### Plugin Development Skills (ALWAYS USE)
 
 When creating or modifying plugin components, **ALWAYS** use the `plugin-dev` skills for guidance:

plugins/ralph-speckit/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-speckit",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Spec-driven development using GitHub spec-kit methodology. Constitution-first approach with specify, plan, tasks, and implement phases.",
   "author": {
     "name": "tzachbon"

plugins/ralph-speckit/agents/constitution-architect.md

@@ -1,7 +1,23 @@
 ---
 name: constitution-architect
-description: Expert in creating and maintaining project constitutions. Establishes governance principles, technology standards, and quality guidelines.
+description: |
+  Expert in creating and maintaining project constitutions. Establishes governance principles, technology standards, and quality guidelines.
+
+  <example>
+  Context: User wants to establish project governance before starting feature development
+  user: /speckit:constitution
+  assistant: [Explores codebase to discover patterns, reads existing docs, then creates .specify/memory/constitution.md with MUST/SHOULD/MAY principles]
+  commentary: Triggered when user wants to establish or update project governance rules and standards
+  </example>
+
+  <example>
+  Context: User needs to update constitution after technology stack changes
+  user: We've switched from REST to GraphQL, update the constitution
+  assistant: [Reads current constitution, identifies affected sections, updates API patterns and examples, bumps version with changelog]
+  commentary: Triggered when project constraints or technology decisions change requiring constitution updates
+  </example>
 model: inherit
+color: magenta
 ---
 
 You are a constitution architect who establishes and maintains project governance documents. You create clear, actionable principles that guide all feature development.

plugins/ralph-speckit/agents/plan-architect.md

@@ -1,7 +1,23 @@
 ---
 name: plan-architect
-description: Technical architect for creating implementation plans from specifications. Designs architecture, data models, and API contracts aligned with constitution.
+description: |
+  Technical architect for creating implementation plans from specifications. Designs architecture, data models, and API contracts aligned with constitution.
+
+  <example>
+  Context: User has approved spec and wants technical design
+  user: /speckit:plan
+  assistant: [Reads spec.md and constitution, explores codebase architecture, creates plan.md with components, data models, API contracts, and constitution references]
+  commentary: Triggered when user wants to create technical implementation plan from approved specification
+  </example>
+
+  <example>
+  Context: Complex feature needs detailed architecture before implementation
+  user: The payment integration needs careful planning
+  assistant: [Parallel exploration for patterns, creates plan with security considerations per C§5.3, integration points, error handling per C§4.3]
+  commentary: Triggered when translating specifications into detailed technical architecture aligned with project constitution
+  </example>
 model: inherit
+color: cyan
 ---
 
 You are a technical architect who transforms feature specifications into detailed implementation plans. You design architectures, data models, and contracts that align with the project constitution.

plugins/ralph-speckit/agents/qa-engineer.md

@@ -1,7 +1,23 @@
 ---
 name: qa-engineer
-description: QA engineer that runs verification commands and checks acceptance criteria for [VERIFY] tasks.
+description: |
+  QA engineer that runs verification commands and checks acceptance criteria for [VERIFY] tasks.
+
+  <example>
+  Context: spec-executor delegates a verification checkpoint task
+  user: [Task tool invocation] Execute this verification task - V4 [VERIFY] Full local CI: pnpm lint && pnpm test
+  assistant: [Runs each command, captures exit codes, analyzes test quality for mock-only anti-patterns, outputs VERIFICATION_PASS or VERIFICATION_FAIL]
+  commentary: Triggered by spec-executor when encountering [VERIFY] tasks - never executed directly by users
+  </example>
+
+  <example>
+  Context: spec-executor delegates AC checklist verification
+  user: [Task tool invocation] V6 [VERIFY] AC checklist - verify all acceptance criteria from spec.md
+  assistant: [Reads spec.md, extracts all AC-* entries, verifies each against implementation, outputs table with PASS/FAIL/SKIP and evidence]
+  commentary: Triggered for final acceptance criteria verification before marking feature complete
+  </example>
 model: inherit
+color: yellow
 ---
 
 You are a QA engineer agent that executes [VERIFY] tasks. You run verification commands and check acceptance criteria, then output VERIFICATION_PASS or VERIFICATION_FAIL.
@@ -298,7 +314,7 @@ Skip mock quality checks when:
 | Command timeout | Mark as FAIL, report timeout |
 | AC ambiguous | Mark as SKIP with explanation |
 | File not found | Mark as FAIL if required, SKIP if optional |
-| All commands SKIP | Output VERIFICATION_PASS (no failures) |
+| All commands SKIP | Output VERIFICATION_FAIL (no verification executed) |
 
 ## Output Truncation
 

plugins/ralph-speckit/agents/spec-analyst.md

@@ -1,7 +1,23 @@
 ---
 name: spec-analyst
-description: Expert specification analyst for creating feature specs aligned with project constitution. Generates user stories, acceptance criteria, and scope definitions.
+description: |
+  Expert specification analyst for creating feature specs aligned with project constitution. Generates user stories, acceptance criteria, and scope definitions.
+
+  <example>
+  Context: User wants to create a specification for a new feature
+  user: /speckit:specify user-auth
+  assistant: [Reads constitution, explores codebase for context, then creates .specify/specs/user-auth/spec.md with user stories, acceptance criteria, and scope]
+  commentary: Triggered when user wants to define feature requirements and acceptance criteria aligned with constitution
+  </example>
+
+  <example>
+  Context: User provides a feature goal that needs structured specification
+  user: I need to add webhook notifications when orders are placed
+  assistant: [Analyzes goal, maps to constitution principles, creates spec with US1: Order webhook delivery, AC-1.1 through AC-1.N with verifiable criteria]
+  commentary: Triggered when converting feature goals into structured specifications with testable acceptance criteria
+  </example>
 model: inherit
+color: blue
 ---
 
 You are a specification analyst who creates feature specifications grounded in the project constitution. You translate goals into structured specs with user stories and acceptance criteria.

plugins/ralph-speckit/agents/spec-executor.md

@@ -1,7 +1,23 @@
 ---
 name: spec-executor
-description: Autonomous task executor for spec-kit development. Executes a single task from tasks.md, verifies, commits, and signals completion.
+description: |
+  Autonomous task executor for spec-kit development. Executes a single task from tasks.md, verifies, commits, and signals completion.
+
+  <example>
+  Context: Coordinator delegates a task for implementation
+  user: [Task tool invocation] Execute task T003 from tasks.md - Implement core API endpoint
+  assistant: [Reads task details, executes Do steps, modifies only listed Files, runs Verify command, commits with exact message, outputs TASK_COMPLETE]
+  commentary: Triggered by coordinator during /speckit:implement - never invoked directly by users
+  </example>
+
+  <example>
+  Context: Coordinator delegates a [VERIFY] checkpoint task
+  user: [Task tool invocation] Execute task T004 [VERIFY] Quality checkpoint
+  assistant: [Detects [VERIFY] tag, delegates to qa-engineer via Task tool, handles VERIFICATION_PASS/FAIL result, updates progress]
+  commentary: Triggered for verification tasks - delegates to qa-engineer rather than executing directly
+  </example>
 model: inherit
+color: green
 ---
 
 You are an autonomous execution agent that implements ONE task from a spec. You execute the task exactly as specified, verify completion, commit changes, update progress, and signal completion.

plugins/ralph-speckit/agents/task-planner.md

@@ -1,7 +1,23 @@
 ---
 name: task-planner
-description: Expert task planner for breaking plans into executable tasks. Masters POC-first workflow, task sequencing, quality gates, and constitution alignment.
+description: |
+  Expert task planner for breaking plans into executable tasks. Masters POC-first workflow, task sequencing, quality gates, and constitution alignment.
+
+  <example>
+  Context: User has approved plan and wants implementation tasks
+  user: /speckit:tasks
+  assistant: [Reads plan.md, spec.md, constitution, explores for commands, creates tasks.md with POC-first phases, [P] parallel markers, [VERIFY] checkpoints]
+  commentary: Triggered when user wants to break technical plan into executable task list for spec-executor
+  </example>
+
+  <example>
+  Context: Complex feature needs careful task sequencing
+  user: Generate tasks for the payment feature
+  assistant: [Creates tasks with Phase 1-5 structure, inserts [VERIFY] every 2-3 tasks, marks parallelizable tasks with [P], includes E2E validation tasks]
+  commentary: Triggered when converting technical plans into structured task sequences following POC-first workflow
+  </example>
 model: inherit
+color: cyan
 ---
 
 You are a task planning specialist who breaks technical plans into executable implementation steps. Your focus is POC-first workflow, clear task definitions, and quality gates aligned with the project constitution.

plugins/ralph-speckit/.claude/commands/speckit.analyze.md → plugins/ralph-speckit/commands/analyze.md

@@ -1,5 +1,7 @@
 ---
+name: analyze
 description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+allowed-tools: [Read, Bash]
 ---
 
 ## User Input
@@ -68,7 +70,7 @@ Load only the minimal necessary context from each artifact:
 
 Create internal representations (do not include raw artifacts in output):
 
-- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`)
 - **User story/action inventory**: Discrete user actions with acceptance criteria
 - **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
 - **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements

plugins/ralph-speckit/commands/cancel.md

@@ -1,7 +1,8 @@
 ---
+name: cancel
 description: Cancel active execution loop and cleanup state
 argument-hint: [feature-name]
-allowed-tools: [Read, Bash, Task]
+allowed-tools: [Read, Bash, Task, Skill]
 ---
 
 # Cancel Execution
@@ -28,7 +29,7 @@ If state file exists, read and display:
 
 ## Cleanup
 
-1. Stop Ralph Loop loop (if running):
+1. Stop Ralph Loop (if running):
    ```
    Use the Skill tool to invoke ralph-wiggum:cancel-ralph
    This stops any active Ralph Loop loop iteration