pi-extensions 0.1.9

package/ralph-wiggum/README.md

@@ -0,0 +1,96 @@
+# Ralph Wiggum Extension
+
+Long-running agent loops for iterative development. Best for long-running-tasks that are verifiable. Builds on Geoffrey Huntley's ralph-loop for Claude Code and adapts it for Pi.
+This one is cool because:
+- You can ask Pi and it will set up and run the loop all by itself in-session. If you prefer, it can also invoke another Pi via tmux
+- You can have multiple parallel loops at once in the same repo (unlike OG ralph-wiggum)
+- You can ask Pi to self-reflect at regular intervals so it doesn't mindlessly grind through wrong instructions (optional)
+
+<img width="432" height="357" alt="Screenshot 2026-01-07 at 17 16 24" src="https://github.com/user-attachments/assets/68cdab11-76c6-4aed-9ea1-558cbb267ea6" />
+
+
+## Install
+
+```bash
+pi install npm:@tmustier/pi-ralph-wiggum
+```
+
+```bash
+pi install git:github.com/tmustier/pi-extensions
+```
+
+Then filter to just this extension in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": [
+    {
+      "source": "git:github.com/tmustier/pi-extensions",
+      "extensions": ["ralph-wiggum/index.ts"],
+      "skills": ["ralph-wiggum/SKILL.md"]
+    }
+  ]
+}
+```
+
+## Recommended usage: just ask Pi
+You ask Pi to set up a ralph-wiggum loop.
+- Pi sets up `.ralph/<name>.md` with goals and a checklist (like a list of features to build, errors to check, or files to refactor)
+- You let Pi know:
+  1. What the task is and completion / tests to run
+  2. How many items to process per iteration
+  3. How often to commit
+  4. (optionally) After how many items it should take a step back and self-reflect
+- Pi runs `ralph_start`, beginning iteration 1.
+  - It gets a prompt telling it to work on the task, update the task file, and call ralph_done when it finishes that iteration
+  - When the iteration is done, it calls `ralph_done`, resending the same prompt*
+- Pi runs until either:
+  - All tasks are done (Pi sends `<promise>COMPLETE</promise>`)
+  - Max iterations (default 50)
+  - You hit `esc` (pausing the loop)
+If you hit `esc`, you can run `/ralph-stop` to clear the loop. Alternatively, just tell Pi to continue to keep going.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ralph start <name\|path>` | Start a new loop |
+| `/ralph resume <name>` | Resume a paused loop |
+| `/ralph stop` | Pause current loop |
+| `/ralph-stop` | Stop active loop (idle only) |
+| `/ralph status` | Show all loops |
+| `/ralph list --archived` | Show archived loops |
+| `/ralph archive <name>` | Move loop to archive |
+| `/ralph clean [--all]` | Clean completed loops |
+| `/ralph cancel <name>` | Delete a loop |
+| `/ralph nuke [--yes]` | Delete all .ralph data |
+
+### Options for start
+
+| Option | Description |
+|--------|-------------|
+| `--max-iterations N` | Stop after N iterations (default 50) |
+| `--items-per-iteration N` | Suggest N items per turn (prompt hint) |
+| `--reflect-every N` | Reflect every N iterations |
+
+## Agent Tool
+
+The agent can self-start loops using `ralph_start`:
+
+```
+ralph_start({
+  name: "refactor-auth",
+  taskContent: "# Task\n\n## Checklist\n- [ ] Item 1",
+  maxIterations: 50,
+  itemsPerIteration: 3,
+  reflectEvery: 10
+})
+```
+
+## Credits
+
+Based on Geoffrey Huntley's Ralph Wiggum approach for long-running agent tasks.
+
+## Changelog
+
+See `CHANGELOG.md`.

package/ralph-wiggum/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: ralph-wiggum
+description: Long-running iterative development loops with pacing control and verifiable progress. Use when tasks require multiple iterations, many discrete steps, or periodic reflection with clear checkpoints; avoid for simple one-shot tasks or quick fixes.
+---
+
+# Ralph Wiggum - Long-Running Development Loops
+
+Use the `ralph_start` tool to begin a loop:
+
+```
+ralph_start({
+  name: "loop-name",
+  taskContent: "# Task\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n- [ ] Item 2",
+  maxIterations: 50,        // Default: 50
+  itemsPerIteration: 3,     // Optional: suggest N items per turn
+  reflectEvery: 10          // Optional: reflect every N iterations
+})
+```
+
+## Loop Behavior
+
+1. **Write the task file**: Create `.ralph/<name>.md` with the task content. The tool does NOT create this file—you must write it yourself using the Write tool.
+2. Work on the task and update the file each iteration.
+3. Record verification evidence (commands run, file paths, outputs) in the task file.
+4. Call `ralph_done` to proceed to the next iteration.
+5. Output `<promise>COMPLETE</promise>` when finished.
+6. Stop when complete or when max iterations is reached (default 50).
+
+## User Commands
+
+- `/ralph start <name|path>` - Start a new loop.
+- `/ralph resume <name>` - Resume loop.
+- `/ralph stop` - Pause loop (when agent idle).
+- `/ralph-stop` - Stop active loop (idle only).
+- `/ralph status` - Show loops.
+- `/ralph list --archived` - Show archived loops.
+- `/ralph archive <name>` - Move loop to archive.
+- `/ralph clean [--all]` - Clean completed loops.
+- `/ralph cancel <name>` - Delete loop.
+- `/ralph nuke [--yes]` - Delete all .ralph data.
+
+Press ESC to interrupt streaming, send a normal message to resume, and run `/ralph-stop` when idle to end the loop.
+
+## Task File Format
+
+```markdown
+# Task Title
+
+Brief description.
+
+## Goals
+- Goal 1
+- Goal 2
+
+## Checklist
+- [ ] Item 1
+- [ ] Item 2
+- [x] Completed item
+
+## Verification
+- Evidence, commands run, or file paths
+
+## Notes
+(Update with progress, decisions, blockers)
+```
+
+## Best Practices
+
+1. Write a clear checklist with discrete items.
+2. Update checklist and notes as you go.
+3. Capture verification evidence for completed items.
+4. Reflect when stuck to reassess approach.
+5. Output the completion marker only when truly done.