feat: add fleet-todo-app lifecycle example

examples/fleet-todo-app/INBOX.md

@@ -0,0 +1,9 @@
+# Inbox
+
+Feature requests and ideas for the todo app.
+
+- [ ] Add a REST API endpoint to create a new todo item (POST /todos with title and optional description)
+- [ ] Add a REST API endpoint to list all todo items (GET /todos with optional ?status=done filter)
+- [ ] Add a REST API endpoint to mark a todo item as done (PATCH /todos/:id)
+- [ ] Add a REST API endpoint to delete a todo item (DELETE /todos/:id)
+- [ ] Add input validation — title must be non-empty and under 200 characters

examples/fleet-todo-app/README.md

@@ -0,0 +1,79 @@
+# Fleet Todo App
+
+A multi-ralph example that simulates a software team building a todo app. Three ralphs — PM, developer, and QA — work together using a shared kanban board and spec files to move features from idea to accepted.
+
+## How it works
+
+The fleet follows a pipeline:
+
+1. **PM** reads the inbox, writes specs, and adds tasks to the board
+2. **Dev** picks up ready tasks, implements them, and marks them done
+3. **QA** verifies done tasks against specs and either accepts or rejects them
+
+All coordination happens through files:
+
+- `INBOX.md` — raw feature requests
+- `TODO.md` — kanban board with Ready / In Progress / Done / Accepted columns
+- `specs/<slug>.md` — detailed specs with acceptance criteria
+
+Each ralph reads the current state of these files via `commands` in its frontmatter, makes a decision, and updates the files. No direct communication between ralphs — just shared state on disk.
+
+## Directory structure
+
+```
+fleet-todo-app/
+├── fleet.yml            # Fleet configuration (roles, dependencies, settings)
+├── INBOX.md             # Seed feature requests
+├── TODO.md              # Kanban board
+├── specs/               # Specs written by PM, read by dev and QA
+└── ralphs/
+    ├── pm.md            # PM ralph — triages inbox, writes specs, reviews work
+    ├── dev.md           # Dev ralph — implements tasks, writes tests
+    └── qa.md            # QA ralph — verifies work against specs
+```
+
+## Running the ralphs
+
+Fleet orchestration (`ralph fleet`) is not yet implemented. For now, run each ralph individually in separate terminals:
+
+```bash
+cd examples/fleet-todo-app
+
+# Terminal 1 — start the PM
+ralph run ralphs/pm.md
+
+# Terminal 2 — start the developer (after PM has created some specs)
+ralph run ralphs/dev.md
+
+# Terminal 3 — start QA (after dev has completed some work)
+ralph run ralphs/qa.md
+```
+
+When fleet support lands, you'll be able to run the whole team with:
+
+```bash
+ralph fleet fleet.yml
+```
+
+The `fleet.yml` defines the dependency order (`dev` depends on `pm`, `qa` depends on `dev`), concurrency limits, and stagger timing so ralphs don't step on each other.
+
+## The workflow
+
+Starting from the seed inbox, a typical run looks like:
+
+1. PM reads `INBOX.md`, picks "Add POST /todos endpoint", writes `specs/create-todo.md`, adds it to `## Ready` on the board
+2. Dev sees the ready task, reads the spec, implements it, writes tests, moves it to `## Done`
+3. QA picks up the done task, runs tests, checks acceptance criteria, moves it to `## Accepted`
+4. PM sees nothing in inbox or done — goes idle. Dev picks the next ready task. The cycle continues.
+
+Each ralph processes one task per iteration and goes idle when there's nothing to do. The loop harness restarts them with fresh state each time.
+
+## Customizing
+
+This example uses `claude` as the agent, but you can swap in any agent that accepts piped input. Edit the `agent` field in each ralph's frontmatter:
+
+```yaml
+agent: aider --yes-always
+```
+
+The board format and file conventions are just that — conventions. Adapt them to match your team's workflow.

examples/fleet-todo-app/TODO.md

@@ -0,0 +1,9 @@
+# Board
+
+## Ready
+
+## In Progress
+
+## Done
+
+## Accepted

examples/fleet-todo-app/fleet.yml

@@ -0,0 +1,35 @@
+# fleet.yml — Fleet of ralphs for a todo app project
+#
+# Three roles working together:
+#   PM     — breaks down features, writes specs, reviews completed work
+#   Dev    — implements tasks, writes tests, creates PRs
+#   QA     — runs tests, verifies acceptance criteria, approves or rejects
+
+fleet:
+  name: todo-app
+  worktree_dir: .trees
+  state_dir: .ralph/state
+
+ralphs:
+  pm:
+    file: ralphs/pm.md
+    branch: ralph/pm
+    worktree: true
+    priority: 1
+
+  dev:
+    file: ralphs/dev.md
+    branch: ralph/dev
+    worktree: true
+    depends_on: [pm]
+
+  qa:
+    file: ralphs/qa.md
+    branch: ralph/qa
+    worktree: true
+    depends_on: [dev]
+
+settings:
+  max_concurrent: 2
+  stagger_start: 30s
+  merge_strategy: fifo

examples/fleet-todo-app/ralphs/dev.md

@@ -0,0 +1,44 @@
+---
+agent: claude -p --dangerously-skip-permissions
+commands:
+  - name: todo
+    run: cat TODO.md
+  - name: tests
+    run: npm test 2>&1 || true
+  - name: recent-commits
+    run: git log --oneline -10
+---
+
+# Role
+
+You are a developer on a todo app project. You pick up tasks from the board, implement them, write tests, and mark them done.
+
+# State
+
+## Board
+
+{{ commands.todo }}
+
+## Test results
+
+{{ commands.tests }}
+
+## Recent commits
+
+{{ commands.recent-commits }}
+
+# Decision tree
+
+1. **Tests failing?** Fix them immediately before picking up new work.
+
+2. **Items in `## Ready`?** Pick the top item. Read its spec in `specs/<slug>.md`. Move the item to `## In Progress` in `TODO.md`. Implement the feature, write tests, and commit. Then move the item to `## Done`.
+
+3. **Nothing in `## Ready`?** Output `IDLE` and stop.
+
+# Rules
+
+- One task per iteration.
+- Always run tests before committing. Never commit with failing tests.
+- Follow the spec's acceptance criteria exactly.
+- Commit messages: `feat:`, `fix:`, `test:` prefixes.
+- Keep code simple — no over-engineering.

examples/fleet-todo-app/ralphs/pm.md

@@ -0,0 +1,43 @@
+---
+agent: claude -p --dangerously-skip-permissions
+commands:
+  - name: inbox
+    run: cat INBOX.md
+  - name: todo
+    run: cat TODO.md
+  - name: recent-commits
+    run: git log --oneline -20
+---
+
+# Role
+
+You are a project manager for a todo app. You break down features into implementable tasks, write clear specs, and keep the board moving.
+
+# State
+
+## Inbox
+
+{{ commands.inbox }}
+
+## Board
+
+{{ commands.todo }}
+
+## Recent commits
+
+{{ commands.recent-commits }}
+
+# Decision tree
+
+1. **Inbox has unclaimed items?** Pick the top unchecked item. Write a clear spec in `specs/<slug>.md` with acceptance criteria, then add it to `TODO.md` under `## Ready`. Check off the inbox item.
+
+2. **Items in `## Done` need review?** Read the spec and the code changes. If acceptance criteria are met, move the item to `## Accepted`. If not, add comments to the spec and move it back to `## Ready`.
+
+3. **Nothing to do?** Output `IDLE` and stop.
+
+# Rules
+
+- One task per iteration.
+- Specs go in `specs/<slug>.md` with: summary, files to touch, and acceptance criteria.
+- Keep `TODO.md` sections in order: `## Ready`, `## In Progress`, `## Done`, `## Accepted`.
+- Never write application code yourself — only specs and board updates.

examples/fleet-todo-app/ralphs/qa.md

@@ -0,0 +1,45 @@
+---
+agent: claude -p --dangerously-skip-permissions
+commands:
+  - name: todo
+    run: cat TODO.md
+  - name: tests
+    run: npm test 2>&1 || true
+  - name: lint
+    run: npm run lint 2>&1 || true
+---
+
+# Role
+
+You are a QA engineer on a todo app project. You verify completed work against specs, run tests, and either approve or reject.
+
+# State
+
+## Board
+
+{{ commands.todo }}
+
+## Test results
+
+{{ commands.tests }}
+
+## Lint results
+
+{{ commands.lint }}
+
+# Decision tree
+
+1. **Items in `## Done`?** Pick the top item. Read its spec in `specs/<slug>.md`. Verify:
+   - All acceptance criteria are met
+   - Tests pass and cover the new functionality
+   - No lint errors introduced
+   If everything passes, move the item to `## Accepted` in `TODO.md`. If not, add a `## QA Notes` section to the spec explaining what failed, and move the item back to `## Ready`.
+
+2. **Nothing in `## Done`?** Output `IDLE` and stop.
+
+# Rules
+
+- One task per iteration.
+- Never fix code yourself — send it back to `## Ready` with clear notes.
+- Be specific about what failed and why.
+- Check both functionality and code quality.

