diff --git a/examples/fleet-todo-app/INBOX.md b/examples/fleet-todo-app/INBOX.md new file mode 100644 index 00000000..84b3ec6c --- /dev/null +++ b/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 diff --git a/examples/fleet-todo-app/README.md b/examples/fleet-todo-app/README.md new file mode 100644 index 00000000..06bf5a72 --- /dev/null +++ b/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/.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. diff --git a/examples/fleet-todo-app/TODO.md b/examples/fleet-todo-app/TODO.md new file mode 100644 index 00000000..c308dbe5 --- /dev/null +++ b/examples/fleet-todo-app/TODO.md @@ -0,0 +1,9 @@ +# Board + +## Ready + +## In Progress + +## Done + +## Accepted diff --git a/examples/fleet-todo-app/fleet.yml b/examples/fleet-todo-app/fleet.yml new file mode 100644 index 00000000..bcacdcf5 --- /dev/null +++ b/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 diff --git a/examples/fleet-todo-app/ralphs/dev.md b/examples/fleet-todo-app/ralphs/dev.md new file mode 100644 index 00000000..9f2a170d --- /dev/null +++ b/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/.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. diff --git a/examples/fleet-todo-app/ralphs/pm.md b/examples/fleet-todo-app/ralphs/pm.md new file mode 100644 index 00000000..fa8616e2 --- /dev/null +++ b/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/.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/.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. diff --git a/examples/fleet-todo-app/ralphs/qa.md b/examples/fleet-todo-app/ralphs/qa.md new file mode 100644 index 00000000..077ddcd6 --- /dev/null +++ b/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/.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. diff --git a/examples/fleet-todo-app/specs/.gitkeep b/examples/fleet-todo-app/specs/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/pm/INBOX.md b/pm/INBOX.md new file mode 100644 index 00000000..aa0063bf --- /dev/null +++ b/pm/INBOX.md @@ -0,0 +1,8 @@ +# Inbox + + + +- [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 diff --git a/pm/TODO.md b/pm/TODO.md new file mode 100644 index 00000000..b0082faf --- /dev/null +++ b/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 diff --git a/pm/tasks/fleet-lifecycle-example/PLAN.md b/pm/tasks/fleet-lifecycle-example/PLAN.md new file mode 100644 index 00000000..efa4fb95 --- /dev/null +++ b/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