Add Ralph Wiggum Loop and beads infrastructure

.gitignore

@@ -46,3 +46,8 @@ pnpm-debug.log*
 # Beads issue tracker cache (JSONL files should be tracked)
 .beads/*.db
 .beads/*.db-*
+
+# Ralph Wiggum loop runtime state (sessions, logs, metrics)
+.ralph/sessions/
+.ralph/latest
+.ralph/history.jsonl

AGENTS.md

@@ -60,3 +60,25 @@ Before ending a session with code changes:
 1. Run `bun run build` to verify types
 2. Run `bun test:e2e` if UI was modified
 3. Commit with descriptive message including issue ID
+## Issue Tracking
+
+This project uses **bd (beads)** for issue tracking.
+Run `bd prime` for workflow context, or install hooks (`bd hooks install`) for auto-injection.
+
+**Quick reference:**
+- `bd ready` - Find unblocked work
+- `bd create "Title" --type task --priority 2` - Create issue
+- `bd close <id>` - Complete work
+- `bd sync` - Sync with jj (run at session end)
+
+For full workflow details: `bd prime`
+
+Always commit changes to .beads folder with other changes.
+
+
+
+## Related Tools
+
+- **Beads**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads) - AI-native issue tracking
+
+

PROMPT_build.md

@@ -0,0 +1,32 @@
+0a. Run `bd ready --json --limit 1 --type task` to find the highest priority unblocked task.
+    If no tasks are found, try `bd ready --json --limit 1 --type bug` for bugs.
+    Never pick an epic directly — epics contain child tasks to work on instead.
+0b. Run `bd show <task-id>` to read the full specification.
+0c. For reference, the application source code is in `src/*`.
+
+1. Your task is to implement the ready bead. Before making changes:
+   - Search the codebase (don't assume not implemented)
+   - Run `bd show <id>` to get full acceptance criteria
+   - Update status: `bd update <id> --status in_progress`
+
+2. Implement the functionality per the bead's description and acceptance criteria.
+   Use up to 500 parallel subagents for searches/reads, 1 subagent for build/tests.
+   Use Opus subagents for complex reasoning (debugging, architectural decisions).
+
+3. After implementing, run the tests for that unit of code.
+   If functionality is missing, add it per the specification. Ultrathink.
+
+4. When you discover issues during implementation:
+   - Create a new bead: `bd create "discovered issue" -t bug -p <priority>`
+   - Link it: `bd dep add <new-id> <current-id> --type discovered-from`
+
+5. When tests pass:
+   - Close the bead: `bd close <id> --reason "Implemented with tests"`
+   - Describe: `jj describe -m "feat: <description>"`
+   - Push: `jj git push`
+   - Sync beads: `bd sync`
+
+99999. When you learn something about how to run the application, update @AGENTS.md.
+999999. For any bugs noticed, create beads even if unrelated to current work.
+9999999. Implement completely. Placeholders waste time redoing work.
+99999999. Use `bd ready` at start of each loop to pick the most important unblocked task.

PROMPT_plan.md

@@ -0,0 +1,27 @@
+0a. Run `bd list --json` to understand all issues in the project.
+0b. Run `bd ready --json` to see what work has no blockers.
+0c. Run `bd dep tree <epic-id>` for each epic to understand the dependency graph.
+0d. Study `src/lib/*` with subagents to understand shared utilities & components.
+
+1. Analyze the beads database for gaps and issues:
+   - Run `bd list --status open --json` to get all open issues
+   - For each epic, verify child tasks cover all aspects of the specification
+   - Check for missing dependencies using `bd dep cycles` (should be empty)
+   - Identify any tasks that should block others but don't
+
+2. Update the beads database to fix any issues found:
+   - Create missing tasks with `bd create "title" -t task -p <priority> -d "description"`
+   - Add missing dependencies with `bd dep add <child> <parent> --type blocks`
+   - Update priorities if needed with `bd update <id> --priority <0-4>`
+   - Add labels for better organization with `bd label add <id> <labels>`
+
+3. Verify the plan is complete:
+   - `bd ready` should show the correct next task(s)
+   - `bd blocked` should show tasks waiting on dependencies
+   - `bd stats` should show accurate counts
+
+IMPORTANT: Plan only. Do NOT implement anything. Do NOT assume functionality is missing; 
+use `bd list` and code search to verify first.
+
+ULTIMATE GOAL: We want to achieve [project-specific goal]. Ensure all necessary tasks 
+exist as beads with proper dependencies so `bd ready` always shows the right next work.

PROMPT_review.md

@@ -0,0 +1,33 @@
+You are a code reviewer. Your job is to review the most recent changes and decide
+whether the work is ready to ship or needs revision.
+
+## Instructions
+
+1. Run `jj log -r 'ancestors(@, 5)'` and `jj diff -r @-` to see the latest changes.
+2. Run `bd list --status in_progress --json` to see what task was being worked on.
+3. Run `bd show <id>` for each in-progress task to understand the acceptance criteria.
+4. Evaluate the changes against the acceptance criteria:
+   - Does the implementation match the specification?
+   - Are there obvious bugs, missing error handling, or logic errors?
+   - Are tests included and do they pass? Run the relevant test command.
+   - Is the code clean and following project conventions?
+
+## Output Format
+
+You MUST end your response with exactly one of these two lines:
+
+```
+RESULT: SHIP
+```
+
+or
+
+```
+RESULT: REVISE
+```
+
+If REVISE, provide specific, actionable feedback above the RESULT line explaining
+exactly what needs to change. Be concrete - reference specific files, functions, and
+line numbers. Do not be vague.
+
+If SHIP, briefly confirm what was verified above the RESULT line.

README.md

@@ -44,3 +44,62 @@ docker build -t europe-west1-docker.pkg.dev/developers-fashionunited-com/develop
 ## License
 
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Ffuww%2Fdeveloper.fashionunited.com.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Ffuww%2Fdeveloper.fashionunited.com?ref=badge_large)
+## Ralph Wiggum Loop
+
+```bash
+while :; do cat prompt.md | claude --dangerously-skip-permissions;done
+```
+
+This project includes `loop.sh`, an implementation of the [Ralph Wiggum technique](https://ghuntley.com/ralph/) by [Geoffrey Huntley](https://github.com/ghuntley/how-to-ralph-wiggum) — a bash loop that runs Claude Code autonomously against a prompt file until all work is done.
+
+### How it works
+
+The loop picks up ready tasks from [beads](https://github.com/steveyegge/beads) issue tracking, feeds them to Claude via a prompt file (`PROMPT_build.md` or `PROMPT_plan.md`), and optionally runs a review phase after each iteration. Session state, logs, and metrics are stored in `.ralph/` (gitignored).
+
+### Quick start
+
+```sh
+# Build mode (unlimited iterations, picks up ready beads tasks)
+./loop.sh
+
+# Plan mode (3 iterations by default)
+./loop.sh plan
+
+# Build with max 10 iterations, interactive confirmation
+./loop.sh run build -n 10 -i
+
+# Disable review phase
+./loop.sh --no-review
+
+# See all options
+./loop.sh --help
+```
+
+### Codex login (for reviews)
+
+On remote machines you need device auth to do headless login. First enable this in your ChatGPT / Codex account.
+
+```
+codex login --device-auth
+```
+
+### Configuration
+
+Create `.ralph/config.toml` to override defaults (default model is `opus`):
+
+```toml
+max_iterations = 10
+model = "opus"
+delay = 5
+push_enabled = false
+review_enabled = true
+review_model = "gpt-5.2-codex"
+review_max_revisions = 3
+```
+
+### Further reading
+
+- [The Ralph Wiggum Technique](https://ghuntley.com/ralph/) — Geoffrey Huntley's original post
+- [how-to-ralph-wiggum](https://github.com/ghuntley/how-to-ralph-wiggum) — Reference implementation and methodology guide
+- [Inventing the Ralph Wiggum Loop](https://devinterrupted.substack.com/p/inventing-the-ralph-wiggum-loop-creator) — Dev Interrupted podcast interview
+

flake.nix

@@ -30,7 +30,16 @@
           packages = with pkgs; [
               bun
               nixpkgs-fmt
+              go
           ];
+
+          shellHook = ''
+            if ! command -v bd &> /dev/null; then
+              echo "Installing beads (bd) for AI agent task tracking..."
+              go install github.com/steveyegge/beads/cmd/bd@latest
+            fi
+            echo "  Beads:       $(bd --version 2>/dev/null || echo 'run: go install github.com/steveyegge/beads/cmd/bd@latest')"
+          '';
         };
       });
     };