pm/INBOX.md

@@ -0,0 +1,8 @@
+# Inbox
+
+<!-- Add work items here. Use checkboxes. The agent picks the top unchecked item. -->
+<!-- Formats: plain text descriptions, GitHub issue URLs, or ideas -->
+- [x] https://github.com/computerlovetech/ralphify/issues/1 (see fleet-of-ralphs.md) POC Disclaimer in draft PR
+- [x] Make a test for a full software lifecycle (multiple devs + qa + tester and kanban and an INBOX.md example for a todo app) use websearch to find good examples, make a subdir with no code just the things ready to test our fleet
+- [ ] Make sure we handle worktrees in a good way use websearch to check how https://github.com/juliusmarminge does it
+- [ ] The dashboard doesn't work

pm/TODO.md

@@ -0,0 +1,20 @@
+# Tasks
+
+## Active
+
+## Done
+- [x] fleet-lifecycle-example — Sample fleet scenario for testing multi-ralph orchestration → PR #34
+- [x] dashboard-poc — Visual dashboard for ralphify (#15) → PR #33
+- [x] fleet-parallel-ralphs — Add `ralph fleet` command to run multiple ralphs in parallel (#1) → PR #32
+- [x] merge-countdown-to-idle — Move countdown timer from PR #31 into PR #29 (idle-detection), fix live ticking → PR #29
+- [x] reliable-idle-detection — Check full agent stdout for idle marker as fallback → PR #29
+- [x] fix-idle-detection — Fix pm/RALPH.md typo and idle marker instruction so idle mode works
+- [x] minimize-pr29-v3 — Reduce PR #29 diff by 76 lines (inlined constants, consolidated tests, trimmed docs)
+- [x] delay-countdown — Replace static "Waiting" message with live countdown timer → PR #31
+- [x] minimize-pr29-further — Further reduce PR #29 diff (~150 lines of dead code, redundancy, verbosity) → PR #29
+- [x] minimize-pr29 — Reduce PR #29 test redundancy to shrink diff → PR #29
+- [x] setup-pm-idle-config — Add idle detection config to setup-pm.md prompt → PR #30
+- [x] idle-detection — State-aware idle detection with backoff and max idle duration (#28) → PR #29
+- [x] minimize-pr27-tests — Further reduce test diff in PR#27 test_agent.py
+- [x] ghost-agent-cleanup — Fix ghost agent processes surviving Ctrl+C (#26) → PR #27
+- [x] minimize-pr27-diff — Reduce PR #27 diff size by consolidating tests

pm/tasks/fleet-lifecycle-example/PLAN.md

@@ -0,0 +1,34 @@
+# fleet-lifecycle-example — Sample fleet scenario for testing multi-ralph orchestration
+
+## Summary
+
+Create a self-contained example directory (`examples/fleet-todo-app/`) that demonstrates a full software lifecycle using a fleet of ralphs. The scenario simulates a todo app project with multiple roles (PM, developer, QA/tester) coordinated through kanban-style file conventions. No application code — just the ralph definitions, project scaffolding, and an INBOX.md ready to drive the fleet.
+
+This is research-driven: use web search to find good examples of multi-agent software lifecycles and kanban workflows to inform the design.
+
+## Files to create
+
+- `examples/fleet-todo-app/README.md` — Overview of the example and how to run it
+- `examples/fleet-todo-app/ralphs/pm.md` — PM ralph definition
+- `examples/fleet-todo-app/ralphs/dev.md` — Developer ralph definition
+- `examples/fleet-todo-app/ralphs/qa.md` — QA/tester ralph definition
+- `examples/fleet-todo-app/INBOX.md` — Seed inbox with todo app tasks
+- `examples/fleet-todo-app/TODO.md` — Initial kanban board
+- `examples/fleet-todo-app/fleet.yml` — Fleet configuration
+
+## Steps
+
+- [x] 1. Research multi-agent software lifecycle examples and kanban workflows via web search to inform the design
+- [x] 2. Create the example directory structure and fleet.yml configuration
+- [x] 3. Write the PM, developer, and QA ralph definitions with realistic prompts and commands
+- [x] 4. Create the seed INBOX.md and TODO.md with todo app feature tasks
+- [x] 5. Write the README.md explaining the example and how to use it
+- [x] 6. Commit and create draft PR
+
+## Acceptance criteria
+
+- Example directory is self-contained and well-documented
+- Ralph definitions use realistic commands and prompts
+- Kanban workflow is clearly demonstrated (INBOX → TODO → In Progress → Done)
+- No application code — just the orchestration scaffolding
+- README explains the fleet concept and how to run the example