Waterfall runs eight specialized agents through a fixed V-cycle: requirements, specs, design, implementation, review, validation, closure. Each phase produces a written file you review before the next one starts.
› /plugin install waterfall@waterfall
One vague prompt, one missed assumption, one improvised refactor — and the agent ships code that compiles, looks plausible, and is wrong from end to end. Reviewing it afterward is harder than writing it yourself.
Each phase builds on the previous one's mistakes. By the time you review the PR, the original intent is lost.
Past a threshold, the model loses track but keeps writing. Waterfall keeps phases small and scoped, so every file is produced in fresh context.
The process produces files you sign off on at every checkpoint.
One giant prompt is a single point of failure. A team of specialized agents produces traceable files, each with a named owner.
Drives the state machine: locks scope, sequences phases, and calls the next agent. Never writes product content.
Interviews HO and writes PRD.md. Owns the Requirements phase, and also drives Closure (retro, PR).
Reads the PRD.md written by PM, then writes the functional specs and acceptance criteria. Starts at the Functional specs phase.
Owns the technical design: picks the architecture, documents trade-offs, and decides hosting and stack.
An independent gate at every phase boundary. Reads, challenges, and blocks — but never writes the file it reviews.
Writes the code, and only the code, against frozen specs. Never reopens a closed phase.
Replays the acceptance criteria against the build, across browsers and flows. Reports failures with evidence.
Visual and interaction design, when the deliverable has a UI. Works with PO on flows and TL on feasibility.
You — the only non-agent role. You set the scope, sign every gate, and are accountable for what ships. Waterfall is built around your sign-off, not around removing it.
Read left to right. Every arrow is a written file. HO checkpoints sit below — each one gates the transition above it.
Verification on the way down (what we're going to do, written). Validation on the way up (what we did, tested against what we wrote). Coding sits at the bottom — last, not first.
Every acronym you'll see across the cycle. Each one is a file the next agent reads.
| Code | Artefact | What it is | Owner |
|---|---|---|---|
| EX | Experience expectation | A user-facing expectation in specs.md, prioritized MUST / SHOULD / MAY. Every downstream file traces back to one. |
PO |
| INV | Invariant | A rule the system must always preserve, in specs.md. Cross-cutting — it doesn't belong to any single EX. |
PO |
| TF | Functional test | A testable GIVEN / WHEN / THEN scenario in acceptance.md. QA replays it at validation. |
PO |
| T | Task | A sized unit of work in tasks.md, traced to one or more EX. The DV works through these. |
TL |
| B | Blocker | A review finding in review.md serious enough to block sign-off. Must be resolved before the artefact is approved. |
RV |
| Q | Question | A clarification raised during review in review.md, routed to PM, PO, or TL. It doesn't block, but it must be answered. |
RV |
| ADR | Architecture decision | An architectural decision recorded in design.md with context, options considered, and rationale. |
TL |
| DEC | Decision | A non-architectural decision logged in tracking.md or retro.md — scope, trade-off, process choice. |
any |
| OBS | Observation | An observation about the workflow itself, logged in tracking.md or or.log while it runs. Collected into retro.md at closure. |
any |
/waterfall.
Waterfall ships as a Claude Code plugin. No build step on your side.
Register the marketplace, then install the plugin. No clone needed.
› /plugin marketplace add mgallet92i/waterfall
› /plugin install waterfall@waterfallCopy .wf-config.example.json to .wf-config.json and set models per role, review-loop budgets, the watchdog interval, and Dark Factory. Defaults apply if the file is missing. The schema is documented in .wf-config.example.md.
$ cp .wf-config.example.json .wf-config.json
# edit models, review_loops, dark_factory…OR walks you through Bootstrap → Requirements. Each gate asks you for approval.
› /waterfall:new add-google-workspace-sso
# OR creates ticket WF-014, hands off to PM…Some changes are too small to deserve a V-cycle. Some are too big to ship without one.
vs. one-shot prompting. You write the specs before the code — that's the point.
Multiple agents read each file. Context is fresh each phase, not accumulated across one long session.
If your change is a typo or a one-line fix, skip Waterfall. Use it where review matters.
The default agent_mode: subagent (Agent tool, no inter-agent messaging) runs slightly cheaper than team mode and is more predictable: PM stays in charge of every spawn, with no idle teammates to nudge. Use team only if agents need to talk to each other directly.
Five reasons teams adopt Waterfall — each a deliberate choice, not just a feature.
A 10-phase state machine. Phases are named and ordered, and every transition produces a written file. Each cycle is exactly as long as the work needs.
OR sequences the work. PM, PO, TL, and DS work in parallel where they can. RV stays independent. DV doesn't start until specs are frozen, so it never has to redo work.
Every line of code maps back through the technical design, the functional specs, and an EX. Reviewing a diff means re-reading three files, not guessing the intent.
Maximum autonomy: agents run end to end. HO only reviews at named checkpoints — typically Review (after design) and Closure (after validation). For teams that trust the output and want speed.
HO must review artefacts and code. That sentence is in the plugin's default config, on every gate, and on this page on purpose. Waterfall is not built to take humans out of the loop. It's built so the humans in the loop read the right thing at the right time.