feat: add ralph-loop plugin and update author info

.claude-plugin/marketplace.json

@@ -3,22 +3,35 @@
   "name": "claude-plugin-boilerplate",
   "description": "Standard boilerplate for creating Claude Code plugins with testing, CI/CD, and validation",
   "owner": {
-    "name": "Your Name",
-    "email": "your.email@example.com"
+    "name": "jito",
+    "email": "git@baleen.me"
   },
   "plugins": [
     {
       "name": "example-plugin",
       "description": "Example plugin demonstrating all component types",
       "version": "1.0.0",
       "author": {
-        "name": "Your Name",
-        "email": "your.email@example.com"
+        "name": "jito",
+        "email": "git@baleen.me"
       },
       "source": "./plugins/example-plugin",
       "category": "development",
       "tags": ["boilerplate", "example", "template"],
       "strict": false
+    },
+    {
+      "name": "ralph-loop",
+      "description": "Continuous self-referential AI loops for interactive iterative development, implementing the Ralph Wiggum technique",
+      "version": "1.0.0",
+      "author": {
+        "name": "Anthropic",
+        "email": "support@anthropic.com"
+      },
+      "source": "./plugins/ralph-loop",
+      "category": "development",
+      "tags": ["automation", "iteration", "loop", "ai"],
+      "strict": false
     }
   ]
 }

.github/workflows/test.yml

@@ -12,10 +12,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install BATS
+      - name: Install BATS and helpers
         run: |
           git clone --depth 1 --branch v1.10.0 https://github.com/bats-core/bats-core.git /tmp/bats
           sudo /tmp/bats/install.sh /usr/local
+          mkdir -p tests/helpers
+          git clone --depth 1 --branch v0.3.0 https://github.com/bats-core/bats-support.git tests/helpers/bats-support
+          git clone --depth 1 --branch v0.3.0 https://github.com/bats-core/bats-assert.git tests/helpers/bats-assert
 
       - name: Run tests
         run: bats tests/

README.md

@@ -6,7 +6,7 @@ Standard boilerplate for creating Claude Code plugins with testing, CI/CD, and v
 
 - Standard Structure: Follows anthropics/claude-plugins-official patterns
 - Validation Scripts: JSON, YAML, naming, and path validation
-- BATS Tests: Comprehensive test suite
+- Structure Validation: Plugin structure and component verification
 - CI/CD: GitHub Actions workflows for PR validation and releases
 - Pre-commit Hooks: Automated quality checks
 - Example Plugin: Demonstrates all component types
@@ -17,7 +17,7 @@ Standard boilerplate for creating Claude Code plugins with testing, CI/CD, and v
 
 ```bash
 # Clone the repository
-git clone https://github.com/YOUR_USERNAME/claude-plugin-boilerplate.git
+git clone https://github.com/jito/claude-plugin-boilerplate.git
 cd claude-plugin-boilerplate
 
 # Install as a marketplace
@@ -43,9 +43,6 @@ cp -r plugins/example-plugin plugins/my-plugin
 # Validate all plugins
 bash scripts/validate-plugin.sh
 
-# Run tests
-bats tests/
-
 # Run pre-commit hooks manually
 pre-commit run --all-files
 ```
@@ -66,7 +63,6 @@ claude-plugin-boilerplate/
 │       └── hooks/
 ├── .github/workflows/            # CI/CD workflows
 ├── scripts/                      # Validation scripts
