waterfall

Waterfall — Claude Code plugin

Multi-agent Spec-Driven Development (SDD) framework for Claude Code. Waterfall orchestrates a team of specialized agents (OR, PM, PO, TL, RV, DV, QA, DS) through a strict waterfall workflow — from product brief to validated implementation — with explicit handoffs, persistent state, and identity enforcement.

🌐 Homepage: https://mgallet92i.github.io/waterfall/

Full documentation (best practices, agent roles, state machine, troubleshooting) will live on a dedicated documentation site. This README covers what you need to install and run the plugin.

---

Overview

Waterfall turns a single Claude Code session into a coordinated team of agents, each with a narrow role:

• HO — human operator, the user driving the workflow. Interacts exclusively through PM (questions, checkpoints, validation, commit approval).
• PM — project manager, owns the PRD, team registry, and handoffs
• OR — orchestrator, drives the state machine
• PO — product owner, reads the PRD, owns the functional specs and acceptance criteria
• TL — tech lead, owns the technical design and task planning
• DV — developer, implements tasks
• RV — reviewer, checks code and design conformance
• QA — quality, validates against acceptance
• DS — design/UX

Each need (work item) lives under wf/needs/<kebab-name>/ with its own PRD, design, specs, tasks, tracking, and .wf-state.json. The state machine (scripts/wf-orchestrate.sh) is the single source of truth for what happens next; agents only advance via guarded --complete calls.

Built on Claude Code's experimental Agent Teams feature.

---

Installation

Marketplace listing coming soon. In the meantime, clone the repo and install it as a local marketplace.

1. Clone the repository locally to <path-to-repo> (e.g. C:\repo\waterfall on Windows, ~/repo/waterfall on macOS/Linux).
2. Register the clone as a local marketplace, then install the plugin:

/plugin marketplace add <path-to-repo>
/plugin install waterfall@waterfall-local

3. Verify the plugin is active:

/plugin

You should see waterfall listed and the /waterfall:new, /waterfall:resume, /waterfall:quit commands available.

The plugin ships:

• commands/ — slash commands (/waterfall:new, /waterfall:resume, /waterfall:quit)
• agents/ — the eight agent definitions (wf-pm, wf-or, …)
• skills/ — skill bundles invoked by the commands
• hooks/wf-auth.sh — PreToolUse(Bash) identity guard
• scripts/ — orchestrator, watchdog, statusline, registry, preflight checks
• wf/templates/ — need document templates, fr and en mirrors (PRD, design, specs, tasks, …)

Requirements

• Claude Code with Agent Teams enabled (see Configuration below)
• bash is mandatory. All scripts use bash-only features.
  • macOS / Linux: any standard bash shell works.
  • Windows: you must run Claude Code from Git Bash (Git for Windows). cmd.exe, PowerShell, and WSL bash are not supported. Download: https://git-scm.com/download/win
  • The bootstrap script scripts/wf-check-bash.sh enforces this on every /waterfall:new and /waterfall:resume and fails fast with a clear message otherwise.
• jq — used by every script that touches .wf-state.json / ack-registry.json. The bootstrap script scripts/wf-check-jq.sh will detect and offer to install it:
  • Windows: winget install jqlang.jq (fallback: choco, scoop)
  • macOS: brew install jq (fallback: port)
  • Linux: apt-get / dnf / yum / pacman / zypper / apk (auto-detected)

Optional tools

• Semgrep — static code analysis used by TL during code review. Disabled by default; enable by setting tools.semgrep: "on" in .wf-config.json. The helper scripts/lib/wf-semgrep.sh auto-detects the available runner:

  1. Native Semgrep CLI (semgrep on $PATH — install via pipx install semgrep or uv tool install semgrep)
  2. Fallback to Docker (semgrep/semgrep image, requires Docker Desktop running)

  If neither is available, TL skips Semgrep silently and the review proceeds unchanged. Findings are mapped to the existing blocker/nit scale (ERROR→P0, WARNING→P1, INFO→P2).

  The default ruleset is strict: p/owasp-top-ten + p/cwe-top-25 + p/default. Override via tools.semgrep_rules (array of Semgrep registry packs or local YAML paths). Dead code and duplication detection are out of scope for Semgrep — handled by SonarCloud integration (planned, RV-side).

---

Configuration

1. Enable Agent Teams (required)

Agent Teams is an experimental Claude Code feature. Enable it in ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}