Implement Ralph Loop methodology for self-correcting implementation

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "shipspec",
       "description": "Spec-driven development for Claude Code. Plan bigger features with persistent PRDs, technical designs, and implementation tasks that keep your AI coding agent on track across sessions.",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "author": {
         "name": "ShipSpec"
       },

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shipspec",
   "description": "Spec-driven development for big features. When features get too big, plan mode gets too vague—leading to hallucinations during implementation. ShipSpec replaces vague plans with structured PRDs, technical designs, and ordered tasks that keep Claude grounded.",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": {
     "name": "ShipSpec"
   },

CLAUDE.md

@@ -0,0 +1,128 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ShipSpec is a Claude Code plugin for spec-driven feature development. It replaces vague plans with structured PRDs (Product Requirements Documents), SDDs (Software Design Documents), and ordered tasks with acceptance criteria.
+
+## Plugin Architecture
+
+```
+shipspec/
+├── commands/           # User-invocable slash commands
+│   ├── feature-planning.md    # 7-phase planning workflow
+│   ├── implement-task.md      # Single task implementation with verification
+│   ├── implement-feature.md   # Full feature implementation loop
+│   ├── cancel-task-loop.md    # Cancel active task retry loop
+│   └── cancel-feature-retry.md
+├── agents/             # Specialized subagents (Task tool invocations)
+│   ├── prd-gatherer.md        # Requirements elicitation
+│   ├── design-architect.md    # Technical design decisions
+│   ├── task-planner.md        # Task decomposition
+│   ├── task-manager.md        # Read-only TASKS.md parsing/validation
+│   ├── task-verifier.md       # Acceptance criteria verification
+│   └── planning-validator.md  # PRD/SDD alignment checking
+├── skills/             # Reusable skill templates (invoked via skill loader)
+│   ├── prd-template/          # PRD structure and patterns
+│   ├── sdd-template/          # Atlassian 8-section SDD format
+│   ├── codebase-context/      # Tech stack extraction
+│   ├── agent-prompts/         # Task prompt generation
+│   ├── research/              # Web/doc research patterns
+│   └── task-loop-verify/      # Loop verification skill
+├── hooks/              # Stop hooks for Ralph Loop methodology
+│   ├── hooks.json             # Hook registration
+│   ├── task-loop-hook.sh      # Per-task auto-retry
+│   ├── feature-retry-hook.sh  # Feature-wide task retry
+│   └── planning-refine-hook.sh # Large task refinement
+└── .claude-plugin/     # Plugin metadata
+    └── plugin.json
+```
+
+## Key Workflows
+
+### Feature Planning (`/feature-planning`)
+7-phase workflow: Description → Setup → Requirements Gathering → PRD Generation → Technical Decisions → SDD Generation → Task Generation
+
+Output: `.shipspec/planning/{feature}/PRD.md`, `SDD.md`, `TASKS.md`
+
+### Task Implementation (`/implement-task`, `/implement-feature`)
+1. Parse and validate TASKS.md via `task-manager` agent
+2. Find next ready task (dependencies satisfied)
+3. Mark task `[~]` (in-progress)
+4. Create loop state file for auto-retry
+5. Implement and verify via `task-verifier` agent
+6. Mark `[x]` on success, retry on failure
+
+## Ralph Loop Methodology
+
+Stop hooks intercept Claude's exit and feed prompts back until completion markers are detected:
+- `<task-loop-complete>VERIFIED|INCOMPLETE|BLOCKED|MISALIGNED</task-loop-complete>`
+- `<feature-task-complete>VERIFIED|BLOCKED</feature-task-complete>`
+- `<feature-complete>APPROVED|APPROVED_WITH_WARNINGS</feature-complete>`
+
+State files are stored alongside planning artifacts in `.shipspec/planning/<feature>/`.
+
+## Hook Behavior
+
+All hooks share stdin sequentially. Each hook:
+1. Checks for pointer file (`.shipspec/active-loop.local.md`) first
+2. Parses pointer to check if this hook's loop type is active
+3. If not this hook's loop type, exits immediately (preserves stdin for other hooks)
+4. If active, reads the state file from `.shipspec/planning/<feature>/<loop-type>.local.md`
+
+Empty stdin detection prevents erroneous state file deletion when multiple hooks are active.
+
+## Development Notes
+
+### Testing Hooks
+Hooks expect JSON input with `transcript_path` field. Test with:
+```bash
+echo '{"transcript_path": "/path/to/transcript.jsonl"}' | ./hooks/task-loop-hook.sh
+```
+
+### Pointer File Format (`.shipspec/active-loop.local.md`)
+```yaml
+---
+feature: feature-name
+loop_type: task-loop|feature-retry|planning-refine
+state_path: .shipspec/planning/feature-name/task-loop.local.md
+created_at: "2024-01-15T10:30:00Z"
+---
+```
+
+### State File Format (`.shipspec/planning/<feature>/<loop-type>.local.md`)
+```yaml
+---
+active: true
+feature: feature-name
+task_id: TASK-001
+iteration: 1
+max_iterations: 5
+---
+
+[Full task prompt content here]
+```
+
+### Task Status Markers
+- `[ ]` - Not started
+- `[~]` - In progress
+- `[x]` - Completed
+
+### Requirement Numbering
+- REQ-001 to REQ-009: Core Features
+- REQ-010 to REQ-019: User Interface
+- REQ-020 to REQ-029: Data & Storage
+- REQ-030 to REQ-039: Integration
+- REQ-040 to REQ-049: Performance
+- REQ-050 to REQ-059: Security
+
+### Task Sizing
+Fibonacci story points (1, 2, 3, 5, 8). Tasks >5 points trigger auto-refinement.
+
+### Version Bumping
+When updating the plugin version, update both files:
+- `.claude-plugin/plugin.json` - the actual plugin version
+- `.claude-plugin/marketplace.json` - the version advertised in the marketplace
+
+These are not automatically synced.

README.md

@@ -192,6 +192,45 @@ The `/implement-feature` command implements all tasks and runs a comprehensive f
 - **Use `/implement-task` to work through tasks manually**: Tracks progress and verifies completion
 - **Use `/implement-feature` for automation**: Implements all tasks and runs comprehensive final review
 
+## Ralph Loop Methodology
+
+This plugin uses the [Ralph Loop](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop) methodology for iterative, self-correcting implementation.
+
+### What is Ralph Loop?
+
+Ralph Loop is a development methodology based on continuous AI agent loops. The core concept: use a **Stop hook** to intercept Claude's exit attempts and feed the same prompt back until the task is complete. This creates a self-referential feedback loop where Claude iteratively improves its work.
+
+### How ShipSpec Uses It
+
+ShipSpec adapts Ralph Loop for structured feature development:
+
+| Feature | Ralph Loop Technique |
+|---------|---------------------|
+| `/implement-task` auto-retry | Stop hook blocks exit on failed verification, retries until VERIFIED or max attempts |
+| `/implement-feature` per-task retry | Same mechanism, applied to each task during full-feature implementation |
+| `/feature-planning` task refinement | Stop hook triggers re-analysis of large tasks (>5 story points) |
+
+### Key Components
+
+1. **Stop Hooks** - Intercept session exit and trigger retry loops
+2. **State Files** - Track iteration count and current task:
+   - Pointer: `.shipspec/active-loop.local.md`
+   - State: `.shipspec/planning/<feature>/<loop-type>.local.md`
+3. **Completion Markers** - Signal successful completion (`<task-loop-complete>VERIFIED</task-loop-complete>`)
+4. **Max Iterations** - Safety limit to prevent infinite loops (default: 5 attempts per task)
+
+### Philosophy
+
+From Ralph Loop:
+- **Iteration > Perfection** - Don't aim for perfect on first try; let the loop refine the work
+- **Failures Are Data** - Failed verification tells Claude exactly what to fix
+- **Persistence Wins** - Keep trying until success; the loop handles retry logic automatically
+
+### Learn More
+
+- [Ralph Loop Plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop)
+- [Original Ralph Technique](https://ghuntley.com/ralph/)
+
 ## Issues & Feedback
 
 Found a bug or have a suggestion? [Submit an issue](https://github.com/jsegov/shipspec-claude-code-plugin/issues)

agents/task-verifier.md

@@ -45,6 +45,22 @@ You will receive:
 
 ## Verification Process
 
+### Step 0: Check for Completion Promise
+
+If the task prompt contains a `## Completion Promise` section:
+
+1. Extract the promise text (the identifier between `<promise>` tags expected)
+2. Search recent assistant messages in the conversation for `<promise>EXACT_TEXT</promise>`
+3. **If promise found and matches exactly:**
+   - Set `promise_matched = true`
+   - Note in report: "Completion promise detected and matched"
+4. **If promise section exists but no matching promise found:**
+   - Set `promise_matched = false`
+   - Continue to Step 1 (standard verification applies)
+5. **If task has NO Completion Promise section:**
+   - Set `promise_matched = false` (not applicable)
+   - Continue to Step 1 normally
+
 ### Step 1: Extract Acceptance Criteria
 
 Parse the task prompt to find the `## Acceptance Criteria` section. Each line starting with `- [ ]` or `- [x]` is a criterion to verify.
@@ -198,10 +214,24 @@ git diff --name-only HEAD~5
 ## Edge Cases
 
 ### Cannot Verify
-If a criterion cannot be verified (e.g., "User experience is smooth"), mark as CANNOT_VERIFY and note why:
-- Requires manual testing
-- Requires running application
-- Subjective criterion
+
+If a criterion cannot be verified, behavior depends on whether a completion promise was matched in Step 0:
+
+**If completion promise WAS matched (promise_matched = true):**
+- Treat subjective CANNOT_VERIFY criteria as PASS
+- The developer's promise signal counts as explicit verification
+- Example: If criterion is "Documentation is clear (SUBJECTIVE)" and promise matched → PASS
+- Non-subjective CANNOT_VERIFY items (e.g., missing test infrastructure) remain CANNOT_VERIFY
+
+**If completion promise was NOT matched:**
+- Mark subjective criteria as CANNOT_VERIFY with reason:
+  - Requires manual testing
+  - Requires running application
+  - Subjective criterion
+- These do NOT block task completion
+
+**How to identify subjective criteria:**
+Look for markers like "(SUBJECTIVE)", "(subjective)", "clear", "intuitive", "smooth", "user experience" in the criterion text.
 
 ### Partial Completion
 If some criteria pass but others fail, status is INCOMPLETE. List exactly what needs to be fixed.
@@ -233,3 +263,28 @@ Always end with one of these clear verdicts:
 3. **Be helpful**: If something fails, explain how to fix it
 4. **Be honest**: If you can't verify something, say so
 5. **Check related files**: Sometimes implementation spans multiple files
+
+## Completion Promise Format
+
+Tasks with subjective criteria can include this section to enable explicit completion signals:
+
+```markdown
+## Completion Promise
+
+To signal completion, output: <promise>UNIQUE_IDENTIFIER</promise>
+
+**This promise should only be output when:**
+- [List specific conditions for this task]
+
+Do NOT output this promise if unsure or to exit early.
+```
+
+**Promise requirements:**
+- The promise text must be a meaningful identifier (e.g., "API_DESIGN_COMPLETE", "DATABASE_SCHEMA_DONE")
+- Must appear verbatim in `<promise>TEXT</promise>` XML tags
+- Match is case-sensitive with no extra whitespace
+
+**When promise is matched:**
+- Subjective criteria marked "(SUBJECTIVE)" are treated as PASS
+- Non-subjective CANNOT_VERIFY items still remain CANNOT_VERIFY
+- Report notes: "Completion promise detected and matched"

commands/cancel-feature-retry.md

@@ -0,0 +1,74 @@
+---
+description: Cancel active feature implementation retry loop
+allowed-tools:
+  - Bash(test:*)
+  - Bash(rm:*)
+  - Bash(grep:*)
+  - Bash(sed:*)
+  - Read
+---
+
+# Cancel Feature Retry
+
+Cancel an active feature implementation retry loop.
+
+## Step 1: Check for Active Loop
+
+Check for the pointer file:
+```bash
+test -f .shipspec/active-loop.local.md && echo "POINTER_EXISTS" || echo "NOT_FOUND"
+```
+
+**If NOT_FOUND:**
+> "No active feature retry loop found."
+
+**Stop here.**
+
+**If POINTER_EXISTS:**
+Read the pointer file and verify it's a feature-retry:
+```bash
+grep "^loop_type:" .shipspec/active-loop.local.md
+```
+
+**If loop_type is NOT "feature-retry":**
+> "No active feature retry loop found. (A different loop type is active)"
+
+**Stop here.**
+
+## Step 2: Read Current State
+
+Extract the state path from the pointer:
+```bash
+grep "^state_path:" .shipspec/active-loop.local.md | sed 's/state_path: *//'
+```
+
+Read the state file using the extracted path:
+```
+Read [state_path]
+```
+
+Extract from the YAML frontmatter:
+- `current_task_id` - the task being implemented
+- `feature` - the feature name
+- `task_attempt` - current attempt number for the task
+- `max_task_attempts` - maximum attempts per task
+- `tasks_completed` - number of completed tasks
+- `total_tasks` - total number of tasks
+
+## Step 3: Cancel the Loop
+
+Remove both the state file and pointer:
+
+```bash
+rm -f [state_path] .shipspec/active-loop.local.md
+```
+
+## Step 4: Report
+
+> "Cancelled feature retry for **[FEATURE]**
+>
+> - Current task: [CURRENT_TASK_ID] (attempt [TASK_ATTEMPT]/[MAX_TASK_ATTEMPTS])
+> - Progress: [TASKS_COMPLETED]/[TOTAL_TASKS] tasks completed
+>
+> The current task remains in `[~]` (in-progress) status in TASKS.md.
+> Run `/implement-feature [feature]` to resume, or `/implement-task [feature]` to continue task-by-task."