-├── tests/                        # BATS tests
 └── schemas/                      # JSON schemas
 ```
 

plugins/example-plugin/.claude-plugin/plugin.json

@@ -4,11 +4,11 @@
   "description": "Example plugin demonstrating all Claude Code plugin component types",
   "version": "1.0.0",
   "author": {
-    "name": "Your Name",
-    "email": "your.email@example.com"
+    "name": "jito",
+    "email": "git@baleen.me"
   },
-  "homepage": "https://github.com/YOUR_USERNAME/claude-plugin-boilerplate",
-  "repository": "https://github.com/YOUR_USERNAME/claude-plugin-boilerplate",
+  "homepage": "https://github.com/jito/claude-plugin-boilerplate",
+  "repository": "https://github.com/jito/claude-plugin-boilerplate",
   "license": "MIT",
   "keywords": ["claude-code", "plugin", "boilerplate", "example"]
 }

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

@@ -0,0 +1,8 @@
+{
+  "name": "ralph-loop",
+  "description": "Continuous self-referential AI loops for interactive iterative development, implementing the Ralph Wiggum technique. Run Claude in a while-true loop with the same prompt until task completion.",
+  "author": {
+    "name": "Anthropic",
+    "email": "support@anthropic.com"
+  }
+}

plugins/ralph-loop/README.md

@@ -0,0 +1,177 @@
+# Ralph Loop Plugin
+
+Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in Claude Code.
+
+## What is Ralph Loop?
+
+Ralph Loop is a development methodology based on continuous AI agent loops. As Geoffrey Huntley describes it: **"Ralph is a Bash loop"** - a simple `while true` that repeatedly feeds an AI agent a prompt file, allowing it to iteratively improve its work until completion.
+
+This technique is inspired by the Ralph Wiggum coding technique (named after the character from The Simpsons), embodying the philosophy of persistent iteration despite setbacks.
+
+### Core Concept
+
+This plugin implements Ralph using a **Stop hook** that intercepts Claude's exit attempts:
+
+```bash
+# You run ONCE:
+/ralph-loop "Your task description" --completion-promise "DONE"
+
+# Then Claude Code automatically:
+# 1. Works on the task
+# 2. Tries to exit
+# 3. Stop hook blocks exit
+# 4. Stop hook feeds the SAME prompt back
+# 5. Repeat until completion
+```
+
+The loop happens **inside your current session** - you don't need external bash loops. The Stop hook in `hooks/stop-hook.sh` creates the self-referential feedback loop by blocking normal session exit.
+
+This creates a **self-referential feedback loop** where:
+- The prompt never changes between iterations
+- Claude's previous work persists in files
+- Each iteration sees modified files and git history
+- Claude autonomously improves by reading its own past work in files
+
+## Quick Start
+
+```bash
+/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output COMPLETE when done." --completion-promise "COMPLETE" --max-iterations 50
+```
+
+Claude will:
+- Implement the API iteratively
+- Run tests and see failures
+- Fix bugs based on test output
+- Iterate until all requirements met
+- Output the completion promise when done
+
+## Commands
+
+### /ralph-loop
+
+Start a Ralph loop in your current session.
+
+**Usage:**
+```bash
+/ralph-loop "<PROMPT>" [--max-iterations <N>] [--completion-promise "<TEXT>"]
+```
+
+**Options:**
+- `--max-iterations <N>` - Stop after N iterations (default: unlimited)
+- `--completion-promise <TEXT>` - Phrase that signals completion
+
+### /cancel-ralph
+
+Cancel the active Ralph loop.
+
+**Usage:**
+```bash
+/cancel-ralph
+```
+
+## Prompt Writing Best Practices
+
+### 1. Clear Completion Criteria
+
+❌ Bad: "Build a todo API and make it good."
+
+✅ Good:
+```markdown
+Build a REST API for todos.
+When complete:
+- All CRUD endpoints working
+- Input validation in place
+- Tests passing (coverage > 80%)
+- README with API docs
+Output: COMPLETE
+```
+
+### 2. Incremental Goals
+
+❌ Bad: "Create a complete e-commerce platform."
+
+✅ Good:
+```markdown
+Phase 1: User authentication (JWT, tests)
+Phase 2: Product catalog (list/search, tests)
+Phase 3: Shopping cart (add/remove, tests)
+Output COMPLETE when all phases done.
+```
+
+### 3. Self-Correction
+
+❌ Bad: "Write code for feature X."
+
+✅ Good:
+```markdown
+Implement feature X following TDD:
+1. Write failing tests
+2. Implement feature
+3. Run tests
+4. If any fail, debug and fix
+5. Refactor if needed
+6. Repeat until all green
+7. Output: COMPLETE
+```
+
+### 4. Escape Hatches
+
+Always use `--max-iterations` as a safety net to prevent infinite loops on impossible tasks:
+
+```bash
+# Recommended: Always set a reasonable iteration limit
+/ralph-loop "Try to implement feature X" --max-iterations 20
+
+# In your prompt, include what to do if stuck:
+# "After 15 iterations, if not complete:
+# - Document what's blocking progress
+# - List what was attempted
+# - Suggest alternative approaches"
+```
+
+**Note**: The `--completion-promise` uses exact string matching, so you cannot use it for multiple completion conditions (like "SUCCESS" vs "BLOCKED"). Always rely on `--max-iterations` as your primary safety mechanism.
+
+## Philosophy
+
+Ralph embodies several key principles:
+
+### 1. Iteration > Perfection
+Don't aim for perfect on first try. Let the loop refine the work.
+
+### 2. Failures Are Data
+"Deterministically bad" means failures are predictable and informative. Use them to tune prompts.
+
+### 3. Operator Skill Matters
+Success depends on writing good prompts, not just having a good model.
+
+### 4. Persistence Wins
+Keep trying until success. The loop handles retry logic automatically.
+
+## When to Use Ralph
+
+**Good for:**
+- Well-defined tasks with clear success criteria
+- Tasks requiring iteration and refinement (e.g., getting tests to pass)
+- Greenfield projects where you can walk away
+- Tasks with automatic verification (tests, linters)
+
+**Not good for:**
+- Tasks requiring human judgment or design decisions
+- One-shot operations
+- Tasks with unclear success criteria
+- Production debugging (use targeted debugging instead)
+
+## Real-World Results
+
+- Successfully generated 6 repositories overnight in Y Combinator hackathon testing
+- One $50k contract completed for $297 in API costs
+- Created entire programming language ("cursed") over 3 months using this approach
+
+## Learn More
+
+- Original technique: https://ghuntley.com/ralph/
+- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
+
+## For Help
+
+Run `/help` in Claude Code for detailed command reference and examples.

plugins/ralph-loop/commands/cancel-ralph.md

@@ -0,0 +1,13 @@
+---
+description: "Cancel active Ralph Loop"
+allowed-tools: ["Bash(test -f .claude/ralph-loop.local.md:*)", "Bash(rm .claude/ralph-loop.local.md)", "Read(.claude/ralph-loop.local.md)"]
+hide-from-slash-command-tool: "true"
+---
+# Cancel Ralph
+To cancel the Ralph loop:
+1. Check if `.claude/ralph-loop.local.md` exists using Bash: `test -f .claude/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+2. **If NOT_FOUND**: Say "No active Ralph loop found."
+3. **If EXISTS**:
+- Read `.claude/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
+- Remove the file using Bash: `rm .claude/ralph-loop.local.md`
+- Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

plugins/ralph-loop/commands/help.md

@@ -0,0 +1,90 @@
+---
+description: "Explain Ralph Loop plugin and available commands"
+---
+# Ralph Loop Plugin Help
+Please explain the following to the user:
+## What is Ralph Loop?
+Ralph Loop implements the Ralph Wiggum technique - an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.
+**Core concept:**
+```bash
+while :; do
+cat PROMPT.md | claude-code --continue
+done
+```
+The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in the files and git history, not from feeding output back as input.
+**Each iteration:**
+1. Claude receives the SAME prompt
+2. Works on the task, modifying files
+3. Tries to exit
+4. Stop hook intercepts and feeds the same prompt again
+5. Claude sees its previous work in the files
+6. Iteratively improves until completion
+The technique is described as "deterministically bad in an undeterministic world" - failures are predictable, enabling systematic improvement through prompt tuning.
+## Available Commands
+### /ralph-loop <PROMPT> [OPTIONS]
+Start a Ralph loop in your current session.
+**Usage:**
+```
+/ralph-loop "Refactor the cache layer" --max-iterations 20
+/ralph-loop "Add tests" --completion-promise "TESTS COMPLETE"
+```
+**Options:**
+- `--max-iterations <N>` - Max iterations before auto-stop
+- `--completion-promise <TEXT>` - Promise phrase to signal completion
+**How it works:**
+1. Creates `.claude/.ralph-loop.local.md` state file
+2. You work on the task
+3. When you try to exit, stop hook intercepts
+4. Same prompt fed back
+5. You see your previous work
+6. Continues until promise detected or max iterations
+---
+### /cancel-ralph
+Cancel an active Ralph loop (removes the loop state file).
+**Usage:**
+```
+/cancel-ralph
+```
+**How it works:**
+- Checks for active loop state file
+- Removes `.claude/.ralph-loop.local.md`
+- Reports cancellation with iteration count
+---
+## Key Concepts
+### Completion Promises
+To signal completion, Claude must output a `<promise>TAG</promise>` tag:
+```
+<promise>TASK COMPLETE</promise>
+```
+The stop hook looks for this specific tag. Without it (or `--max-iterations`), Ralph runs infinitely.
+### Self-Reference Mechanism
+The "loop" doesn't mean Claude talks to itself. It means:
+- Same prompt repeated
+- Claude's work persists in files
+- Each iteration sees previous attempts
+- Builds incrementally toward goal
+## Example
+### Interactive Bug Fix
+```
+/ralph-loop "Fix the token refresh logic in auth.ts. Output FIXED when all tests pass." --completion-promise "FIXED" --max-iterations 10
+```
+You'll see Ralph:
+- Attempt fixes
+- Run tests
+- See failures
+- Iterate on solution
+- In your current session
+## When to Use Ralph
+**Good for:**
+- Well-defined tasks with clear success criteria
+- Tasks requiring iteration and refinement
+- Iterative development with self-correction
+- Greenfield projects
+**Not good for:**
+- Tasks requiring human judgment or design decisions
+- One-shot operations
+- Tasks with unclear success criteria
+- Debugging production issues (use targeted debugging instead)
+## Learn More
+- Original technique: https://ghuntley.com/ralph/
+- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator