From 6c0ada2124ea1487307dd9fb67f4d42ab52a07ef Mon Sep 17 00:00:00 2001 From: bonfilz Date: Thu, 29 Jan 2026 21:19:44 +0200 Subject: [PATCH 01/37] spec(refactor-plugins): add requirements --- specs/refactor-plugins/requirements.md | 176 +++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 specs/refactor-plugins/requirements.md diff --git a/specs/refactor-plugins/requirements.md b/specs/refactor-plugins/requirements.md new file mode 100644 index 00000000..93b1c67d --- /dev/null +++ b/specs/refactor-plugins/requirements.md @@ -0,0 +1,176 @@ +--- +spec: refactor-plugins +phase: requirements +created: 2026-01-29 +--- + +# Requirements: Plugin Refactoring to Best Practices + +## Goal + +Refactor ralph-specum and ralph-speckit plugins to fully comply with plugin-dev skills best practices, fixing 61 identified issues across agents, skills, hooks, and commands. + +## User Decisions + +| Question | Response | +|----------|----------| +| Primary users | Both developers and end users | +| Priority tradeoffs | Prioritize thoroughness over speed | +| Success criteria | Full compliance + documentation (all issues fixed plus validation scripts and docs) | +| Problem statement | Improve all plugins according to plugin-dev skills best practices | +| Constraints | Use only plugin-dev skills to improve all plugins | + +--- + +## User Stories + +### US-1: Agent Color and Examples +**As a** plugin developer +**I want** all agents to have proper `color` and `` blocks +**So that** Claude can correctly identify when to invoke each agent + +**Acceptance Criteria:** +- [ ] AC-1.1: All 8 ralph-specum agents have `color` field in frontmatter +- [ ] AC-1.2: All 6 ralph-speckit agents have `color` field in frontmatter +- [ ] AC-1.3: All 14 agents have at least 2 `` blocks in description +- [ ] AC-1.4: Each example follows Context/user/assistant/commentary format +- [ ] AC-1.5: Colors match semantic guidelines (blue=analysis, green=execution, yellow=validation, magenta=transformation) + +### US-2: Skill Version and Description Format +**As a** plugin user +**I want** skills to have proper version and trigger-phrase descriptions +**So that** Claude correctly identifies when to use each skill + +**Acceptance Criteria:** +- [ ] AC-2.1: All 6 ralph-specum skills have `version: 0.1.0` field +- [ ] AC-2.2: All 4 ralph-speckit skills have `version: 0.1.0` field +- [ ] AC-2.3: All skill descriptions use third-person format ("This skill should be used when...") +- [ ] AC-2.4: All skill descriptions include at least 3 trigger phrases in quotes +- [ ] AC-2.5: interview-framework skill description is rewritten in correct format + +### US-3: Hook Matcher Fields +**As a** plugin developer +**I want** all hook entries to have explicit `matcher` field +**So that** hook configuration matches official plugin patterns + +**Acceptance Criteria:** +- [ ] AC-3.1: ralph-specum hooks.json Stop entry has `matcher: "*"` +- [ ] AC-3.2: ralph-specum hooks.json SessionStart entry has `matcher: "*"` +- [ ] AC-3.3: ralph-speckit hooks.json Stop entry has `matcher: "*"` + +### US-4: Command Migration and Fixes +**As a** ralph-speckit user +**I want** all commands consolidated in `commands/` with proper frontmatter +**So that** the plugin follows standard structure + +**Acceptance Criteria:** +- [ ] AC-4.1: All 5 modern ralph-speckit commands have `name` field +- [ ] AC-4.2: All 9 legacy commands migrated from `.claude/commands/` to `commands/` +- [ ] AC-4.3: Duplicate implement.md resolved (keep one, remove other) +- [ ] AC-4.4: Legacy `.claude/commands/` directory removed +- [ ] AC-4.5: Migrated commands have proper frontmatter (name, description, allowed_tools) + +### US-5: Validation and Documentation +**As a** plugin maintainer +**I want** validation scripts and updated documentation +**So that** future changes maintain compliance + +**Acceptance Criteria:** +- [ ] AC-5.1: Validation script checks all agents have `color` field +- [ ] AC-5.2: Validation script checks all agents have `` blocks +- [ ] AC-5.3: Validation script checks all skills have `version` field +- [ ] AC-5.4: Validation script checks all hooks have `matcher` field +- [ ] AC-5.5: CLAUDE.md updated with best practices reference + +--- + +## Functional Requirements + +| ID | Requirement | Priority | Acceptance Criteria | +|----|-------------|----------|---------------------| +| FR-1 | Add `color` field to all 14 agents | P0 | Agents render with semantic colors | +| FR-2 | Add `` blocks to all 14 agent descriptions | P0 | Each agent has 2+ examples with correct format | +| FR-3 | Fix skill descriptions to third-person format | P0 | All descriptions start with "This skill should be used when" | +| FR-4 | Add `version: 0.1.0` to all 10 skills | P1 | All skills report version in metadata | +| FR-5 | Add `matcher: "*"` to all hook entries | P1 | Hook config matches official patterns | +| FR-6 | Add `name` field to 5 ralph-speckit commands | P1 | Commands register with correct names | +| FR-7 | Migrate 9 legacy commands to `commands/` | P1 | All commands in standard location | +| FR-8 | Remove duplicate implement.md | P1 | Only one implement command exists | +| FR-9 | Create validation script | P2 | Script exits non-zero on compliance failures | +| FR-10 | Update CLAUDE.md documentation | P2 | Best practices documented | + +--- + +## Non-Functional Requirements + +| ID | Requirement | Metric | Target | +|----|-------------|--------|--------| +| NFR-1 | Backward compatibility | Breaking changes | 0 breaking changes to existing workflows | +| NFR-2 | Validation speed | Script runtime | < 5 seconds | +| NFR-3 | Code consistency | Style | Match official plugin-dev patterns exactly | + +--- + +## Glossary + +- **Agent**: Subagent definition (markdown file in `agents/`) invoked via Task tool +- **Skill**: Contextual knowledge (markdown in `skills/*/SKILL.md`) auto-loaded when relevant +- **Hook**: Event-driven action (JSON in `hooks/hooks.json`) triggered on lifecycle events +- **Command**: Slash command (markdown in `commands/`) invoked by user +- **Matcher**: Hook field specifying which events trigger the hook (`*` = all) +- **Frontmatter**: YAML metadata block at top of markdown files (between `---` markers) +- **Third-person description**: Format starting with "This skill/agent should be used when..." + +--- + +## Out of Scope + +- Adding new agents, skills, or commands +- Changing agent behavior or prompts beyond frontmatter fixes +- Adding `tools` restrictions to agents (noted in research but not required) +- Adding SessionStart hook to ralph-speckit (optional enhancement) +- Enhancing plugin.json with repository/homepage fields (nice-to-have) +- Performance optimization of plugins +- CI/CD integration of validation script + +--- + +## Dependencies + +- plugin-dev skills must be available for reference patterns +- Both plugins must be in working state before refactor +- No external service dependencies + +--- + +## Risk Assessment + +| Risk | Impact | Likelihood | Mitigation | +|------|--------|------------|------------| +| Breaking agent triggering | High | Medium | Test each agent after color/example changes | +| Legacy command loss | High | Low | Backup before migration, verify all commands work | +| Skill trigger regression | Medium | Low | Test skill matching after description changes | + +--- + +## Success Criteria + +1. All 61 identified issues resolved +2. Validation script passes for both plugins +3. No regressions in existing plugin functionality +4. Both plugins match official plugin-dev patterns + +--- + +## Unresolved Questions + +- Should colors be unique per agent or grouped by function? (Recommendation: group by function per research.md) +- Should ralph-speckit get SessionStart hook? (Out of scope for this refactor) + +--- + +## Next Steps + +1. Run `/ralph-specum:design` to create technical design for implementation +2. Define file-by-file change plan for each component type +3. Create task breakdown with quality checkpoints From 15ad4843c093e983b8d349ccd1d00f3fd6cac5ac Mon Sep 17 00:00:00 2001 From: bonfilz Date: Thu, 29 Jan 2026 22:33:28 +0200 Subject: [PATCH 02/37] spec(refactor-plugins): add technical design 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 --- specs/refactor-plugins/design.md | 520 +++++++++++++++++++++++++++++ specs/refactor-plugins/research.md | 360 ++++++++++++++++++++ 2 files changed, 880 insertions(+) create mode 100644 specs/refactor-plugins/design.md create mode 100644 specs/refactor-plugins/research.md diff --git a/specs/refactor-plugins/design.md b/specs/refactor-plugins/design.md new file mode 100644 index 00000000..9e94168c --- /dev/null +++ b/specs/refactor-plugins/design.md @@ -0,0 +1,520 @@ +--- +spec: refactor-plugins +phase: design +created: 2026-01-29 +updated: 2026-01-29 +--- + +# Design: Plugin Refactoring to Best Practices + +## Overview + +Two-phase refactoring: (1) Add missing frontmatter fields (color, version, matcher) and example blocks. (2) Consolidate procedural logic from commands/agents INTO skills. Commands become thin wrappers; agents reference skills for expertise. + +## Design Inputs (Interview Responses) + +| Parameter | Value | +|-----------|-------| +| Architecture style | Edit files in place | +| Technology constraints | Bash only for validation | +| Integration approach | Minimal - frontmatter/metadata only | +| New direction | Consolidate heavy-lifting into skills | + +## Skill Consolidation Strategy + +### Current State Analysis + +**Commands** (heavy - 100-1200 lines each): +- `implement.md`: 1200+ lines of coordinator logic, recovery orchestration, state machine +- `research.md`: 700+ lines including parallel research patterns, merge logic +- `start.md`: 980+ lines with branch management, quick mode, intent classification +- `design.md`, `requirements.md`, `tasks.md`: 250-300 lines each with interview patterns + +**Agents** (moderate - 250-500 lines each): +- `spec-executor.md`: 440 lines with execution rules, phase-specific rules, commit discipline +- `task-planner.md`: 520 lines with POC workflow, quality checkpoints, VF task generation +- `research-analyst.md`: 340 lines with quality command discovery, methodology +- `architect-reviewer.md`: 250 lines with design structure template + +**Skills** (light - 50-200 lines each): +- `interview-framework`: 200 lines - already well-consolidated +- `communication-style`: 105 lines - good +- `delegation-principle`: 48 lines - good +- `spec-workflow`: 45 lines - just command reference +- `reality-verification`: ~100 lines - good +- `smart-ralph`: ~100 lines - good + +### Consolidation Goals + +| Goal | Benefit | +|------|---------| +| Skills = reusable knowledge | Referenced by multiple commands/agents | +| Commands = thin orchestration | ~50-100 lines max, delegate to skills | +| Agents = focused expertise | Reference skills, don't duplicate patterns | + +### Content Migration Matrix + +| Source | Content to Extract | New Skill | Lines Saved | +|--------|-------------------|-----------|-------------| +| implement.md | Recovery orchestration (6b-6d) | `failure-recovery` | ~400 | +| implement.md | Verification layers (7) | `verification-layers` | ~70 | +| implement.md | Coordinator prompt pattern | `coordinator-pattern` | ~150 | +| start.md | Branch management logic | `branch-management` | ~200 | +| start.md | Intent classification | `intent-classification` | ~100 | +| start.md | Spec scanner | `spec-scanner` | ~80 | +| research.md | Parallel execution pattern | `parallel-research` | ~300 | +| research.md | Merge results algorithm | (in parallel-research) | ~100 | +| spec-executor.md | Phase-specific rules | `phase-rules` | ~50 | +| spec-executor.md | Commit discipline | `commit-discipline` | ~60 | +| task-planner.md | POC-first workflow rules | `poc-workflow` | ~80 | +| task-planner.md | Quality checkpoint rules | `quality-checkpoints` | ~100 | +| task-planner.md | VF task generation | (in reality-verification) | ~40 | +| research-analyst.md | Quality command discovery | `quality-commands` | ~80 | + +### New Skills to Create + +| Skill | Purpose | Referenced By | +|-------|---------|---------------| +| `failure-recovery` | Iterative fix task generation, recovery loop | implement.md, coordinator | +| `verification-layers` | 4-layer verification (contradiction, uncommitted, checkmark, signal) | implement.md, spec-executor | +| `coordinator-pattern` | Task delegation, state management, completion signal | implement.md | +| `branch-management` | Branch creation, worktree setup, naming conventions | start.md | +| `intent-classification` | Goal analysis for question counts | start.md, all phase commands | +| `spec-scanner` | Related specs discovery | start.md, research.md | +| `parallel-research` | Multi-agent research spawning, merge logic | research.md | +| `phase-rules` | POC/Refactor/Testing/Quality phase behaviors | spec-executor, task-planner | +| `commit-discipline` | Commit rules, spec file inclusion | spec-executor | +| `quality-checkpoints` | [VERIFY] task format, frequency rules | task-planner | +| `quality-commands` | Discovery from package.json/Makefile/CI | research-analyst | + +### Command Simplification Plan + +After consolidation, commands become thin orchestrators: + +```markdown +# Before: implement.md (1200 lines) +- Full coordinator prompt inline +- Recovery orchestration logic inline +- Verification layers inline +- State machine inline + +# After: implement.md (~150 lines) +1. Determine active spec +2. Validate prerequisites +3. Parse arguments +4. Initialize state +5. Reference skills: + - Invoke skill: coordinator-pattern + - Invoke skill: failure-recovery (if --recovery-mode) + - Invoke skill: verification-layers +6. Invoke Ralph Loop +``` + +| Command | Before | After | References Skills | +|---------|--------|-------|-------------------| +| implement.md | 1200 | ~150 | coordinator-pattern, failure-recovery, verification-layers | +| start.md | 980 | ~200 | branch-management, intent-classification, spec-scanner, interview-framework | +| research.md | 700 | ~150 | parallel-research, interview-framework | +| design.md | 300 | ~80 | interview-framework | +| requirements.md | 294 | ~80 | interview-framework | +| tasks.md | 314 | ~80 | interview-framework | + +### Agent Simplification Plan + +Agents reference skills instead of duplicating patterns: + +```markdown +# Before: spec-executor.md (440 lines) +- Phase rules inline (50 lines) +- Commit discipline inline (60 lines) +- Verification handling inline (100 lines) + +# After: spec-executor.md (~200 lines) +- Core execution logic +- Reference skill: phase-rules +- Reference skill: commit-discipline +- Reference skill: verification-layers (for [VERIFY] tasks) +``` + +| Agent | Before | After | References Skills | +|-------|--------|-------|-------------------| +| spec-executor.md | 440 | ~200 | phase-rules, commit-discipline, verification-layers | +| task-planner.md | 520 | ~250 | poc-workflow, quality-checkpoints, phase-rules | +| research-analyst.md | 340 | ~200 | quality-commands | +| architect-reviewer.md | 250 | ~200 | (minimal change - mostly template) | + +### Skill Reference Pattern + +Commands/agents reference skills using: + +```markdown + +**Apply skill**: `skills/failure-recovery/SKILL.md` +Use the failure recovery pattern when spec-executor does not output TASK_COMPLETE and recoveryMode is true. + +``` + +Or inline reference: +```markdown +**Failure Recovery**: Apply standard recovery loop from `skills/failure-recovery/SKILL.md` +``` + +## Change Strategy + +**Approach**: Two-phase refactoring +1. **Phase A**: Metadata fixes (original scope) - color, version, matcher, examples +2. **Phase B**: Skill consolidation - extract patterns to skills, simplify commands/agents + +**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 + +## File Change Matrix + +### ralph-specum Agents (8 files) + +| File | Add `color` | Add `` blocks | +|------|-------------|------------------------| +| `plugins/ralph-specum/agents/research-analyst.md` | `blue` | 2 examples | +| `plugins/ralph-specum/agents/product-manager.md` | `cyan` | 2 examples | +| `plugins/ralph-specum/agents/architect-reviewer.md` | `blue` | 2 examples | +| `plugins/ralph-specum/agents/task-planner.md` | `cyan` | 2 examples | +| `plugins/ralph-specum/agents/spec-executor.md` | `green` | 2 examples | +| `plugins/ralph-specum/agents/plan-synthesizer.md` | `green` | 2 examples | +| `plugins/ralph-specum/agents/qa-engineer.md` | `yellow` | 2 examples | +| `plugins/ralph-specum/agents/refactor-specialist.md` | `magenta` | 2 examples | + +### ralph-speckit Agents (6 files) + +| File | Add `color` | Add `` blocks | +|------|-------------|------------------------| +| `plugins/ralph-speckit/agents/constitution-architect.md` | `magenta` | 2 examples | +| `plugins/ralph-speckit/agents/spec-analyst.md` | `blue` | 2 examples | +| `plugins/ralph-speckit/agents/qa-engineer.md` | `yellow` | 2 examples | +| `plugins/ralph-speckit/agents/spec-executor.md` | `green` | 2 examples | +| `plugins/ralph-speckit/agents/plan-architect.md` | `cyan` | 2 examples | +| `plugins/ralph-speckit/agents/task-planner.md` | `cyan` | 2 examples | + +### ralph-specum Skills (6 files) + +| File | Add `version` | Fix description | +|------|---------------|-----------------| +| `plugins/ralph-specum/skills/communication-style/SKILL.md` | `0.1.0` | No (OK) | +| `plugins/ralph-specum/skills/delegation-principle/SKILL.md` | `0.1.0` | No (OK) | +| `plugins/ralph-specum/skills/interview-framework/SKILL.md` | `0.1.0` | Yes - rewrite | +| `plugins/ralph-specum/skills/reality-verification/SKILL.md` | `0.1.0` | No (OK) | +| `plugins/ralph-specum/skills/smart-ralph/SKILL.md` | `0.1.0` | No (OK) | +| `plugins/ralph-specum/skills/spec-workflow/SKILL.md` | `0.1.0` | No (OK) | + +### ralph-speckit Skills (4 files) + +| File | Add `version` | Fix description | +|------|---------------|-----------------| +| `plugins/ralph-speckit/skills/communication-style/SKILL.md` | `0.1.0` | Yes - rewrite | +| `plugins/ralph-speckit/skills/delegation-principle/SKILL.md` | `0.1.0` | Yes - rewrite | +| `plugins/ralph-speckit/skills/smart-ralph/SKILL.md` | `0.1.0` | Yes - rewrite | +| `plugins/ralph-speckit/skills/speckit-workflow/SKILL.md` | `0.1.0` | Yes - rewrite | + +### Hooks (2 files) + +| File | Change | +|------|--------| +| `plugins/ralph-specum/hooks/hooks.json` | Add `"matcher": "*"` to Stop and SessionStart entries | +| `plugins/ralph-speckit/hooks/hooks.json` | Add `"matcher": "*"` to Stop entry | + +### ralph-speckit Commands (5 files + 9 legacy) + +**Modern commands - add `name` field:** + +| File | Add `name` | +|------|-----------| +| `plugins/ralph-speckit/commands/start.md` | `start` | +| `plugins/ralph-speckit/commands/status.md` | `status` | +| `plugins/ralph-speckit/commands/switch.md` | `switch` | +| `plugins/ralph-speckit/commands/cancel.md` | `cancel` | +| `plugins/ralph-speckit/commands/implement.md` | `implement` | + +**Legacy commands - migrate from `.claude/commands/` to `commands/`:** + +| Source | Destination | Add frontmatter | +|--------|-------------|-----------------| +| `.claude/commands/speckit.analyze.md` | `commands/analyze.md` | name, allowed_tools | +| `.claude/commands/speckit.checklist.md` | `commands/checklist.md` | name, allowed_tools | +| `.claude/commands/speckit.clarify.md` | `commands/clarify.md` | name, allowed_tools | +| `.claude/commands/speckit.constitution.md` | `commands/constitution.md` | name, allowed_tools | +| `.claude/commands/speckit.implement.md` | REMOVE (duplicate) | - | +| `.claude/commands/speckit.plan.md` | `commands/plan.md` | name, allowed_tools | +| `.claude/commands/speckit.specify.md` | `commands/specify.md` | name, allowed_tools | +| `.claude/commands/speckit.tasks.md` | `commands/tasks.md` | name, allowed_tools | +| `.claude/commands/speckit.taskstoissues.md` | `commands/taskstoissues.md` | name, allowed_tools | + +**Post-migration**: Remove `plugins/ralph-speckit/.claude/commands/` directory. + +### Validation Script (1 new file) + +| File | Purpose | +|------|---------| +| `scripts/validate-plugins.sh` | Check compliance, exit non-zero on failure | + +### Documentation (1 file) + +| File | Change | +|------|--------| +| `CLAUDE.md` | Add plugin best practices reference section | + +## Agent Color Assignments + +Color grouping by semantic function: + +| Color | Function | Agents | +|-------|----------|--------| +| `blue` | Analysis, review, investigation | research-analyst, architect-reviewer, spec-analyst | +| `cyan` | Planning, coordination | product-manager, task-planner (both), plan-architect | +| `green` | Generation, execution | spec-executor (both), plan-synthesizer | +| `yellow` | Validation, quality | qa-engineer (both) | +| `magenta` | Transformation, creative | refactor-specialist, constitution-architect | + +## Example Block Format + +Each agent gets 2 examples in description: + +```markdown + +Context: [Scenario setup] +user: "[User message]" +assistant: "[Claude response about using agent]" + +[Why this triggers the agent] + + +``` + +## Validation Script Design + +**Location**: `scripts/validate-plugins.sh` + +**Checks**: + +```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 blocks (at least 2) +for agent in plugins/*/agents/*.md; do + count=$(grep -c "" "$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 + +# 5. Check no legacy commands remain +if [ -d "plugins/ralph-speckit/.claude/commands" ]; then + echo "FAIL: Legacy commands directory still exists" + ((ERRORS++)) +fi + +# Summary +if [ $ERRORS -eq 0 ]; then + echo "PASS: All plugins compliant" + exit 0 +else + echo "FAIL: $ERRORS compliance issues" + exit 1 +fi +``` + +## Execution Order + +### Phase A: Metadata Fixes (Original Scope) + +| Step | Tasks | Files | +|------|-------|-------| +| A1 | Fix ralph-specum agents (color + examples) | 8 files | +| A2 | Fix ralph-speckit agents (color + examples) | 6 files | +| A3 | Fix ralph-specum skills (version) | 6 files | +| A4 | Fix ralph-speckit skills (version + descriptions) | 4 files | +| A5 | Fix hooks (matcher) | 2 files | +| A6 | Fix ralph-speckit modern commands (name) | 5 files | +| A7 | Migrate legacy commands | 8 files create | +| A8 | Remove legacy directory | 1 directory | +| A9 | Create validation script | 1 file | +| A10 | Update CLAUDE.md | 1 file | +| QC-A | Run Phase A validation, verify no regressions | - | + +### Phase B: Skill Consolidation (New Scope) + +| Step | Tasks | Files | +|------|-------|-------| +| B1 | Create failure-recovery skill | 1 skill | +| B2 | Create verification-layers skill | 1 skill | +| B3 | Create coordinator-pattern skill | 1 skill | +| B4 | Create branch-management skill | 1 skill | +| B5 | Create intent-classification skill | 1 skill | +| B6 | Create spec-scanner skill | 1 skill | +| B7 | Create parallel-research skill | 1 skill | +| B8 | Create phase-rules skill | 1 skill | +| B9 | Create commit-discipline skill | 1 skill | +| B10 | Create quality-checkpoints skill | 1 skill | +| B11 | Create quality-commands skill | 1 skill | +| B12 | Simplify implement.md | 1 command | +| B13 | Simplify start.md | 1 command | +| B14 | Simplify research.md | 1 command | +| B15 | Simplify design.md, requirements.md, tasks.md | 3 commands | +| B16 | Simplify spec-executor.md | 1 agent | +| B17 | Simplify task-planner.md | 1 agent | +| B18 | Simplify research-analyst.md | 1 agent | +| QC-B | Run Phase B validation, test skill references | - | + +## Technical Decisions + +### Phase A Decisions + +| Decision | Options | Choice | Rationale | +|----------|---------|--------|-----------| +| Edit approach | In-place vs temp files | In-place | Simpler, git tracks changes | +| Color strategy | Unique per agent vs grouped | Grouped by function | Consistent semantic meaning | +| Legacy command naming | Keep speckit. prefix vs strip | Strip prefix | Match modern command style | +| Validation location | scripts/ vs plugin dir | scripts/ | Project-wide, not plugin-specific | +| Skill version | Use plugin version vs 0.1.0 | 0.1.0 | Standard initial version | + +### Phase B Decisions + +| Decision | Options | Choice | Rationale | +|----------|---------|--------|-----------| +| Skill extraction granularity | Few large vs many small | Many small (11) | Better reuse, focused context | +| Reference pattern | Inline expand vs reference | Reference with summary | Keeps commands/agents readable | +| Phase B timing | Same PR vs separate | Same PR | Single atomic refactor | +| Skill naming | Generic vs specific | Specific (failure-recovery not just recovery) | Clear intent, searchable | +| Skill organization | Flat vs grouped | Flat in skills/ | Plugin convention, auto-discovery | +| Content preserved vs trimmed | Keep full detail vs summarize | Keep full detail in skill | Skills are the source of truth | + +## Error Handling + +| Error | Handling | +|-------|----------| +| Edit fails to match | Investigate file format, use Read to verify | +| Legacy command has unique content | Compare with modern version, keep better | +| Validation fails after changes | Review failed check, fix file | + +## Rollback Strategy + +Git provides rollback: +```bash +git checkout -- plugins/ # Revert all plugin changes +git checkout -- scripts/ # Revert validation script +``` + +No database, no external state, no destructive operations. + +## Test Strategy + +**Validation script**: Run after all changes, must pass +**Manual verification**: +- Claude Code restart with `--plugin-dir` for both plugins +- Test agent triggering via Task tool +- Test skill loading via context matching +- Test command invocation + +## File Summary + +### Phase A: Metadata Fixes + +| Category | Files Changed | Files Created | Files Deleted | +|----------|---------------|---------------|---------------| +| Agents | 14 | 0 | 0 | +| Skills (version) | 10 | 0 | 0 | +| Hooks | 2 | 0 | 0 | +| Commands | 5 | 8 | 9 | +| Scripts | 0 | 1 | 0 | +| Docs | 1 | 0 | 0 | +| **Subtotal A** | **32** | **9** | **9** | + +### Phase B: Skill Consolidation + +| Category | Files Changed | Files Created | Files Deleted | +|----------|---------------|---------------|---------------| +| Commands (simplify) | 6 | 0 | 0 | +| Agents (simplify) | 4 | 0 | 0 | +| Skills (new) | 0 | 11 | 0 | +| **Subtotal B** | **10** | **11** | **0** | + +### Combined Total + +| Category | Files Changed | Files Created | Files Deleted | +|----------|---------------|---------------|---------------| +| **Grand Total** | **42** | **20** | **9** | + +## Implementation Steps + +### Phase A: Metadata Fixes + +1. Add `color` field to 8 ralph-specum agents +2. Add `` blocks to 8 ralph-specum agents +3. Add `color` field to 6 ralph-speckit agents +4. Add `` blocks to 6 ralph-speckit agents +5. Add `version: 0.1.0` to 6 ralph-specum skills +6. Add `version: 0.1.0` to 4 ralph-speckit skills +7. Rewrite interview-framework skill description (ralph-specum) +8. Rewrite 4 ralph-speckit skill descriptions +9. Add `"matcher": "*"` to ralph-specum hooks.json +10. Add `"matcher": "*"` to ralph-speckit hooks.json +11. Add `name` field to 5 ralph-speckit commands +12. Migrate 8 legacy commands to `commands/` with frontmatter +13. Remove duplicate speckit.implement.md +14. Remove `.claude/commands/` directory +15. Create `scripts/validate-plugins.sh` +16. Update CLAUDE.md with best practices reference +17. Run validation script Phase A +18. Test both plugins with Claude Code + +### Phase B: Skill Consolidation + +19. Create `skills/failure-recovery/SKILL.md` from implement.md sections 6b-6d +20. Create `skills/verification-layers/SKILL.md` from implement.md section 7 +21. Create `skills/coordinator-pattern/SKILL.md` from implement.md coordinator prompt +22. Create `skills/branch-management/SKILL.md` from start.md +23. Create `skills/intent-classification/SKILL.md` from start.md +24. Create `skills/spec-scanner/SKILL.md` from start.md +25. Create `skills/parallel-research/SKILL.md` from research.md +26. Create `skills/phase-rules/SKILL.md` from spec-executor.md +27. Create `skills/commit-discipline/SKILL.md` from spec-executor.md +28. Create `skills/quality-checkpoints/SKILL.md` from task-planner.md +29. Create `skills/quality-commands/SKILL.md` from research-analyst.md +30. Simplify implement.md to reference skills +31. Simplify start.md to reference skills +32. Simplify research.md to reference skills +33. Simplify design.md, requirements.md, tasks.md to reference interview-framework +34. Simplify spec-executor.md to reference skills +35. Simplify task-planner.md to reference skills +36. Simplify research-analyst.md to reference skills +37. Run validation script Phase B +38. Test skill references work correctly diff --git a/specs/refactor-plugins/research.md b/specs/refactor-plugins/research.md new file mode 100644 index 00000000..893a7d8e --- /dev/null +++ b/specs/refactor-plugins/research.md @@ -0,0 +1,360 @@ +--- +spec: refactor-plugins +phase: research +created: 2026-01-29 +--- + +# Research: refactor-plugins + +## Executive Summary + +Analysis of `ralph-specum` and `ralph-speckit` plugins against plugin-dev skills best practices reveals both plugins are functional but have significant gaps. The research used: +1. All plugin-dev skills for best practice patterns +2. Official Claude Code plugins (plugin-dev, feature-dev, hookify, ralph-loop) as reference implementations + +**Key findings:** +- **37 total issues** to fix across both plugins +- Agents: Missing `color` field (CRITICAL) and `` blocks in descriptions (CRITICAL) +- Skills: Missing `version` field and some using incorrect description format +- Hooks: Missing `matcher` field in hook entries +- Commands: ralph-speckit has legacy `.claude/commands/` that need migration + +## Official Plugin Reference Patterns + +### Agent Pattern (from plugin-dev/agents/agent-creator.md) + +```markdown +--- +name: agent-creator +description: Use this agent when the user asks to "create an agent", "generate an agent", "build a new agent"... Examples: + + +Context: User wants to create a code review agent +user: "Create an agent that reviews code for quality issues" +assistant: "I'll use the agent-creator agent to generate the agent configuration." + +User requesting new agent creation, trigger agent-creator to generate it. + + + +model: sonnet +color: magenta +tools: ["Write", "Read"] +--- +``` + +### Skill Pattern (from plugin-dev/skills/*) + +```markdown +--- +name: Skill Name +description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", "specific phrase 3". Include exact phrases users would say. +version: 0.1.0 +--- +``` + +### Hook Pattern (from ralph-loop/hooks/hooks.json) + +```json +{ + "description": "Brief explanation of hooks", + "hooks": { + "Stop": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/script.sh" + } + ] + } + ] + } +} +``` + +**Note:** `matcher` field is optional when hook applies to all events, but official plugins include it explicitly. + +### Color Guidelines (from agent-development skill) + +| Color | Use For | +|-------|---------| +| blue/cyan | Analysis, review, investigation | +| green | Generation, creation, success-oriented | +| yellow | Validation, warnings, caution | +| red | Security, critical analysis | +| magenta | Transformation, creative, refactoring | + +--- + +## ralph-specum Gap Analysis + +### Agents (8 total) + +| Agent | color | blocks | Issues | +|-------|-------|------------------|--------| +| research-analyst | MISSING | MISSING | 2 | +| product-manager | MISSING | MISSING | 2 | +| architect-reviewer | MISSING | MISSING | 2 | +| task-planner | MISSING | MISSING | 2 | +| spec-executor | MISSING | MISSING | 2 | +| plan-synthesizer | MISSING | MISSING | 2 | +| qa-engineer | MISSING | MISSING | 2 | +| refactor-specialist | MISSING | MISSING | 2 | + +**Total Agent Issues: 16 CRITICAL** + +**Recommended colors:** +- research-analyst: `blue` (investigation) +- product-manager: `cyan` (analysis) +- architect-reviewer: `blue` (review) +- task-planner: `cyan` (planning) +- spec-executor: `green` (execution) +- plan-synthesizer: `green` (generation) +- qa-engineer: `yellow` (validation) +- refactor-specialist: `magenta` (transformation) + +### Skills (6 total) + +| Skill | version | description format | Issues | +|-------|---------|-------------------|--------| +| communication-style | MISSING | OK (third-person) | 1 | +| delegation-principle | MISSING | OK (third-person) | 1 | +| interview-framework | MISSING | WRONG (not third-person) | 2 | +| reality-verification | MISSING | OK (third-person) | 1 | +| smart-ralph | MISSING | OK (third-person) | 1 | +| spec-workflow | MISSING | OK (third-person) | 1 | + +**Total Skill Issues: 7 (6 HIGH + 1 CRITICAL)** + +### Hooks (hooks/hooks.json) + +| Entry | matcher field | Status | +|-------|--------------|--------| +| Stop | MISSING | NEEDS FIX | +| SessionStart | MISSING | NEEDS FIX | + +**Total Hook Issues: 2 HIGH** + +### Commands (13 total) + +Commands follow best practices with proper frontmatter. No issues found. + +--- + +## ralph-speckit Gap Analysis + +### Agents (6 total) + +| Agent | color | blocks | Issues | +|-------|-------|------------------|--------| +| constitution-architect | MISSING | MISSING | 2 | +| spec-analyst | MISSING | MISSING | 2 | +| qa-engineer | MISSING | MISSING | 2 | +| spec-executor | MISSING | MISSING | 2 | +| plan-architect | MISSING | MISSING | 2 | +| task-planner | MISSING | MISSING | 2 | + +**Total Agent Issues: 12 CRITICAL** + +### Skills (4 total) + +| Skill | version | description format | Issues | +|-------|---------|-------------------|--------| +| communication-style | MISSING | WRONG (not third-person) | 2 | +| delegation-principle | MISSING | WRONG (not third-person) | 2 | +| smart-ralph | MISSING | WRONG (not third-person) | 2 | +| speckit-workflow | MISSING | WRONG (not third-person) | 2 | + +**Total Skill Issues: 8 CRITICAL** + +### Hooks (hooks/hooks.json) + +| Entry | matcher field | Status | +|-------|--------------|--------| +| Stop | MISSING | NEEDS FIX | + +**Total Hook Issues: 1 HIGH** + +### Commands + +**Modern commands (5 in `commands/`):** +| Command | name field | Status | +|---------|-----------|--------| +| start.md | MISSING | NEEDS FIX | +| status.md | MISSING | NEEDS FIX | +| switch.md | MISSING | NEEDS FIX | +| cancel.md | MISSING | NEEDS FIX | +| implement.md | MISSING | NEEDS FIX | + +**Legacy commands (9 in `.claude/commands/`):** +- speckit.analyze.md +- speckit.checklist.md +- speckit.clarify.md +- speckit.constitution.md +- speckit.implement.md (DUPLICATE!) +- speckit.plan.md +- speckit.specify.md +- speckit.tasks.md +- speckit.taskstoissues.md + +**Total Command Issues: 5 missing name + 9 need migration + 1 duplicate** + +--- + +## Summary of All Issues + +| Plugin | Component | Critical | High | Total | +|--------|-----------|----------|------|-------| +| ralph-specum | Agents | 16 | 0 | 16 | +| ralph-specum | Skills | 1 | 6 | 7 | +| ralph-specum | Hooks | 0 | 2 | 2 | +| ralph-speckit | Agents | 12 | 0 | 12 | +| ralph-speckit | Skills | 8 | 0 | 8 | +| ralph-speckit | Hooks | 0 | 1 | 1 | +| ralph-speckit | Commands | 0 | 15 | 15 | +| **TOTAL** | | **37** | **24** | **61** | + +--- + +## Sample Fixes + +### Agent Fix Example (research-analyst.md) + +**Current:** +```yaml +--- +name: research-analyst +description: This agent should be used to "research a feature"... +model: inherit +--- +``` + +**Fixed:** +```yaml +--- +name: research-analyst +description: This agent should be used to "research a feature", "analyze feasibility", "explore codebase", "find existing patterns", "gather context before requirements". Expert analyzer that verifies through web search, documentation, and codebase exploration before providing findings. + + +Context: User wants to add authentication to their app +user: "I need to add OAuth support" +assistant: "Let me research OAuth best practices and analyze your codebase for existing auth patterns." + +Research-analyst is triggered to explore OAuth implementations and codebase patterns before requirements phase. + + + + +Context: User starting new spec +user: "/ralph-specum:research" +assistant: "Starting research phase. I'll analyze best practices and your codebase." + +Research-analyst is explicitly invoked via the research command. + + + +model: inherit +color: blue +--- +``` + +### Skill Fix Example (interview-framework/SKILL.md) + +**Current:** +```yaml +--- +name: interview-framework +description: Standard single-question adaptive interview loop used across all spec phases +--- +``` + +**Fixed:** +```yaml +--- +name: interview-framework +description: This skill should be used when implementing "interview questions", "adaptive interview loop", "single-question flow", "parameter chain", "question piping", or building interview flows for spec phases. +version: 0.1.0 +--- +``` + +### Hooks Fix Example (hooks/hooks.json) + +**Current:** +```json +"Stop": [ + { + "hooks": [...] + } +] +``` + +**Fixed:** +```json +"Stop": [ + { + "matcher": "*", + "hooks": [...] + } +] +``` + +--- + +## Recommendations for Requirements + +### Priority 1: Critical (Must Fix) + +1. **Add `color` to all 14 agents** across both plugins +2. **Add `` blocks to all 14 agent descriptions** +3. **Add `matcher` to all hook entries** in both plugins +4. **Fix skill descriptions** to use third-person format with trigger phrases + +### Priority 2: High (Should Fix) + +5. **Add `version: 0.1.0`** to all 10 skills +6. **Add `name` field** to ralph-speckit commands +7. **Migrate legacy commands** from `.claude/commands/` to `commands/` +8. **Remove duplicate** implement.md in ralph-speckit + +### Priority 3: Nice to Have + +9. **Enhance plugin.json** with repository, homepage, full author info +10. **Create validation script** to check plugin compliance + +--- + +## Open Questions + +1. Should we use unique colors for each agent or group by function? +2. Should we add `tools` restrictions to limit agent access? +3. Should ralph-speckit get a SessionStart hook like ralph-specum? + +--- + +## Sources + +### Plugin-Dev Skills +- plugin-structure/SKILL.md - Directory layout, manifest format +- agent-development/SKILL.md - Agent frontmatter requirements +- skill-development/SKILL.md - Skill frontmatter requirements +- hook-development/SKILL.md - Hook configuration format +- command-development/SKILL.md - Command frontmatter format + +### Official Plugin References +- plugin-dev/agents/agent-creator.md - Agent with color and examples +- feature-dev/agents/code-architect.md - Agent with tools restriction +- ralph-loop/hooks/hooks.json - Hooks with matcher field +- hookify/skills/writing-rules/SKILL.md - Skill with version + +### Analyzed Files +- plugins/ralph-specum/agents/*.md (8 files) +- plugins/ralph-specum/skills/*/SKILL.md (6 files) +- plugins/ralph-specum/hooks/hooks.json +- plugins/ralph-specum/commands/*.md (13 files) +- plugins/ralph-speckit/agents/*.md (6 files) +- plugins/ralph-speckit/skills/*/SKILL.md (4 files) +- plugins/ralph-speckit/hooks/hooks.json +- plugins/ralph-speckit/commands/*.md (5 files) +- plugins/ralph-speckit/.claude/commands/*.md (9 files) From 9471f9208b8e4b60d55fc8143ba582773f70444f Mon Sep 17 00:00:00 2001 From: bonfilz Date: Fri, 30 Jan 2026 18:40:49 +0200 Subject: [PATCH 03/37] spec(refactor-plugins): add implementation tasks 32 tasks across 2 phases: - Phase A: 14 tasks (metadata fixes) - Phase B: 18 tasks (skill consolidation) Co-Authored-By: Claude Opus 4.5 --- specs/refactor-plugins/tasks.md | 576 ++++++++++++++++++++++++++++++++ 1 file changed, 576 insertions(+) create mode 100644 specs/refactor-plugins/tasks.md diff --git a/specs/refactor-plugins/tasks.md b/specs/refactor-plugins/tasks.md new file mode 100644 index 00000000..9fa231cf --- /dev/null +++ b/specs/refactor-plugins/tasks.md @@ -0,0 +1,576 @@ +--- +spec: refactor-plugins +phase: tasks +total_tasks: 32 +created: 2026-01-29 +--- + +# Tasks: Plugin Refactoring to Best Practices + +## Phase 1: Make It Work (POC) - Phase A Metadata Fixes + +Focus: Fix all missing frontmatter fields (color, version, matcher, name) and add example blocks to agents. + +### A1: Agent Metadata + +- [ ] 1.1 Add color and examples to ralph-specum agents (8 files) + - **Do**: + 1. For each of 8 agents, add `color` field after `model` in frontmatter + 2. Add 2 `` blocks with Context/user/assistant/commentary format to description + 3. Colors: research-analyst=blue, product-manager=cyan, architect-reviewer=blue, task-planner=cyan, spec-executor=green, plan-synthesizer=green, qa-engineer=yellow, refactor-specialist=magenta + - **Files**: + - `plugins/ralph-specum/agents/research-analyst.md` + - `plugins/ralph-specum/agents/product-manager.md` + - `plugins/ralph-specum/agents/architect-reviewer.md` + - `plugins/ralph-specum/agents/task-planner.md` + - `plugins/ralph-specum/agents/spec-executor.md` + - `plugins/ralph-specum/agents/plan-synthesizer.md` + - `plugins/ralph-specum/agents/qa-engineer.md` + - `plugins/ralph-specum/agents/refactor-specialist.md` + - **Done when**: All 8 agents have color field and 2+ example blocks + - **Verify**: `for f in plugins/ralph-specum/agents/*.md; do grep -q "^color:" "$f" && test $(grep -c "" "$f") -ge 2 || echo "FAIL: $f"; done | grep -c FAIL | xargs test 0 -eq` + - **Commit**: `feat(ralph-specum): add color and examples to all agents` + - _Requirements: AC-1.1, AC-1.3, AC-1.4, AC-1.5_ + - _Design: ralph-specum Agents, Agent Color Assignments_ + +- [ ] 1.2 Add color and examples to ralph-speckit agents (6 files) + - **Do**: + 1. For each of 6 agents, add `color` field after `model` in frontmatter + 2. Add 2 `` blocks with Context/user/assistant/commentary format to description + 3. Colors: constitution-architect=magenta, spec-analyst=blue, qa-engineer=yellow, spec-executor=green, plan-architect=cyan, task-planner=cyan + - **Files**: + - `plugins/ralph-speckit/agents/constitution-architect.md` + - `plugins/ralph-speckit/agents/spec-analyst.md` + - `plugins/ralph-speckit/agents/qa-engineer.md` + - `plugins/ralph-speckit/agents/spec-executor.md` + - `plugins/ralph-speckit/agents/plan-architect.md` + - `plugins/ralph-speckit/agents/task-planner.md` + - **Done when**: All 6 agents have color field and 2+ example blocks + - **Verify**: `for f in plugins/ralph-speckit/agents/*.md; do grep -q "^color:" "$f" && test $(grep -c "" "$f") -ge 2 || echo "FAIL: $f"; done | grep -c FAIL | xargs test 0 -eq` + - **Commit**: `feat(ralph-speckit): add color and examples to all agents` + - _Requirements: AC-1.2, AC-1.3, AC-1.4, AC-1.5_ + - _Design: ralph-speckit Agents, Agent Color Assignments_ + +- [ ] 1.3 [VERIFY] Quality checkpoint: agent metadata + - **Do**: Verify all 14 agents have color field and 2+ example blocks + - **Verify**: `count=0; for f in plugins/*/agents/*.md; do grep -q "^color:" "$f" && test $(grep -c "" "$f") -ge 2 || ((count++)); done; test $count -eq 0` + - **Done when**: All agents pass color and example validation + - **Commit**: `chore(plugins): pass agent metadata checkpoint` (only if fixes needed) + +### A2: Skill Metadata + +- [ ] 1.4 Add version to ralph-specum skills (6 files) + - **Do**: + 1. Add `version: 0.1.0` to frontmatter of each skill + 2. Fix interview-framework description to third-person format with trigger phrases + - **Files**: + - `plugins/ralph-specum/skills/communication-style/SKILL.md` + - `plugins/ralph-specum/skills/delegation-principle/SKILL.md` + - `plugins/ralph-specum/skills/interview-framework/SKILL.md` + - `plugins/ralph-specum/skills/reality-verification/SKILL.md` + - `plugins/ralph-specum/skills/smart-ralph/SKILL.md` + - `plugins/ralph-specum/skills/spec-workflow/SKILL.md` + - **Done when**: All 6 skills have version field, interview-framework has third-person description + - **Verify**: `for f in plugins/ralph-specum/skills/*/SKILL.md; do grep -q "^version:" "$f" || echo "FAIL: $f"; done | grep -c FAIL | xargs test 0 -eq` + - **Commit**: `feat(ralph-specum): add version to all skills` + - _Requirements: AC-2.1, AC-2.5_ + - _Design: ralph-specum Skills_ + +- [ ] 1.5 Add version and fix descriptions for ralph-speckit skills (4 files) + - **Do**: + 1. Add `version: 0.1.0` to frontmatter of each skill + 2. Rewrite all 4 descriptions to third-person format: "This skill should be used when..." + 3. Include at least 3 trigger phrases in quotes + - **Files**: + - `plugins/ralph-speckit/skills/communication-style/SKILL.md` + - `plugins/ralph-speckit/skills/delegation-principle/SKILL.md` + - `plugins/ralph-speckit/skills/smart-ralph/SKILL.md` + - `plugins/ralph-speckit/skills/speckit-workflow/SKILL.md` + - **Done when**: All 4 skills have version field and third-person descriptions + - **Verify**: `for f in plugins/ralph-speckit/skills/*/SKILL.md; do grep -q "^version:" "$f" && grep -q "This skill should be used when" "$f" || echo "FAIL: $f"; done | grep -c FAIL | xargs test 0 -eq` + - **Commit**: `feat(ralph-speckit): add version and fix descriptions for all skills` + - _Requirements: AC-2.2, AC-2.3, AC-2.4_ + - _Design: ralph-speckit Skills_ + +### A3: Hook Metadata + +- [ ] 1.6 Add matcher field to hooks (2 files) + - **Do**: + 1. Add `"matcher": "*"` to Stop entry in ralph-specum hooks.json + 2. Add `"matcher": "*"` to SessionStart entry in ralph-specum hooks.json + 3. Add `"matcher": "*"` to Stop entry in ralph-speckit hooks.json + - **Files**: + - `plugins/ralph-specum/hooks/hooks.json` + - `plugins/ralph-speckit/hooks/hooks.json` + - **Done when**: All hook entries have matcher field + - **Verify**: `for f in plugins/*/hooks/hooks.json; do grep -q '"matcher"' "$f" || echo "FAIL: $f"; done | grep -c FAIL | xargs test 0 -eq` + - **Commit**: `feat(plugins): add matcher field to all hook entries` + - _Requirements: AC-3.1, AC-3.2, AC-3.3_ + - _Design: Hooks_ + +- [ ] 1.7 [VERIFY] Quality checkpoint: skills and hooks + - **Do**: Verify all skills have version and all hooks have matcher + - **Verify**: `count=0; for f in plugins/*/skills/*/SKILL.md; do grep -q "^version:" "$f" || ((count++)); done; for f in plugins/*/hooks/hooks.json; do grep -q '"matcher"' "$f" || ((count++)); done; test $count -eq 0` + - **Done when**: All skills and hooks pass validation + - **Commit**: `chore(plugins): pass skills/hooks checkpoint` (only if fixes needed) + +### A4: Command Fixes + +- [ ] 1.8 Add name field to ralph-speckit modern commands (5 files) + - **Do**: + 1. Add `name: ` field to frontmatter of each command + 2. Names: start, status, switch, cancel, implement + - **Files**: + - `plugins/ralph-speckit/commands/start.md` (name: start) + - `plugins/ralph-speckit/commands/status.md` (name: status) + - `plugins/ralph-speckit/commands/switch.md` (name: switch) + - `plugins/ralph-speckit/commands/cancel.md` (name: cancel) + - `plugins/ralph-speckit/commands/implement.md` (name: implement) + - **Done when**: All 5 commands have name field in frontmatter + - **Verify**: `for f in plugins/ralph-speckit/commands/*.md; do grep -q "^name:" "$f" || echo "FAIL: $f"; done | grep -c FAIL | xargs test 0 -eq` + - **Commit**: `feat(ralph-speckit): add name field to modern commands` + - _Requirements: AC-4.1_ + - _Design: ralph-speckit Commands_ + +- [ ] 1.9 Migrate legacy commands to commands/ directory (8 files) + - **Do**: + 1. For each legacy command in `.claude/commands/`: + - Copy to `plugins/ralph-speckit/commands/` with new name (strip speckit. prefix) + - Add proper frontmatter: name, description, allowed_tools + 2. Files to migrate (skip speckit.implement.md - duplicate): + - speckit.analyze.md -> analyze.md + - speckit.checklist.md -> checklist.md + - speckit.clarify.md -> clarify.md + - speckit.constitution.md -> constitution.md + - speckit.plan.md -> plan.md + - speckit.specify.md -> specify.md + - speckit.tasks.md -> tasks.md + - speckit.taskstoissues.md -> taskstoissues.md + - **Files**: + - `plugins/ralph-speckit/commands/analyze.md` (create) + - `plugins/ralph-speckit/commands/checklist.md` (create) + - `plugins/ralph-speckit/commands/clarify.md` (create) + - `plugins/ralph-speckit/commands/constitution.md` (create) + - `plugins/ralph-speckit/commands/plan.md` (create) + - `plugins/ralph-speckit/commands/specify.md` (create) + - `plugins/ralph-speckit/commands/tasks.md` (create) + - `plugins/ralph-speckit/commands/taskstoissues.md` (create) + - **Done when**: All 8 commands exist in commands/ with proper frontmatter + - **Verify**: `for cmd in analyze checklist clarify constitution plan specify tasks taskstoissues; do test -f "plugins/ralph-speckit/commands/$cmd.md" && grep -q "^name:" "plugins/ralph-speckit/commands/$cmd.md" || echo "FAIL: $cmd"; done | grep -c FAIL | xargs test 0 -eq` + - **Commit**: `feat(ralph-speckit): migrate legacy commands to commands/` + - _Requirements: AC-4.2, AC-4.5_ + - _Design: Legacy commands migration_ + +- [ ] 1.10 Remove legacy commands directory + - **Do**: + 1. Verify all commands migrated successfully (from 1.9) + 2. Delete `.claude/commands/` directory from ralph-speckit + 3. This removes duplicate speckit.implement.md + - **Files**: + - `plugins/ralph-speckit/.claude/commands/` (delete entire directory) + - **Done when**: Legacy directory no longer exists + - **Verify**: `test ! -d "plugins/ralph-speckit/.claude/commands"` + - **Commit**: `chore(ralph-speckit): remove legacy commands directory` + - _Requirements: AC-4.3, AC-4.4_ + - _Design: Post-migration cleanup_ + +- [ ] 1.11 [VERIFY] Quality checkpoint: commands + - **Do**: Verify all ralph-speckit commands have name field and legacy dir removed + - **Verify**: `count=0; for f in plugins/ralph-speckit/commands/*.md; do grep -q "^name:" "$f" || ((count++)); done; test ! -d "plugins/ralph-speckit/.claude/commands" || ((count++)); test $count -eq 0` + - **Done when**: All commands valid, legacy directory removed + - **Commit**: `chore(ralph-speckit): pass commands checkpoint` (only if fixes needed) + +### A5: Validation and Documentation + +- [ ] 1.12 Create validation script + - **Do**: + 1. Create `scripts/validate-plugins.sh` with compliance checks: + - Agents have color field + - Agents have 2+ example blocks + - Skills have version field + - Hooks have matcher field + - No legacy commands directory + 2. Script exits 0 on pass, non-zero on failure + 3. Make script executable + - **Files**: + - `scripts/validate-plugins.sh` (create) + - **Done when**: Script runs and validates all checks + - **Verify**: `test -x scripts/validate-plugins.sh && bash scripts/validate-plugins.sh` + - **Commit**: `feat(scripts): add plugin compliance validation script` + - _Requirements: AC-5.1, AC-5.2, AC-5.3, AC-5.4_ + - _Design: Validation Script Design_ + +- [ ] 1.13 Update CLAUDE.md with best practices + - **Do**: + 1. Add section referencing plugin-dev skills for best practices + 2. Include validation script usage + 3. Document color conventions for agents + - **Files**: + - `CLAUDE.md` (edit) + - **Done when**: CLAUDE.md has plugin best practices reference + - **Verify**: `grep -q "validate-plugins" CLAUDE.md && grep -q "plugin-dev" CLAUDE.md` + - **Commit**: `docs: add plugin best practices reference to CLAUDE.md` + - _Requirements: AC-5.5_ + - _Design: Documentation_ + +- [ ] 1.14 [VERIFY] Phase A complete validation + - **Do**: Run full validation script to verify all Phase A changes + - **Verify**: `bash scripts/validate-plugins.sh && echo "Phase A PASS"` + - **Done when**: Validation script passes with 0 errors + - **Commit**: `chore(plugins): pass Phase A validation` (only if fixes needed) + +--- + +## Phase 2: Refactoring - Phase B Skill Consolidation + +Focus: Extract procedural logic from commands/agents into reusable skills, then simplify sources. + +### B1: Create New Skills + +- [ ] 2.1 Create failure-recovery skill + - **Do**: + 1. Extract recovery orchestration logic from implement.md sections 6b-6d + 2. Create skill with proper frontmatter (name, description, version) + 3. Document recovery loop pattern, fix task generation, recovery state management + - **Files**: + - `plugins/ralph-specum/skills/failure-recovery/SKILL.md` (create) + - **Done when**: Skill contains full recovery pattern, ~300-400 lines + - **Verify**: `test -f plugins/ralph-specum/skills/failure-recovery/SKILL.md && grep -q "^version:" plugins/ralph-specum/skills/failure-recovery/SKILL.md` + - **Commit**: `feat(ralph-specum): add failure-recovery skill` + - _Design: New Skills - failure-recovery_ + +- [ ] 2.2 Create verification-layers skill + - **Do**: + 1. Extract 4-layer verification pattern from implement.md section 7 + 2. Document: contradiction check, uncommitted changes, checkmark verification, completion signal + - **Files**: + - `plugins/ralph-specum/skills/verification-layers/SKILL.md` (create) + - **Done when**: Skill contains all 4 verification layers + - **Verify**: `test -f plugins/ralph-specum/skills/verification-layers/SKILL.md && grep -q "contradiction" plugins/ralph-specum/skills/verification-layers/SKILL.md` + - **Commit**: `feat(ralph-specum): add verification-layers skill` + - _Design: New Skills - verification-layers_ + +- [ ] 2.3 Create coordinator-pattern skill + - **Do**: + 1. Extract coordinator prompt pattern from implement.md + 2. Document role definition, state reading, task delegation, completion signaling + - **Files**: + - `plugins/ralph-specum/skills/coordinator-pattern/SKILL.md` (create) + - **Done when**: Skill contains coordinator delegation pattern + - **Verify**: `test -f plugins/ralph-specum/skills/coordinator-pattern/SKILL.md && grep -q "COORDINATOR" plugins/ralph-specum/skills/coordinator-pattern/SKILL.md` + - **Commit**: `feat(ralph-specum): add coordinator-pattern skill` + - _Design: New Skills - coordinator-pattern_ + +- [ ] 2.4 [VERIFY] Quality checkpoint: new skills batch 1 + - **Do**: Verify first 3 new skills have proper structure + - **Verify**: `count=0; for s in failure-recovery verification-layers coordinator-pattern; do test -f "plugins/ralph-specum/skills/$s/SKILL.md" && grep -q "^version:" "plugins/ralph-specum/skills/$s/SKILL.md" || ((count++)); done; test $count -eq 0` + - **Done when**: All 3 skills exist with version field + - **Commit**: `chore(ralph-specum): pass new skills batch 1 checkpoint` (only if fixes needed) + +- [ ] 2.5 Create branch-management skill + - **Do**: + 1. Extract branch management logic from start.md + 2. Document branch creation, worktree setup, naming conventions, default branch detection + - **Files**: + - `plugins/ralph-specum/skills/branch-management/SKILL.md` (create) + - **Done when**: Skill contains branch workflow patterns + - **Verify**: `test -f plugins/ralph-specum/skills/branch-management/SKILL.md && grep -q "branch" plugins/ralph-specum/skills/branch-management/SKILL.md` + - **Commit**: `feat(ralph-specum): add branch-management skill` + - _Design: New Skills - branch-management_ + +- [ ] 2.6 Create intent-classification skill + - **Do**: + 1. Extract intent classification logic from start.md + 2. Document goal type detection, keyword matching, question count determination + - **Files**: + - `plugins/ralph-specum/skills/intent-classification/SKILL.md` (create) + - **Done when**: Skill contains intent detection patterns and keyword tables + - **Verify**: `test -f plugins/ralph-specum/skills/intent-classification/SKILL.md && grep -q "intent" plugins/ralph-specum/skills/intent-classification/SKILL.md` + - **Commit**: `feat(ralph-specum): add intent-classification skill` + - _Design: New Skills - intent-classification_ + +- [ ] 2.7 Create spec-scanner skill + - **Do**: + 1. Extract spec discovery logic from start.md + 2. Document related specs finding, status checking, recommendation logic + - **Files**: + - `plugins/ralph-specum/skills/spec-scanner/SKILL.md` (create) + - **Done when**: Skill contains spec discovery patterns + - **Verify**: `test -f plugins/ralph-specum/skills/spec-scanner/SKILL.md && grep -q "spec" plugins/ralph-specum/skills/spec-scanner/SKILL.md` + - **Commit**: `feat(ralph-specum): add spec-scanner skill` + - _Design: New Skills - spec-scanner_ + +- [ ] 2.8 Create parallel-research skill + - **Do**: + 1. Extract parallel execution pattern from research.md + 2. Document multi-agent spawning, parallel search, results merge algorithm + - **Files**: + - `plugins/ralph-specum/skills/parallel-research/SKILL.md` (create) + - **Done when**: Skill contains parallel execution and merge patterns + - **Verify**: `test -f plugins/ralph-specum/skills/parallel-research/SKILL.md && grep -q "parallel" plugins/ralph-specum/skills/parallel-research/SKILL.md` + - **Commit**: `feat(ralph-specum): add parallel-research skill` + - _Design: New Skills - parallel-research_ + +- [ ] 2.9 [VERIFY] Quality checkpoint: new skills batch 2 + - **Do**: Verify skills 4-7 have proper structure + - **Verify**: `count=0; for s in branch-management intent-classification spec-scanner parallel-research; do test -f "plugins/ralph-specum/skills/$s/SKILL.md" && grep -q "^version:" "plugins/ralph-specum/skills/$s/SKILL.md" || ((count++)); done; test $count -eq 0` + - **Done when**: All 4 skills exist with version field + - **Commit**: `chore(ralph-specum): pass new skills batch 2 checkpoint` (only if fixes needed) + +- [ ] 2.10 Create phase-rules skill + - **Do**: + 1. Extract phase-specific rules from spec-executor.md + 2. Document POC/Refactor/Testing/Quality phase behaviors, shortcuts allowed per phase + - **Files**: + - `plugins/ralph-specum/skills/phase-rules/SKILL.md` (create) + - **Done when**: Skill contains all 4 phase behavior definitions + - **Verify**: `test -f plugins/ralph-specum/skills/phase-rules/SKILL.md && grep -q "Phase" plugins/ralph-specum/skills/phase-rules/SKILL.md` + - **Commit**: `feat(ralph-specum): add phase-rules skill` + - _Design: New Skills - phase-rules_ + +- [ ] 2.11 Create commit-discipline skill + - **Do**: + 1. Extract commit rules from spec-executor.md + 2. Document commit message format, spec file inclusion, commit frequency rules + - **Files**: + - `plugins/ralph-specum/skills/commit-discipline/SKILL.md` (create) + - **Done when**: Skill contains commit conventions and rules + - **Verify**: `test -f plugins/ralph-specum/skills/commit-discipline/SKILL.md && grep -q "commit" plugins/ralph-specum/skills/commit-discipline/SKILL.md` + - **Commit**: `feat(ralph-specum): add commit-discipline skill` + - _Design: New Skills - commit-discipline_ + +- [ ] 2.12 Create quality-checkpoints skill + - **Do**: + 1. Extract [VERIFY] task rules from task-planner.md + 2. Document checkpoint frequency, format, verification commands + - **Files**: + - `plugins/ralph-specum/skills/quality-checkpoints/SKILL.md` (create) + - **Done when**: Skill contains checkpoint insertion rules and formats + - **Verify**: `test -f plugins/ralph-specum/skills/quality-checkpoints/SKILL.md && grep -q "VERIFY" plugins/ralph-specum/skills/quality-checkpoints/SKILL.md` + - **Commit**: `feat(ralph-specum): add quality-checkpoints skill` + - _Design: New Skills - quality-checkpoints_ + +- [ ] 2.13 Create quality-commands skill + - **Do**: + 1. Extract quality command discovery from research-analyst.md + 2. Document package.json/Makefile/CI discovery patterns, fallback commands + - **Files**: + - `plugins/ralph-specum/skills/quality-commands/SKILL.md` (create) + - **Done when**: Skill contains command discovery patterns + - **Verify**: `test -f plugins/ralph-specum/skills/quality-commands/SKILL.md && grep -q "package.json" plugins/ralph-specum/skills/quality-commands/SKILL.md` + - **Commit**: `feat(ralph-specum): add quality-commands skill` + - _Design: New Skills - quality-commands_ + +- [ ] 2.14 [VERIFY] Quality checkpoint: new skills batch 3 + - **Do**: Verify skills 8-11 have proper structure + - **Verify**: `count=0; for s in phase-rules commit-discipline quality-checkpoints quality-commands; do test -f "plugins/ralph-specum/skills/$s/SKILL.md" && grep -q "^version:" "plugins/ralph-specum/skills/$s/SKILL.md" || ((count++)); done; test $count -eq 0` + - **Done when**: All 4 skills exist with version field + - **Commit**: `chore(ralph-specum): pass new skills batch 3 checkpoint` (only if fixes needed) + +### B2: Simplify Commands + +- [ ] 2.15 Simplify implement.md command + - **Do**: + 1. Replace inline coordinator prompt with skill reference to coordinator-pattern + 2. Replace inline recovery logic with skill reference to failure-recovery + 3. Replace inline verification logic with skill reference to verification-layers + 4. Target: ~150 lines (down from 1200+) + - **Files**: + - `plugins/ralph-specum/commands/implement.md` (edit) + - **Done when**: Command references skills, reduced to ~150-200 lines + - **Verify**: `test $(wc -l < plugins/ralph-specum/commands/implement.md) -lt 300 && grep -q "skill" plugins/ralph-specum/commands/implement.md` + - **Commit**: `refactor(ralph-specum): simplify implement.md to reference skills` + - _Design: Command Simplification Plan_ + +- [ ] 2.16 Simplify start.md command + - **Do**: + 1. Replace inline branch management with skill reference to branch-management + 2. Replace inline intent classification with skill reference to intent-classification + 3. Replace inline spec scanning with skill reference to spec-scanner + 4. Target: ~200 lines (down from 980+) + - **Files**: + - `plugins/ralph-specum/commands/start.md` (edit) + - **Done when**: Command references skills, reduced to ~200-250 lines + - **Verify**: `test $(wc -l < plugins/ralph-specum/commands/start.md) -lt 350 && grep -q "skill" plugins/ralph-specum/commands/start.md` + - **Commit**: `refactor(ralph-specum): simplify start.md to reference skills` + - _Design: Command Simplification Plan_ + +- [ ] 2.17 Simplify research.md command + - **Do**: + 1. Replace inline parallel execution with skill reference to parallel-research + 2. Target: ~150 lines (down from 700+) + - **Files**: + - `plugins/ralph-specum/commands/research.md` (edit) + - **Done when**: Command references skills, reduced to ~150-200 lines + - **Verify**: `test $(wc -l < plugins/ralph-specum/commands/research.md) -lt 250 && grep -q "skill" plugins/ralph-specum/commands/research.md` + - **Commit**: `refactor(ralph-specum): simplify research.md to reference skills` + - _Design: Command Simplification Plan_ + +- [ ] 2.18 Simplify design.md, requirements.md, tasks.md commands + - **Do**: + 1. Each command already uses interview-framework skill + 2. Ensure explicit skill references are present + 3. Target: ~80 lines each (down from ~300) + - **Files**: + - `plugins/ralph-specum/commands/design.md` (edit) + - `plugins/ralph-specum/commands/requirements.md` (edit) + - `plugins/ralph-specum/commands/tasks.md` (edit) + - **Done when**: Commands explicitly reference interview-framework skill + - **Verify**: `for f in design requirements tasks; do test $(wc -l < "plugins/ralph-specum/commands/$f.md") -lt 150 || echo "FAIL: $f"; done | grep -c FAIL | xargs test 0 -eq` + - **Commit**: `refactor(ralph-specum): simplify phase commands to reference skills` + - _Design: Command Simplification Plan_ + +- [ ] 2.19 [VERIFY] Quality checkpoint: command simplification + - **Do**: Verify all simplified commands are under target line counts + - **Verify**: `count=0; test $(wc -l < plugins/ralph-specum/commands/implement.md) -lt 300 || ((count++)); test $(wc -l < plugins/ralph-specum/commands/start.md) -lt 350 || ((count++)); test $(wc -l < plugins/ralph-specum/commands/research.md) -lt 250 || ((count++)); test $count -eq 0` + - **Done when**: All major commands under target line counts + - **Commit**: `chore(ralph-specum): pass command simplification checkpoint` (only if fixes needed) + +### B3: Simplify Agents + +- [ ] 2.20 Simplify spec-executor.md agent + - **Do**: + 1. Replace inline phase rules with skill reference to phase-rules + 2. Replace inline commit discipline with skill reference to commit-discipline + 3. Add skill reference to verification-layers for [VERIFY] tasks + 4. Target: ~200 lines (down from 440) + - **Files**: + - `plugins/ralph-specum/agents/spec-executor.md` (edit) + - **Done when**: Agent references skills, reduced to ~200-250 lines + - **Verify**: `test $(wc -l < plugins/ralph-specum/agents/spec-executor.md) -lt 300 && grep -q "skill" plugins/ralph-specum/agents/spec-executor.md` + - **Commit**: `refactor(ralph-specum): simplify spec-executor.md to reference skills` + - _Design: Agent Simplification Plan_ + +- [ ] 2.21 Simplify task-planner.md agent + - **Do**: + 1. Replace inline POC workflow with skill reference to phase-rules + 2. Replace inline quality checkpoints with skill reference to quality-checkpoints + 3. Target: ~250 lines (down from 520) + - **Files**: + - `plugins/ralph-specum/agents/task-planner.md` (edit) + - **Done when**: Agent references skills, reduced to ~250-300 lines + - **Verify**: `test $(wc -l < plugins/ralph-specum/agents/task-planner.md) -lt 350 && grep -q "skill" plugins/ralph-specum/agents/task-planner.md` + - **Commit**: `refactor(ralph-specum): simplify task-planner.md to reference skills` + - _Design: Agent Simplification Plan_ + +- [ ] 2.22 Simplify research-analyst.md agent + - **Do**: + 1. Replace inline quality command discovery with skill reference to quality-commands + 2. Target: ~200 lines (down from 340) + - **Files**: + - `plugins/ralph-specum/agents/research-analyst.md` (edit) + - **Done when**: Agent references skills, reduced to ~200-250 lines + - **Verify**: `test $(wc -l < plugins/ralph-specum/agents/research-analyst.md) -lt 280 && grep -q "skill" plugins/ralph-specum/agents/research-analyst.md` + - **Commit**: `refactor(ralph-specum): simplify research-analyst.md to reference skills` + - _Design: Agent Simplification Plan_ + +- [ ] 2.23 [VERIFY] Quality checkpoint: agent simplification + - **Do**: Verify all simplified agents are under target line counts + - **Verify**: `count=0; test $(wc -l < plugins/ralph-specum/agents/spec-executor.md) -lt 300 || ((count++)); test $(wc -l < plugins/ralph-specum/agents/task-planner.md) -lt 350 || ((count++)); test $(wc -l < plugins/ralph-specum/agents/research-analyst.md) -lt 280 || ((count++)); test $count -eq 0` + - **Done when**: All simplified agents under target line counts + - **Commit**: `chore(ralph-specum): pass agent simplification checkpoint` (only if fixes needed) + +--- + +## Phase 3: Testing + +Minimal testing per interview context. + +- [ ] 3.1 Run full validation script + - **Do**: Execute validation script to verify all compliance requirements + - **Files**: (none - verification only) + - **Done when**: Validation script passes with 0 errors + - **Verify**: `bash scripts/validate-plugins.sh` + - **Commit**: None (verification only) + - _Requirements: AC-5.1, AC-5.2, AC-5.3, AC-5.4_ + +--- + +## Phase 4: Quality Gates + +- [ ] 4.1 [VERIFY] Full local validation + - **Do**: Run validation script and verify all components + - **Verify**: `bash scripts/validate-plugins.sh && echo "All checks pass"` + - **Done when**: Validation passes, no compliance issues + - **Commit**: `fix(plugins): address validation issues` (only if fixes needed) + +- [ ] 4.2 Create PR and verify + - **Do**: + 1. Verify current branch is feature branch: `git branch --show-current` + 2. Push branch: `git push -u origin $(git branch --show-current)` + 3. Create PR: `gh pr create --title "refactor(plugins): apply plugin-dev best practices" --body "..."` + 4. Wait for CI: `gh pr checks --watch` + - **Verify**: `gh pr checks | grep -v "pending\|in_progress" | grep -c "fail" | xargs test 0 -eq` + - **Done when**: PR created, CI passes + - **Commit**: None (PR creation) + +--- + +## Phase 5: PR Lifecycle + +- [ ] 5.1 Monitor CI and fix failures + - **Do**: + 1. Watch CI status: `gh pr checks --watch` + 2. If failures, read logs and fix issues + 3. Push fixes and re-verify + - **Verify**: `gh pr checks | grep -c "fail" | xargs test 0 -eq` + - **Done when**: All CI checks pass + - **Commit**: `fix(plugins): address CI failures` (only if fixes needed) + +- [ ] 5.2 [VERIFY] AC checklist verification + - **Do**: Programmatically verify each acceptance criterion + - **Verify**: + ```bash + # AC-1.1, AC-1.2: All agents have color + for f in plugins/*/agents/*.md; do grep -q "^color:" "$f" || exit 1; done + # AC-1.3: All agents have 2+ examples + for f in plugins/*/agents/*.md; do test $(grep -c "" "$f") -ge 2 || exit 1; done + # AC-2.1, AC-2.2: All skills have version + for f in plugins/*/skills/*/SKILL.md; do grep -q "^version:" "$f" || exit 1; done + # AC-3.1, AC-3.2, AC-3.3: All hooks have matcher + for f in plugins/*/hooks/hooks.json; do grep -q '"matcher"' "$f" || exit 1; done + # AC-4.1: ralph-speckit commands have name + for f in plugins/ralph-speckit/commands/*.md; do grep -q "^name:" "$f" || exit 1; done + # AC-4.4: Legacy directory removed + test ! -d "plugins/ralph-speckit/.claude/commands" || exit 1 + # AC-5.1-5.4: Validation script works + bash scripts/validate-plugins.sh + echo "All ACs verified" + ``` + - **Done when**: All acceptance criteria confirmed met + - **Commit**: None (verification only) + +--- + +## Notes + +### POC Shortcuts Taken + +- Validation script is bash-only (no test framework) +- Manual Claude Code testing deferred to user +- No automated E2E tests for plugin loading + +### Production TODOs + +- Consider adding CI integration for validation script +- May want to add more sophisticated skill trigger phrase detection +- Consider adding tools restrictions to agents in future iteration + +### File Counts + +| Phase | Files Changed | Files Created | Files Deleted | +|-------|---------------|---------------|---------------| +| Phase A | 32 | 9 | 9 | +| Phase B | 10 | 11 | 0 | +| **Total** | **42** | **20** | **9** | + +### Skill Reference Pattern + +Commands/agents reference skills using: + +```markdown + +**Apply skill**: `skills/failure-recovery/SKILL.md` +Use the failure recovery pattern when spec-executor does not output TASK_COMPLETE. + +``` From d8cf5965817e7fb5b46cdc3ee432994c21af5e8f Mon Sep 17 00:00:00 2001 From: bonfilz Date: Fri, 30 Jan 2026 21:29:12 +0200 Subject: [PATCH 04/37] feat(ralph-specum): add color and examples to all agents Co-Authored-By: Claude Opus 4.5 --- .../ralph-specum/agents/architect-reviewer.md | 18 +++++++++++++++++- .../ralph-specum/agents/plan-synthesizer.md | 18 +++++++++++++++++- plugins/ralph-specum/agents/product-manager.md | 18 +++++++++++++++++- plugins/ralph-specum/agents/qa-engineer.md | 18 +++++++++++++++++- .../ralph-specum/agents/refactor-specialist.md | 18 +++++++++++++++++- .../ralph-specum/agents/research-analyst.md | 18 +++++++++++++++++- plugins/ralph-specum/agents/spec-executor.md | 18 +++++++++++++++++- plugins/ralph-specum/agents/task-planner.md | 18 +++++++++++++++++- specs/refactor-plugins/tasks.md | 2 +- 9 files changed, 137 insertions(+), 9 deletions(-) diff --git a/plugins/ralph-specum/agents/architect-reviewer.md b/plugins/ralph-specum/agents/architect-reviewer.md index 9035594d..5f5a9d40 100644 --- a/plugins/ralph-specum/agents/architect-reviewer.md +++ b/plugins/ralph-specum/agents/architect-reviewer.md @@ -1,7 +1,23 @@ --- name: architect-reviewer -description: This agent should be used to "create technical design", "define architecture", "design components", "create design.md", "analyze trade-offs". Expert systems architect that designs scalable, maintainable systems with clear component boundaries. +description: | + This agent should be used to "create technical design", "define architecture", "design components", "create design.md", "analyze trade-offs". Expert systems architect that designs scalable, maintainable systems with clear component boundaries. + + + Context: User has approved requirements and needs technical design + user: Design the architecture for the authentication feature + assistant: [Reads requirements.md, creates mermaid diagrams, defines component interfaces, documents technical decisions table] + commentary: The agent produces design.md with architecture diagrams, component definitions, data flow, and explicit trade-off decisions. + + + + Context: User needs design review before implementation + user: Review the proposed file structure for the new module + assistant: [Analyzes existing codebase patterns via Explore, validates proposed structure against conventions, recommends adjustments] + commentary: The agent ensures designs align with existing codebase patterns and explicitly documents deviations with rationale. + model: inherit +color: blue --- You are a senior systems architect with expertise in designing scalable, maintainable systems. Your focus is architecture decisions, component boundaries, patterns, and technical feasibility. diff --git a/plugins/ralph-specum/agents/plan-synthesizer.md b/plugins/ralph-specum/agents/plan-synthesizer.md index bb4500b2..aeba9a5f 100644 --- a/plugins/ralph-specum/agents/plan-synthesizer.md +++ b/plugins/ralph-specum/agents/plan-synthesizer.md @@ -1,7 +1,23 @@ --- name: plan-synthesizer -description: This agent should be used to "run quick mode", "generate all spec artifacts", "synthesize spec from goal", "auto-generate research, requirements, design, tasks". Rapid spec synthesizer that creates all four spec artifacts in one pass for quick mode execution. +description: | + This agent should be used to "run quick mode", "generate all spec artifacts", "synthesize spec from goal", "auto-generate research, requirements, design, tasks". Rapid spec synthesizer that creates all four spec artifacts in one pass for quick mode execution. + + + Context: User wants to skip interactive phases + user: Quick mode: Add a new user profile endpoint + assistant: [Explores codebase briefly, generates research.md, requirements.md, design.md, tasks.md in sequence, commits specs, transitions to execution phase] + commentary: The agent generates all four artifacts with `generated: auto` frontmatter, then updates state to enable immediate task execution. + + + + Context: User provides a fix-type goal in quick mode + user: Quick mode: Fix the broken login validation + assistant: [Detects fix goal, runs reproduction command to capture BEFORE state, documents in .progress.md, generates minimal fix-focused artifacts] + commentary: For fix goals, the agent diagnoses the issue first, documents the BEFORE state, and generates a VF task to verify the fix works. + model: inherit +color: green --- You are a rapid spec synthesizer that converts a user plan/goal into complete spec artifacts. Your purpose is to enable quick mode where all spec phases are completed automatically. diff --git a/plugins/ralph-specum/agents/product-manager.md b/plugins/ralph-specum/agents/product-manager.md index 6c721884..ece5486d 100644 --- a/plugins/ralph-specum/agents/product-manager.md +++ b/plugins/ralph-specum/agents/product-manager.md @@ -1,7 +1,23 @@ --- name: product-manager -description: This agent should be used to "generate requirements", "write user stories", "define acceptance criteria", "create requirements.md", "gather product requirements". Expert product manager that translates user goals into structured requirements. +description: | + This agent should be used to "generate requirements", "write user stories", "define acceptance criteria", "create requirements.md", "gather product requirements". Expert product manager that translates user goals into structured requirements. + + + Context: User has completed research and needs requirements + user: Generate requirements for the new API authentication feature + assistant: [Reads research.md, creates user stories with acceptance criteria, outputs requirements.md with FR/NFR tables] + commentary: The agent transforms research findings into testable user stories and prioritized requirements. + + + + Context: User provides a high-level goal + user: I need requirements for adding dark mode to the app + assistant: [Explores codebase for UI patterns, creates US-1 through US-N with specific ACs, defines out-of-scope items] + commentary: The agent ensures every requirement has testable acceptance criteria and clear scope boundaries. + model: inherit +color: cyan --- You are a senior product manager with expertise in translating user goals into structured requirements. Your focus is user empathy, business value framing, and creating testable acceptance criteria. diff --git a/plugins/ralph-specum/agents/qa-engineer.md b/plugins/ralph-specum/agents/qa-engineer.md index 1ba8c40b..9bb93428 100644 --- a/plugins/ralph-specum/agents/qa-engineer.md +++ b/plugins/ralph-specum/agents/qa-engineer.md @@ -1,7 +1,23 @@ --- name: qa-engineer -description: This agent should be used to "run verification task", "check quality gate", "verify acceptance criteria", "run [VERIFY] task", "execute quality checkpoint". QA engineer that runs verification commands and outputs VERIFICATION_PASS or VERIFICATION_FAIL. +description: | + This agent should be used to "run verification task", "check quality gate", "verify acceptance criteria", "run [VERIFY] task", "execute quality checkpoint". QA engineer that runs verification commands and outputs VERIFICATION_PASS or VERIFICATION_FAIL. + + + Context: spec-executor delegates a [VERIFY] task + user: Execute V4 [VERIFY] Full local CI: pnpm lint && pnpm test + assistant: [Runs each command via Bash, captures exit codes, outputs VERIFICATION_PASS if all pass, or VERIFICATION_FAIL with specific error details] + commentary: The agent runs verification commands sequentially, stopping on first failure and providing actionable error information. + + + + Context: VF task to verify a fix resolved the original issue + user: Execute VF: Verify original issue resolved + assistant: [Reads BEFORE state from .progress.md, re-runs reproduction command, compares BEFORE/AFTER, documents result, outputs VERIFICATION_PASS or VERIFICATION_FAIL] + commentary: For VF tasks, the agent proves the fix worked by comparing the BEFORE failure state with the AFTER success state. + 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. diff --git a/plugins/ralph-specum/agents/refactor-specialist.md b/plugins/ralph-specum/agents/refactor-specialist.md index 2edea487..0a2cd51d 100644 --- a/plugins/ralph-specum/agents/refactor-specialist.md +++ b/plugins/ralph-specum/agents/refactor-specialist.md @@ -1,7 +1,23 @@ --- name: refactor-specialist -description: This agent should be used to "update spec files", "refactor requirements", "revise design", "modify tasks after execution", "incrementally update specifications". Expert at methodically reviewing and updating spec files section-by-section after execution. +description: | + This agent should be used to "update spec files", "refactor requirements", "revise design", "modify tasks after execution", "incrementally update specifications". Expert at methodically reviewing and updating spec files section-by-section after execution. + + + Context: User wants to update requirements after implementation learnings + user: Update requirements.md based on what we learned during implementation + assistant: [Reads current requirements.md and .progress.md learnings, presents each section for review, makes targeted changes, preserves valuable context] + commentary: The agent reviews section-by-section, asking before changing, and preserves implementation learnings in the updated spec. + + + + Context: Design needs revision after POC revealed issues + user: Revise the design based on POC findings + assistant: [Reads design.md and .progress.md, identifies sections needing updates, makes focused changes, detects cascade to tasks.md] + commentary: The agent detects when changes cascade to downstream files and reports CASCADE_NEEDED with specific files and reasons. + model: inherit +color: magenta --- You are a spec refactoring specialist. Your role is to help users update their specifications after execution in a methodical, section-by-section approach. diff --git a/plugins/ralph-specum/agents/research-analyst.md b/plugins/ralph-specum/agents/research-analyst.md index dc97c67b..63390620 100644 --- a/plugins/ralph-specum/agents/research-analyst.md +++ b/plugins/ralph-specum/agents/research-analyst.md @@ -1,7 +1,23 @@ --- name: research-analyst -description: This agent should be used to "research a feature", "analyze feasibility", "explore codebase", "find existing patterns", "gather context before requirements". Expert analyzer that verifies through web search, documentation, and codebase exploration before providing findings. +description: | + This agent should be used to "research a feature", "analyze feasibility", "explore codebase", "find existing patterns", "gather context before requirements". Expert analyzer that verifies through web search, documentation, and codebase exploration before providing findings. + + + Context: User wants to understand if a feature is feasible + user: Research how authentication is handled in this codebase + assistant: [Uses WebSearch and Glob/Grep to find auth patterns, creates research.md with feasibility assessment] + commentary: The agent searches externally for best practices, then internally for existing patterns, cross-references, and outputs structured findings. + + + + Context: User needs codebase analysis before starting a new feature + user: Find existing patterns for API endpoints before we add a new one + assistant: [Explores src/ for endpoint patterns, documents conventions found, recommends approach aligned with existing code] + commentary: The agent prioritizes internal research for pattern questions, documenting file paths and code examples as sources. + model: inherit +color: blue --- You are a senior analyzer and researcher with a strict "verify-first, assume-never" methodology. Your core principle: **never guess, always check**. diff --git a/plugins/ralph-specum/agents/spec-executor.md b/plugins/ralph-specum/agents/spec-executor.md index 566e2f90..748ecf15 100644 --- a/plugins/ralph-specum/agents/spec-executor.md +++ b/plugins/ralph-specum/agents/spec-executor.md @@ -1,7 +1,23 @@ --- name: spec-executor -description: This agent should be used to "execute a task", "implement task from tasks.md", "run spec task", "complete verification task". Autonomous executor that implements one task, verifies completion, commits changes, and signals TASK_COMPLETE. +description: | + This agent should be used to "execute a task", "implement task from tasks.md", "run spec task", "complete verification task". Autonomous executor that implements one task, verifies completion, commits changes, and signals TASK_COMPLETE. + + + Context: Coordinator delegates a task during implementation + user: Execute task 1.2: Add authentication middleware + assistant: [Reads task details, implements Do steps exactly, runs Verify command, commits with specified message, outputs TASK_COMPLETE] + commentary: The agent executes exactly one task, never deviating from the Files list, and only outputs TASK_COMPLETE after verification passes. + + + + Context: Task is a [VERIFY] checkpoint + user: Execute task 2.3 [VERIFY] Quality checkpoint + assistant: [Detects [VERIFY] tag, delegates to qa-engineer agent, handles VERIFICATION_PASS or VERIFICATION_FAIL result] + commentary: [VERIFY] tasks are always delegated to qa-engineer; the spec-executor never runs verification commands directly for these tasks. + 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. diff --git a/plugins/ralph-specum/agents/task-planner.md b/plugins/ralph-specum/agents/task-planner.md index a199ee4c..d568a6cb 100644 --- a/plugins/ralph-specum/agents/task-planner.md +++ b/plugins/ralph-specum/agents/task-planner.md @@ -1,7 +1,23 @@ --- name: task-planner -description: This agent should be used to "create tasks", "break down design into tasks", "generate tasks.md", "plan implementation steps", "define quality checkpoints". Expert task planner that creates POC-first task breakdowns with verification steps. +description: | + This agent should be used to "create tasks", "break down design into tasks", "generate tasks.md", "plan implementation steps", "define quality checkpoints". Expert task planner that creates POC-first task breakdowns with verification steps. + + + Context: User has approved design and needs implementation tasks + user: Create tasks for the authentication feature + assistant: [Reads design.md, creates 4-phase task breakdown with POC first, adds [VERIFY] checkpoints every 2-3 tasks, each task has Do/Files/Verify/Commit] + commentary: The agent generates tasks.md with POC-first workflow, ensuring each task is autonomous-executable with explicit verification commands. + + + + Context: User needs tasks for a bugfix + user: Plan tasks to fix the login validation bug + assistant: [Detects fix-type goal, plans reproduction task first, adds VF verification task at end, keeps Phase 1 minimal] + commentary: For fix goals, the agent includes reality-check tasks to prove the issue is resolved before and after implementation. + model: inherit +color: cyan --- You are a task planning specialist who breaks designs into executable implementation steps. Your focus is POC-first workflow, clear task definitions, and quality gates. diff --git a/specs/refactor-plugins/tasks.md b/specs/refactor-plugins/tasks.md index 9fa231cf..76e3ee95 100644 --- a/specs/refactor-plugins/tasks.md +++ b/specs/refactor-plugins/tasks.md @@ -13,7 +13,7 @@ Focus: Fix all missing frontmatter fields (color, version, matcher, name) and ad ### A1: Agent Metadata -- [ ] 1.1 Add color and examples to ralph-specum agents (8 files) +- [x] 1.1 Add color and examples to ralph-specum agents (8 files) - **Do**: 1. For each of 8 agents, add `color` field after `model` in frontmatter 2. Add 2 `` blocks with Context/user/assistant/commentary format to description From c7ca6d4d05d9297aeaa74323c8617f2aa95f676c Mon Sep 17 00:00:00 2001 From: bonfilz Date: Fri, 30 Jan 2026 21:30:56 +0200 Subject: [PATCH 05/37] feat(ralph-speckit): add color and examples to all agents Co-Authored-By: Claude Opus 4.5 --- .../agents/constitution-architect.md | 18 +++++++++++++++++- plugins/ralph-speckit/agents/plan-architect.md | 18 +++++++++++++++++- plugins/ralph-speckit/agents/qa-engineer.md | 18 +++++++++++++++++- plugins/ralph-speckit/agents/spec-analyst.md | 18 +++++++++++++++++- plugins/ralph-speckit/agents/spec-executor.md | 18 +++++++++++++++++- plugins/ralph-speckit/agents/task-planner.md | 18 +++++++++++++++++- specs/refactor-plugins/tasks.md | 2 +- 7 files changed, 103 insertions(+), 7 deletions(-) diff --git a/plugins/ralph-speckit/agents/constitution-architect.md b/plugins/ralph-speckit/agents/constitution-architect.md index d6d18979..09475f44 100644 --- a/plugins/ralph-speckit/agents/constitution-architect.md +++ b/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. + + + 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 + + + + 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 + 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. diff --git a/plugins/ralph-speckit/agents/plan-architect.md b/plugins/ralph-speckit/agents/plan-architect.md index 2c321cd2..a4eb1795 100644 --- a/plugins/ralph-speckit/agents/plan-architect.md +++ b/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. + + + 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 + + + + 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 + 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. diff --git a/plugins/ralph-speckit/agents/qa-engineer.md b/plugins/ralph-speckit/agents/qa-engineer.md index e481d4e4..b19d7fe6 100644 --- a/plugins/ralph-speckit/agents/qa-engineer.md +++ b/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. + + + 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 + + + + 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 + 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. diff --git a/plugins/ralph-speckit/agents/spec-analyst.md b/plugins/ralph-speckit/agents/spec-analyst.md index 138b4d6e..1d22f9dd 100644 --- a/plugins/ralph-speckit/agents/spec-analyst.md +++ b/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. + + + 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 + + + + 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 + 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. diff --git a/plugins/ralph-speckit/agents/spec-executor.md b/plugins/ralph-speckit/agents/spec-executor.md index bf2f138b..3be6921e 100644 --- a/plugins/ralph-speckit/agents/spec-executor.md +++ b/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. + + + 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 + + + + 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 + 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. diff --git a/plugins/ralph-speckit/agents/task-planner.md b/plugins/ralph-speckit/agents/task-planner.md index d09088b5..4b2d123c 100644 --- a/plugins/ralph-speckit/agents/task-planner.md +++ b/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. + + + 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 + + + + 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 + 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. diff --git a/specs/refactor-plugins/tasks.md b/specs/refactor-plugins/tasks.md index 76e3ee95..e8d1c240 100644 --- a/specs/refactor-plugins/tasks.md +++ b/specs/refactor-plugins/tasks.md @@ -33,7 +33,7 @@ Focus: Fix all missing frontmatter fields (color, version, matcher, name) and ad - _Requirements: AC-1.1, AC-1.3, AC-1.4, AC-1.5_ - _Design: ralph-specum Agents, Agent Color Assignments_ -- [ ] 1.2 Add color and examples to ralph-speckit agents (6 files) +- [x] 1.2 Add color and examples to ralph-speckit agents (6 files) - **Do**: 1. For each of 6 agents, add `color` field after `model` in frontmatter 2. Add 2 `` blocks with Context/user/assistant/commentary format to description From 68538ab5eece032aa26e61fc6a44ee6ca11d3203 Mon Sep 17 00:00:00 2001 From: bonfilz Date: Fri, 30 Jan 2026 21:33:15 +0200 Subject: [PATCH 06/37] feat(ralph-specum): add version to all skills Co-Authored-By: Claude Opus 4.5 --- plugins/ralph-specum/skills/communication-style/SKILL.md | 1 + plugins/ralph-specum/skills/delegation-principle/SKILL.md | 1 + plugins/ralph-specum/skills/interview-framework/SKILL.md | 3 ++- plugins/ralph-specum/skills/reality-verification/SKILL.md | 1 + plugins/ralph-specum/skills/smart-ralph/SKILL.md | 1 + plugins/ralph-specum/skills/spec-workflow/SKILL.md | 1 + specs/refactor-plugins/tasks.md | 2 +- 7 files changed, 8 insertions(+), 2 deletions(-) diff --git a/plugins/ralph-specum/skills/communication-style/SKILL.md b/plugins/ralph-specum/skills/communication-style/SKILL.md index a009dfd2..ad7af0e8 100644 --- a/plugins/ralph-specum/skills/communication-style/SKILL.md +++ b/plugins/ralph-specum/skills/communication-style/SKILL.md @@ -1,5 +1,6 @@ --- name: communication-style +version: 0.1.0 description: This skill should be used when the user asks about "output formatting", "concise responses", "Matt Pocock planning style", "scannable output", "action steps format", or needs guidance on communication and output formatting rules for Ralph agents. --- diff --git a/plugins/ralph-specum/skills/delegation-principle/SKILL.md b/plugins/ralph-specum/skills/delegation-principle/SKILL.md index 16ccd297..6a03c8f7 100644 --- a/plugins/ralph-specum/skills/delegation-principle/SKILL.md +++ b/plugins/ralph-specum/skills/delegation-principle/SKILL.md @@ -1,5 +1,6 @@ --- name: delegation-principle +version: 0.1.0 description: This skill should be used when the user asks about "coordinator role", "delegate to subagent", "use Task tool", "never implement yourself", "subagent delegation", or needs guidance on proper delegation patterns for Ralph workflows. --- diff --git a/plugins/ralph-specum/skills/interview-framework/SKILL.md b/plugins/ralph-specum/skills/interview-framework/SKILL.md index 07587f83..ed5909cc 100644 --- a/plugins/ralph-specum/skills/interview-framework/SKILL.md +++ b/plugins/ralph-specum/skills/interview-framework/SKILL.md @@ -1,6 +1,7 @@ --- name: interview-framework -description: Standard single-question adaptive interview loop used across all spec phases +version: 0.1.0 +description: This skill should be used when the user asks about "interview loop", "single-question interview", "adaptive interview", "question piping", "parameter chain", "completion signals", or needs guidance on the standard interview framework used across Ralph spec phases. --- # Interview Framework diff --git a/plugins/ralph-specum/skills/reality-verification/SKILL.md b/plugins/ralph-specum/skills/reality-verification/SKILL.md index 5bb9b669..a8d6baca 100644 --- a/plugins/ralph-specum/skills/reality-verification/SKILL.md +++ b/plugins/ralph-specum/skills/reality-verification/SKILL.md @@ -1,5 +1,6 @@ --- name: reality-verification +version: 0.1.0 description: This skill should be used when the user asks to "verify a fix", "reproduce failure", "diagnose issue", "check BEFORE/AFTER state", "VF task", "reality check", or needs guidance on verifying fixes by reproducing failures before and after implementation. --- diff --git a/plugins/ralph-specum/skills/smart-ralph/SKILL.md b/plugins/ralph-specum/skills/smart-ralph/SKILL.md index 8d2d2f6f..244a6573 100644 --- a/plugins/ralph-specum/skills/smart-ralph/SKILL.md +++ b/plugins/ralph-specum/skills/smart-ralph/SKILL.md @@ -1,5 +1,6 @@ --- name: smart-ralph +version: 0.1.0 description: This skill should be used when the user asks about "ralph arguments", "quick mode", "commit spec", "max iterations", "ralph state file", "execution modes", "ralph loop integration", or needs guidance on common Ralph plugin arguments and state management patterns. --- diff --git a/plugins/ralph-specum/skills/spec-workflow/SKILL.md b/plugins/ralph-specum/skills/spec-workflow/SKILL.md index a57bc697..e0ed8507 100644 --- a/plugins/ralph-specum/skills/spec-workflow/SKILL.md +++ b/plugins/ralph-specum/skills/spec-workflow/SKILL.md @@ -1,5 +1,6 @@ --- name: spec-workflow +version: 0.1.0 description: This skill should be used when the user asks to "build a feature", "create a spec", "start spec-driven development", "run research phase", "generate requirements", "create design", "plan tasks", "implement spec", "check spec status", or needs guidance on the spec-driven development workflow. --- diff --git a/specs/refactor-plugins/tasks.md b/specs/refactor-plugins/tasks.md index e8d1c240..2ac796f1 100644 --- a/specs/refactor-plugins/tasks.md +++ b/specs/refactor-plugins/tasks.md @@ -59,7 +59,7 @@ Focus: Fix all missing frontmatter fields (color, version, matcher, name) and ad ### A2: Skill Metadata -- [ ] 1.4 Add version to ralph-specum skills (6 files) +- [x] 1.4 Add version to ralph-specum skills (6 files) - **Do**: 1. Add `version: 0.1.0` to frontmatter of each skill 2. Fix interview-framework description to third-person format with trigger phrases From e32d256b9da77274211ab33ab3f75ac079a9e498 Mon Sep 17 00:00:00 2001 From: bonfilz Date: Fri, 30 Jan 2026 21:34:25 +0200 Subject: [PATCH 07/37] feat(ralph-speckit): add version and fix descriptions for all skills Co-Authored-By: Claude Opus 4.5 --- plugins/ralph-speckit/skills/communication-style/SKILL.md | 3 ++- plugins/ralph-speckit/skills/delegation-principle/SKILL.md | 3 ++- plugins/ralph-speckit/skills/smart-ralph/SKILL.md | 3 ++- plugins/ralph-speckit/skills/speckit-workflow/SKILL.md | 3 ++- specs/refactor-plugins/tasks.md | 2 +- 5 files changed, 9 insertions(+), 5 deletions(-) diff --git a/plugins/ralph-speckit/skills/communication-style/SKILL.md b/plugins/ralph-speckit/skills/communication-style/SKILL.md index be50584d..1ae4d24e 100644 --- a/plugins/ralph-speckit/skills/communication-style/SKILL.md +++ b/plugins/ralph-speckit/skills/communication-style/SKILL.md @@ -1,6 +1,7 @@ --- name: communication-style -description: Output rules for all agents - concise, scannable, actionable. Based on Matt Pocock's planning principles. +version: 0.1.0 +description: This skill should be used when the user asks about "output formatting", "concise responses", "Matt Pocock planning style", "scannable output", "action steps format", or needs guidance on communication and output formatting rules for Ralph agents. --- # Communication Style diff --git a/plugins/ralph-speckit/skills/delegation-principle/SKILL.md b/plugins/ralph-speckit/skills/delegation-principle/SKILL.md index be25edea..fa88f751 100644 --- a/plugins/ralph-speckit/skills/delegation-principle/SKILL.md +++ b/plugins/ralph-speckit/skills/delegation-principle/SKILL.md @@ -1,6 +1,7 @@ --- name: delegation-principle -description: Core principle that the main agent is a coordinator, not an implementer. All work must be delegated to subagents. +version: 0.1.0 +description: This skill should be used when the user asks about "coordinator role", "delegate to subagent", "use Task tool", "never implement yourself", "subagent delegation", or needs guidance on proper delegation patterns for Ralph workflows. --- # Delegation Principle diff --git a/plugins/ralph-speckit/skills/smart-ralph/SKILL.md b/plugins/ralph-speckit/skills/smart-ralph/SKILL.md index fcecf060..8951d7b6 100644 --- a/plugins/ralph-speckit/skills/smart-ralph/SKILL.md +++ b/plugins/ralph-speckit/skills/smart-ralph/SKILL.md @@ -1,6 +1,7 @@ --- name: smart-ralph -description: Core Smart Ralph skill defining common arguments, execution modes, and shared behaviors across all Ralph plugins. +version: 0.1.0 +description: This skill should be used when the user asks about "ralph arguments", "quick mode", "commit spec", "max iterations", "ralph state file", "execution modes", "ralph loop integration", or needs guidance on common Ralph plugin arguments and state management patterns. --- # Smart Ralph diff --git a/plugins/ralph-speckit/skills/speckit-workflow/SKILL.md b/plugins/ralph-speckit/skills/speckit-workflow/SKILL.md index c1de6239..768a9307 100644 --- a/plugins/ralph-speckit/skills/speckit-workflow/SKILL.md +++ b/plugins/ralph-speckit/skills/speckit-workflow/SKILL.md @@ -1,6 +1,7 @@ --- name: speckit-workflow -description: Comprehensive understanding of the spec-kit methodology. Constitution-driven feature development with specify, plan, tasks, and implement phases. +version: 0.1.0 +description: This skill should be used when the user asks to "build a feature", "create a spec", "start spec-driven development", "run research phase", "generate requirements", "create design", "plan tasks", "implement spec", "check spec status", or needs guidance on the spec-driven development workflow. --- # SpecKit Workflow diff --git a/specs/refactor-plugins/tasks.md b/specs/refactor-plugins/tasks.md index 2ac796f1..5131d583 100644 --- a/specs/refactor-plugins/tasks.md +++ b/specs/refactor-plugins/tasks.md @@ -76,7 +76,7 @@ Focus: Fix all missing frontmatter fields (color, version, matcher, name) and ad - _Requirements: AC-2.1, AC-2.5_ - _Design: ralph-specum Skills_ -- [ ] 1.5 Add version and fix descriptions for ralph-speckit skills (4 files) +- [x] 1.5 Add version and fix descriptions for ralph-speckit skills (4 files) - **Do**: 1. Add `version: 0.1.0` to frontmatter of each skill 2. Rewrite all 4 descriptions to third-person format: "This skill should be used when..." From 8301b9441ae9529e3ea3cb2b9f966454292e7ee1 Mon Sep 17 00:00:00 2001 From: bonfilz Date: Fri, 30 Jan 2026 21:35:27 +0200 Subject: [PATCH 08/37] feat(plugins): add matcher field to all hook entries Co-Authored-By: Claude Opus 4.5 --- plugins/ralph-speckit/hooks/hooks.json | 1 + plugins/ralph-specum/hooks/hooks.json | 2 ++ specs/refactor-plugins/tasks.md | 2 +- 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/plugins/ralph-speckit/hooks/hooks.json b/plugins/ralph-speckit/hooks/hooks.json index e5560f9e..1eba5f47 100644 --- a/plugins/ralph-speckit/hooks/hooks.json +++ b/plugins/ralph-speckit/hooks/hooks.json @@ -2,6 +2,7 @@ "hooks": { "Stop": [ { + "matcher": "*", "hooks": [ { "type": "command", diff --git a/plugins/ralph-specum/hooks/hooks.json b/plugins/ralph-specum/hooks/hooks.json index a4a228e9..31b87ed3 100644 --- a/plugins/ralph-specum/hooks/hooks.json +++ b/plugins/ralph-specum/hooks/hooks.json @@ -3,6 +3,7 @@ "hooks": { "Stop": [ { + "matcher": "*", "hooks": [ { "type": "command", @@ -13,6 +14,7 @@ ], "SessionStart": [ { + "matcher": "*", "hooks": [ { "type": "command", diff --git a/specs/refactor-plugins/tasks.md b/specs/refactor-plugins/tasks.md index 5131d583..f9df354a 100644 --- a/specs/refactor-plugins/tasks.md +++ b/specs/refactor-plugins/tasks.md @@ -94,7 +94,7 @@ Focus: Fix all missing frontmatter fields (color, version, matcher, name) and ad ### A3: Hook Metadata -- [ ] 1.6 Add matcher field to hooks (2 files) +- [x] 1.6 Add matcher field to hooks (2 files) - **Do**: 1. Add `"matcher": "*"` to Stop entry in ralph-specum hooks.json 2. Add `"matcher": "*"` to SessionStart entry in ralph-specum hooks.json From 34bd45bcff29ae55a01d2e0e3443b40e0cdaad72 Mon Sep 17 00:00:00 2001 From: bonfilz Date: Fri, 30 Jan 2026 21:37:23 +0200 Subject: [PATCH 09/37] feat(ralph-speckit): add name field to modern commands Co-Authored-By: Claude Opus 4.5 --- plugins/ralph-speckit/commands/cancel.md | 1 + plugins/ralph-speckit/commands/implement.md | 1 + plugins/ralph-speckit/commands/start.md | 1 + plugins/ralph-speckit/commands/status.md | 1 + plugins/ralph-speckit/commands/switch.md | 1 + specs/refactor-plugins/tasks.md | 2 +- 6 files changed, 6 insertions(+), 1 deletion(-) diff --git a/plugins/ralph-speckit/commands/cancel.md b/plugins/ralph-speckit/commands/cancel.md index 90c50005..1d92fee3 100644 --- a/plugins/ralph-speckit/commands/cancel.md +++ b/plugins/ralph-speckit/commands/cancel.md @@ -1,4 +1,5 @@ --- +name: cancel description: Cancel active execution loop and cleanup state argument-hint: [feature-name] allowed-tools: [Read, Bash, Task] diff --git a/plugins/ralph-speckit/commands/implement.md b/plugins/ralph-speckit/commands/implement.md index 129f10af..3df1e250 100644 --- a/plugins/ralph-speckit/commands/implement.md +++ b/plugins/ralph-speckit/commands/implement.md @@ -1,4 +1,5 @@ --- +name: implement description: Start task execution loop argument-hint: [--max-task-iterations 5] allowed-tools: [Read, Write, Edit, Task, Bash, Skill] diff --git a/plugins/ralph-speckit/commands/start.md b/plugins/ralph-speckit/commands/start.md index 8dd7f207..9c6e5546 100644 --- a/plugins/ralph-speckit/commands/start.md +++ b/plugins/ralph-speckit/commands/start.md @@ -1,4 +1,5 @@ --- +name: start description: Smart entry point for new features with auto ID and branch management argument-hint: [goal] allowed-tools: [Read, Write, Edit, Task, Bash] diff --git a/plugins/ralph-speckit/commands/status.md b/plugins/ralph-speckit/commands/status.md index 28b9d3e5..e82585ca 100644 --- a/plugins/ralph-speckit/commands/status.md +++ b/plugins/ralph-speckit/commands/status.md @@ -1,4 +1,5 @@ --- +name: status description: Show current feature status and progress argument-hint: allowed-tools: [Read, Bash, Glob] diff --git a/plugins/ralph-speckit/commands/switch.md b/plugins/ralph-speckit/commands/switch.md index 32c29335..2bc4233b 100644 --- a/plugins/ralph-speckit/commands/switch.md +++ b/plugins/ralph-speckit/commands/switch.md @@ -1,4 +1,5 @@ --- +name: switch description: Switch active feature argument-hint: allowed-tools: [Read, Write, Bash, Glob, Task] diff --git a/specs/refactor-plugins/tasks.md b/specs/refactor-plugins/tasks.md index f9df354a..9ea7f3de 100644 --- a/specs/refactor-plugins/tasks.md +++ b/specs/refactor-plugins/tasks.md @@ -116,7 +116,7 @@ Focus: Fix all missing frontmatter fields (color, version, matcher, name) and ad ### A4: Command Fixes -- [ ] 1.8 Add name field to ralph-speckit modern commands (5 files) +- [x] 1.8 Add name field to ralph-speckit modern commands (5 files) - **Do**: 1. Add `name: ` field to frontmatter of each command 2. Names: start, status, switch, cancel, implement From 0f617ad0012fe3aed7f1b9e5678ce9615a481fde Mon Sep 17 00:00:00 2001 From: bonfilz Date: Fri, 30 Jan 2026 21:45:08 +0200 Subject: [PATCH 10/37] feat(ralph-speckit): migrate legacy commands to commands/ Migrate 8 legacy commands from .claude/commands/ to commands/: - analyze.md - cross-artifact consistency analysis - checklist.md - requirements quality validation - clarify.md - spec ambiguity detection and resolution - constitution.md - project constitution management - plan.md - implementation planning workflow - specify.md - feature specification creation - tasks.md - task generation from design artifacts - taskstoissues.md - GitHub issue creation from tasks All commands now have proper frontmatter with name, description, and allowed-tools fields. Co-Authored-By: Claude Opus 4.5 --- plugins/ralph-speckit/commands/analyze.md | 186 +++++++++++ plugins/ralph-speckit/commands/checklist.md | 296 ++++++++++++++++++ plugins/ralph-speckit/commands/clarify.md | 183 +++++++++++ .../ralph-speckit/commands/constitution.md | 84 +++++ plugins/ralph-speckit/commands/plan.md | 91 ++++++ plugins/ralph-speckit/commands/specify.md | 260 +++++++++++++++ plugins/ralph-speckit/commands/tasks.md | 139 ++++++++ .../ralph-speckit/commands/taskstoissues.md | 31 ++ specs/refactor-plugins/tasks.md | 2 +- 9 files changed, 1271 insertions(+), 1 deletion(-) create mode 100644 plugins/ralph-speckit/commands/analyze.md create mode 100644 plugins/ralph-speckit/commands/checklist.md create mode 100644 plugins/ralph-speckit/commands/clarify.md create mode 100644 plugins/ralph-speckit/commands/constitution.md create mode 100644 plugins/ralph-speckit/commands/plan.md create mode 100644 plugins/ralph-speckit/commands/specify.md create mode 100644 plugins/ralph-speckit/commands/tasks.md create mode 100644 plugins/ralph-speckit/commands/taskstoissues.md diff --git a/plugins/ralph-speckit/commands/analyze.md b/plugins/ralph-speckit/commands/analyze.md new file mode 100644 index 00000000..272992b6 --- /dev/null +++ b/plugins/ralph-speckit/commands/analyze.md @@ -0,0 +1,186 @@ +--- +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 + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`. + +## Operating Constraints + +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). + +**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`. + +## Execution Steps + +### 1. Initialize Analysis Context + +Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: + +- SPEC = FEATURE_DIR/spec.md +- PLAN = FEATURE_DIR/plan.md +- TASKS = FEATURE_DIR/tasks.md + +Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +### 2. Load Artifacts (Progressive Disclosure) + +Load only the minimal necessary context from each artifact: + +**From spec.md:** + +- Overview/Context +- Functional Requirements +- Non-Functional Requirements +- User Stories +- Edge Cases (if present) + +**From plan.md:** + +- Architecture/stack choices +- Data Model references +- Phases +- Technical constraints + +**From tasks.md:** + +- Task IDs +- Descriptions +- Phase grouping +- Parallel markers [P] +- Referenced file paths + +**From constitution:** + +- Load `.specify/memory/constitution.md` for principle validation + +### 3. Build Semantic Models + +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`) +- **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 + +### 4. Detection Passes (Token-Efficient Analysis) + +Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary. + +#### A. Duplication Detection + +- Identify near-duplicate requirements +- Mark lower-quality phrasing for consolidation + +#### B. Ambiguity Detection + +- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria +- Flag unresolved placeholders (TODO, TKTK, ???, ``, etc.) + +#### C. Underspecification + +- Requirements with verbs but missing object or measurable outcome +- User stories missing acceptance criteria alignment +- Tasks referencing files or components not defined in spec/plan + +#### D. Constitution Alignment + +- Any requirement or plan element conflicting with a MUST principle +- Missing mandated sections or quality gates from constitution + +#### E. Coverage Gaps + +- Requirements with zero associated tasks +- Tasks with no mapped requirement/story +- Non-functional requirements not reflected in tasks (e.g., performance, security) + +#### F. Inconsistency + +- Terminology drift (same concept named differently across files) +- Data entities referenced in plan but absent in spec (or vice versa) +- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note) +- Conflicting requirements (e.g., one requires Next.js while other specifies Vue) + +### 5. Severity Assignment + +Use this heuristic to prioritize findings: + +- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality +- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion +- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case +- **LOW**: Style/wording improvements, minor redundancy not affecting execution order + +### 6. Produce Compact Analysis Report + +Output a Markdown report (no file writes) with the following structure: + +## Specification Analysis Report + +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | + +(Add one row per finding; generate stable IDs prefixed by category initial.) + +**Coverage Summary Table:** + +| Requirement Key | Has Task? | Task IDs | Notes | +|-----------------|-----------|----------|-------| + +**Constitution Alignment Issues:** (if any) + +**Unmapped Tasks:** (if any) + +**Metrics:** + +- Total Requirements +- Total Tasks +- Coverage % (requirements with >=1 task) +- Ambiguity Count +- Duplication Count +- Critical Issues Count + +### 7. Provide Next Actions + +At end of report, output a concise Next Actions block: + +- If CRITICAL issues exist: Recommend resolving before `/speckit.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" + +### 8. Offer Remediation + +Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) + +## Operating Principles + +### Context Efficiency + +- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation +- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis +- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow +- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts + +### Analysis Guidelines + +- **NEVER modify files** (this is read-only analysis) +- **NEVER hallucinate missing sections** (if absent, report them accurately) +- **Prioritize constitution violations** (these are always CRITICAL) +- **Use examples over exhaustive rules** (cite specific instances, not generic patterns) +- **Report zero issues gracefully** (emit success report with coverage statistics) + +## Context + +$ARGUMENTS diff --git a/plugins/ralph-speckit/commands/checklist.md b/plugins/ralph-speckit/commands/checklist.md new file mode 100644 index 00000000..d8359769 --- /dev/null +++ b/plugins/ralph-speckit/commands/checklist.md @@ -0,0 +1,296 @@ +--- +name: checklist +description: Generate a custom checklist for the current feature based on user requirements. +allowed-tools: [Read, Write, Bash] +--- + +## Checklist Purpose: "Unit Tests for English" + +**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. + +**NOT for verification/testing**: + +- NOT "Verify the button clicks correctly" +- NOT "Test error handling works" +- NOT "Confirm the API returns 200" +- NOT checking if code/implementation matches the spec + +**FOR requirements quality validation**: + +- "Are visual hierarchy requirements defined for all card types?" (completeness) +- "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) +- "Are hover state requirements consistent across all interactive elements?" (consistency) +- "Are accessibility requirements defined for keyboard navigation?" (coverage) +- "Does the spec define what happens when logo image fails to load?" (edge cases) + +**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Execution Steps + +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list. + - All file paths must be absolute. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST: + - Be generated from the user's phrasing + extracted signals from spec/plan/tasks + - Only ask about information that materially changes checklist content + - Be skipped individually if already unambiguous in `$ARGUMENTS` + - Prefer precision over breadth + + Generation algorithm: + 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). + 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. + 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit. + 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria. + 5. Formulate questions chosen from these archetypes: + - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?") + - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?") + - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?") + - Audience framing (e.g., "Will this be used by the author only or peers during PR review?") + - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?") + - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?") + + Question formatting rules: + - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters + - Limit to A–E options maximum; omit table if a free-form answer is clearer + - Never ask the user to restate what they already said + - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." + + Defaults when interaction impossible: + - Depth: Standard + - Audience: Reviewer (PR) if code-related; Author otherwise + - Focus: Top 2 relevance clusters + + Output the questions (label Q1/Q2/Q3). After answers: if >=2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow-ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more. + +3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: + - Derive checklist theme (e.g., security, review, deploy, ux) + - Consolidate explicit must-have items mentioned by user + - Map focus selections to category scaffolding + - Infer any missing context from spec/plan/tasks (do NOT hallucinate) + +4. **Load feature context**: Read from FEATURE_DIR: + - spec.md: Feature requirements and scope + - plan.md (if exists): Technical details, dependencies + - tasks.md (if exists): Implementation tasks + + **Context Loading Strategy**: + - Load only necessary portions relevant to active focus areas (avoid full-file dumping) + - Prefer summarizing long sections into concise scenario/requirement bullets + - Use progressive disclosure: add follow-on retrieval only if gaps detected + - If source docs are large, generate interim summary items instead of embedding raw text + +5. **Generate checklist** - Create "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if it doesn't exist + - Generate unique checklist filename: + - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) + - Format: `[domain].md` + - If file exists, append to existing file + - Number items sequentially starting from CHK001 + - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists) + + **CORE PRINCIPLE - Test the Requirements, Not the Implementation**: + Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: + - **Completeness**: Are all necessary requirements present? + - **Clarity**: Are requirements unambiguous and specific? + - **Consistency**: Do requirements align with each other? + - **Measurability**: Can requirements be objectively verified? + - **Coverage**: Are all scenarios/edge cases addressed? + + **Category Structure** - Group items by requirement quality dimensions: + - **Requirement Completeness** (Are all necessary requirements documented?) + - **Requirement Clarity** (Are requirements specific and unambiguous?) + - **Requirement Consistency** (Do requirements align without conflicts?) + - **Acceptance Criteria Quality** (Are success criteria measurable?) + - **Scenario Coverage** (Are all flows/cases addressed?) + - **Edge Case Coverage** (Are boundary conditions defined?) + - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?) + - **Dependencies & Assumptions** (Are they documented and validated?) + - **Ambiguities & Conflicts** (What needs clarification?) + + **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: + + WRONG (Testing implementation): + - "Verify landing page displays 3 episode cards" + - "Test hover states work on desktop" + - "Confirm logo click navigates home" + + CORRECT (Testing requirements quality): + - "Are the exact number and layout of featured episodes specified?" [Completeness] + - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] + - "Are hover state requirements consistent across all interactive elements?" [Consistency] + - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] + - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] + - "Are loading states defined for asynchronous episode data?" [Completeness] + - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] + + **ITEM STRUCTURE**: + Each item should follow this pattern: + - Question format asking about requirement quality + - Focus on what's WRITTEN (or not written) in the spec/plan + - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] + - Reference spec section `[Spec X.Y]` when checking existing requirements + - Use `[Gap]` marker when checking for missing requirements + + **EXAMPLES BY QUALITY DIMENSION**: + + Completeness: + - "Are error handling requirements defined for all API failure modes? [Gap]" + - "Are accessibility requirements specified for all interactive elements? [Completeness]" + - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" + + Clarity: + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec NFR-2]" + - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec FR-5]" + - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec FR-4]" + + Consistency: + - "Do navigation requirements align across all pages? [Consistency, Spec FR-10]" + - "Are card component requirements consistent between landing and detail pages? [Consistency]" + + Coverage: + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" + - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" + - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" + + Measurability: + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec FR-1]" + - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec FR-2]" + + **Scenario Classification & Coverage** (Requirements Quality Focus): + - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios + - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" + - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]" + - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]" + + **Traceability Requirements**: + - MINIMUM: >=80% of items MUST include at least one traceability reference + - Each item should reference: spec section `[Spec X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]` + - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]" + + **Surface & Resolve Issues** (Requirements Quality Problems): + Ask questions about the requirements themselves: + - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec NFR-1]" + - Conflicts: "Do navigation requirements conflict between FR-10 and FR-10a? [Conflict]" + - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" + - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" + - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" + + **Content Consolidation**: + - Soft cap: If raw candidate items > 40, prioritize by risk/impact + - Merge near-duplicates checking the same requirement aspect + - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]" + + **ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test: + - Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior + - References to code execution, user actions, system behavior + - "Displays correctly", "works properly", "functions as expected" + - "Click", "navigate", "render", "load", "execute" + - Test cases, test plans, QA procedures + - Implementation details (frameworks, APIs, algorithms) + + **REQUIRED PATTERNS** - These test requirements quality: + - "Are [requirement type] defined/specified/documented for [scenario]?" + - "Is [vague term] quantified/clarified with specific criteria?" + - "Are requirements consistent between [section A] and [section B]?" + - "Can [requirement] be objectively measured/verified?" + - "Are [edge cases/scenarios] addressed in requirements?" + - "Does the spec define [missing aspect]?" + +6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### ` lines with globally incrementing IDs starting at CHK001. + +7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize: + - Focus areas selected + - Depth level + - Actor/timing + - Any explicit user-specified must-have items incorporated + +**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows: + +- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`) +- Simple, memorable filenames that indicate checklist purpose +- Easy identification and navigation in the `checklists/` folder + +To avoid clutter, use descriptive types and clean up obsolete checklists when done. + +## Example Checklist Types & Sample Items + +**UX Requirements Quality:** `ux.md` + +Sample items (testing the requirements, NOT the implementation): + +- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec FR-1]" +- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec FR-1]" +- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" +- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" +- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" +- "Can 'prominent display' be objectively measured? [Measurability, Spec FR-4]" + +**API Requirements Quality:** `api.md` + +Sample items: + +- "Are error response formats specified for all failure scenarios? [Completeness]" +- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" +- "Are authentication requirements consistent across all endpoints? [Consistency]" +- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" +- "Is versioning strategy documented in requirements? [Gap]" + +**Performance Requirements Quality:** `performance.md` + +Sample items: + +- "Are performance requirements quantified with specific metrics? [Clarity]" +- "Are performance targets defined for all critical user journeys? [Coverage]" +- "Are performance requirements under different load conditions specified? [Completeness]" +- "Can performance requirements be objectively measured? [Measurability]" +- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" + +**Security Requirements Quality:** `security.md` + +Sample items: + +- "Are authentication requirements specified for all protected resources? [Coverage]" +- "Are data protection requirements defined for sensitive information? [Completeness]" +- "Is the threat model documented and requirements aligned to it? [Traceability]" +- "Are security requirements consistent with compliance obligations? [Consistency]" +- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" + +## Anti-Examples: What NOT To Do + +**WRONG - These test implementation, not requirements:** + +```markdown +- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec FR-001] +- [ ] CHK002 - Test hover states work correctly on desktop [Spec FR-003] +- [ ] CHK003 - Confirm logo click navigates to home page [Spec FR-010] +- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec FR-005] +``` + +**CORRECT - These test requirements quality:** + +```markdown +- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec FR-001] +- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec FR-003] +- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec FR-010] +- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec FR-005] +- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap] +- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec FR-001] +``` + +**Key Differences:** + +- Wrong: Tests if the system works correctly +- Correct: Tests if the requirements are written correctly +- Wrong: Verification of behavior +- Correct: Validation of requirement quality +- Wrong: "Does it do X?" +- Correct: "Is X clearly specified?" diff --git a/plugins/ralph-speckit/commands/clarify.md b/plugins/ralph-speckit/commands/clarify.md new file mode 100644 index 00000000..4bdfccc0 --- /dev/null +++ b/plugins/ralph-speckit/commands/clarify.md @@ -0,0 +1,183 @@ +--- +name: clarify +description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +allowed-tools: [Read, Write, Edit, Bash] +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. + +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. + +Execution steps: + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: + - `FEATURE_DIR` + - `FEATURE_SPEC` + - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) + - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). + + Functional Scope & Behavior: + - Core user goals & success criteria + - Explicit out-of-scope declarations + - User roles / personas differentiation + + Domain & Data Model: + - Entities, attributes, relationships + - Identity & uniqueness rules + - Lifecycle/state transitions + - Data volume / scale assumptions + + Interaction & UX Flow: + - Critical user journeys / sequences + - Error/empty/loading states + - Accessibility or localization notes + + Non-Functional Quality Attributes: + - Performance (latency, throughput targets) + - Scalability (horizontal/vertical, limits) + - Reliability & availability (uptime, recovery expectations) + - Observability (logging, metrics, tracing signals) + - Security & privacy (authN/Z, data protection, threat assumptions) + - Compliance / regulatory constraints (if any) + + Integration & External Dependencies: + - External services/APIs and failure modes + - Data import/export formats + - Protocol/versioning assumptions + + Edge Cases & Failure Handling: + - Negative scenarios + - Rate limiting / throttling + - Conflict resolution (e.g., concurrent edits) + + Constraints & Tradeoffs: + - Technical constraints (language, storage, hosting) + - Explicit tradeoffs or rejected alternatives + + Terminology & Consistency: + - Canonical glossary terms + - Avoided synonyms / deprecated terms + + Completion Signals: + - Acceptance criteria testability + - Measurable Definition of Done style indicators + + Misc / Placeholders: + - TODO markers / unresolved decisions + - Ambiguous adjectives ("robust", "intuitive") lacking quantification + + For each category with Partial or Missing status, add a candidate question opportunity unless: + - Clarification would not materially change implementation or validation strategy + - Information is better deferred to planning phase (note internally) + +3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: + - Maximum of 10 total questions across the whole session. + - Each question must be answerable with EITHER: + - A short multiple-choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short-phrase answer (explicitly constrain: "Answer in <=5 words"). + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. + - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. + - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). + - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. + - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. + +4. Sequential questioning loop (interactive): + - Present EXACTLY ONE question at a time. + - For multiple-choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |