{
"markdown": "# Waterfall β Claude Code plugin\r\n\r\nMulti-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.\r\n\r\nπ **Homepage:** \r\n\r\n> 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.\r\n\r\n---\r\n\r\n## Overview\r\n\r\nWaterfall turns a single Claude Code session into a coordinated team of agents, each with a narrow role:\r\n\r\n- **HO** β human operator, the user driving the workflow. Interacts exclusively through PM (questions, checkpoints, validation, commit approval).\r\n- **PM** β project manager, owns the PRD, team registry, and handoffs\r\n- **OR** β orchestrator, drives the state machine\r\n- **PO** β product owner, reads the PRD, owns the functional specs and acceptance criteria\r\n- **TL** β tech lead, owns the technical design and task planning\r\n- **DV** β developer, implements tasks\r\n- **RV** β reviewer, checks code and design conformance\r\n- **QA** β quality, validates against acceptance\r\n- **DS** β design/UX\r\n\r\nEach *need* (work item) lives under `wf/needs//` 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.\r\n\r\nBuilt on Claude Code's experimental **[Agent Teams](https://code.claude.com/docs/en/agent-teams#enable-agent-teams)** feature.\r\n\r\n---\r\n\r\n## Installation\r\n\r\nFrom a Claude Code session, register the marketplace then install the plugin:\r\n\r\n```\r\n/plugin marketplace add mgallet92i/waterfall\r\n/plugin install waterfall@waterfall\r\n```\r\n\r\nVerify the plugin is active:\r\n\r\n```\r\n/plugin\r\n```\r\n\r\nYou should see `waterfall` listed and the `/waterfall:new`, `/waterfall:resume`, `/waterfall:quit` commands available.\r\n\r\nThe plugin ships:\r\n\r\n- `commands/` β slash commands (`/waterfall:new`, `/waterfall:resume`, `/waterfall:quit`)\r\n- `agents/` β the eight agent definitions (`wf-pm`, `wf-or`, β¦)\r\n- `skills/` β skill bundles invoked by the commands\r\n- `hooks/wf-auth.sh` β `PreToolUse(Bash)` identity guard\r\n- `scripts/` β orchestrator, watchdog, statusline, registry, preflight checks\r\n- `wf/templates/` β need document templates, `fr` and `en` mirrors (PRD, design, specs, tasks, β¦)\r\n\r\n### Requirements\r\n\r\n- **Claude Code** with Agent Teams enabled (see *Configuration* below)\r\n- **bash is mandatory.** All scripts use bash-only features.\r\n - **macOS / Linux**: any standard bash shell works.\r\n - **Windows**: you **must** run Claude Code from **Git Bash** (Git for Windows). cmd.exe, PowerShell, and WSL bash are not supported. Download: \r\n - 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.\r\n- **[jq](https://jqlang.org/)** β used by every script that touches `.wf-state.json` / `.team-registry.json`. The bootstrap script `scripts/wf-check-jq.sh` will detect and offer to install it:\r\n - Windows: `winget install jqlang.jq` (fallback: `choco`, `scoop`)\r\n - macOS: `brew install jq` (fallback: `port`)\r\n - Linux: `apt-get` / `dnf` / `yum` / `pacman` / `zypper` / `apk` (auto-detected)\r\n\r\n### Optional tools\r\n\r\n- **[Semgrep](https://semgrep.dev/docs/for-developers/cli)** β 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:\r\n 1. Native Semgrep CLI (`semgrep` on `$PATH` β install via `pipx install semgrep` or `uv tool install semgrep`)\r\n 2. Fallback to Docker (`semgrep/semgrep` image, requires Docker Desktop running)\r\n\r\n 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).\r\n\r\n 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).\r\n\r\n---\r\n\r\n## Configuration\r\n\r\n### 1. Enable Agent Teams (required)\r\n\r\n[Agent Teams](https://code.claude.com/docs/en/agent-teams#enable-agent-teams) is an experimental Claude Code feature. Enable it in `~/.claude/settings.json`:\r\n\r\n```json\r\n{\r\n \"env\": {\r\n \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\"\r\n }\r\n}\r\n```\r\n\r\nRestart Claude Code. The preflight `scripts/wf-check-teams.sh` runs at plugin bootstrap and will fail loudly if the flag is missing.\r\n\r\n### 2. Identity enforcement (automatic)\r\n\r\n`hooks/wf-auth.sh` is registered as a `PreToolUse(Bash)` hook. It guards every `wf-orchestrate.sh --complete :` call: the harness-injected `agent_type` must match the role the state machine expects for the current step (resolved from the stepβagent tables). Self-declared identities are rejected β there is no `--agent` flag. The `.team-registry.json` file is traceability only and is never consulted for authorization (DEC-001).\r\n\r\nNo setup needed; the hook is wired by the plugin manifest.\r\n\r\n### 3. Statusline (optional)\r\n\r\nA compact statusline reports the active need's phase/step, agent, and handoff state. To enable:\r\n\r\n```bash\r\nbash scripts/wf-statusline-apply.sh on # backs up your existing statusLine.command\r\nbash scripts/wf-statusline-apply.sh off # restores the backup\r\n```\r\n\r\nIf you already have a `statusLine.command`, the original output is printed first and the `wf` block is appended on a new line.\r\n\r\n### 4. `.wf-config.json` β workflow tuning\r\n\r\nDrop a `.wf-config.json` at your repo root to tune model choice, review loops, watchdog cadence, etc. The file is optional β defaults apply when missing. Values are validated at every `/waterfall:new` / `/waterfall:resume`; an invalid value stops the bootstrap with an explicit error.\r\n\r\nA reference example is shipped at the plugin root: [`.wf-config.example.md`](./.wf-config.example.md).\r\n\r\n| Param | Description | Default | Allowed values |\r\n|---|---|---|---|\r\n| `models.pm` | Model for **PM** (project manager, team lead, HO relay) | `sonnet` | `opus`, `sonnet`, `haiku` |\r\n| `models.or` | Model for **OR** (orchestrator, state machine driver) | `sonnet` | `opus`, `sonnet`, `haiku` |\r\n| `models.po` | Model for **PO** (PRD, specs, acceptance) | `sonnet` | `opus`, `sonnet`, `haiku` |\r\n| `models.tl` | Model for **TL** (tech design, code review, DV pool mgmt) | `opus` | `opus`, `sonnet`, `haiku` |\r\n| `models.rv` | Model for **RV** (cross-reviewer of PO/TL/DS artifacts) | `opus` | `opus`, `sonnet`, `haiku` |\r\n| `models.qa` | Model for **QA** (functional test plan execution) | `sonnet` | `opus`, `sonnet`, `haiku` |\r\n| `models.dv` | Model for **DV** (implementation + unit tests) | `sonnet` | `opus`, `sonnet`, `haiku` |\r\n| `models.ds` | Model for **DS** (UI/UX, only if `has_ui:true`) | `haiku` | `opus`, `sonnet`, `haiku` |\r\n| `review_loops.artifacts` | Max RV cycles on artifacts (PRD, specs, design, ui) | `2` | integer β₯ 1 |\r\n| `review_loops.code` | Max TL cycles on delivered code | `3` | integer β₯ 1 |\r\n| `watchdog.interval` | Watchdog cron cadence (PM wakeup to detect STUCK agents) | `3min` | `off`, `3min`, `5min`, `10min` |\r\n| `agent_mode` | Agent spawn mechanism | `team` | `team` (Agent Teams β implicit team via Agent spawn + inter-agent SendMessage, native delivery/idle, CLI v2.1.178+), `subagent-light` (PM+TL only, 3 artefacts specs/design/tasks, 3 HO interactions β for small needs where the full pipeline is overkill). `subagent` is a **deprecated alias of `team`** (F-039). |\r\n| `dark_factory` | Autonomy mode for checkpoints | `off` | `on` (auto-validate, log decision), `off` (escalate to HO via AskUserQuestion) |\r\n| `statusline` | Waterfall statusline state β managed by `scripts/wf-statusline-apply.sh`, do not edit manually | `false` | `true`, `false` |\r\n| `tools.semgrep` | Run Semgrep static analysis during TL code review (auto-detects native CLI or Docker, silent skip if neither) | `off` | `on`, `off` |\r\n| `tools.semgrep_rules` | Semgrep rulesets passed as `--config` (registry packs `p/...` or local YAML paths) | `[\"p/owasp-top-ten\", \"p/cwe-top-25\", \"p/default\"]` | non-empty array of strings |\r\n\r\n**Example** (`.wf-config.json` at repo root):\r\n\r\n```json\r\n{\r\n \"models\": { \"pm\": \"sonnet\", \"or\": \"sonnet\", \"po\": \"sonnet\", \"tl\": \"opus\", \"rv\": \"sonnet\", \"qa\": \"sonnet\", \"dv\": \"sonnet\", \"ds\": \"sonnet\" },\r\n \"review_loops\": { \"artifacts\": 2, \"code\": 3 },\r\n \"watchdog\": { \"interval\": \"3min\" },\r\n \"agent_mode\": \"team\",\r\n \"dark_factory\": \"off\",\r\n \"statusline\": false,\r\n \"tools\": { \"semgrep\": \"off\" }\r\n}\r\n```\r\n\r\n---\r\n\r\n## Usage\r\n\r\n```\r\n/waterfall:new # start a new need\r\n/waterfall:resume # resume an interrupted need\r\n/waterfall:quit # cleanly stop the active need\r\n```\r\n\r\nEach need is created at `wf/needs//` in your project. From there, the orchestrator drives PM β PO β TL β DV β RV β QA through the waterfall, asking you for input only at the checkpoints that require human judgment (brief, PRD validation, design approval, acceptance).\r\n\r\nFor a deeper dive β agent contracts, state machine diagram, recovery patterns, and best practices β see the upcoming documentation site.\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT β see [LICENSE](LICENSE).\r\n",
"bytes": 9762,
"sha": "cfbd730fe2316261a83c3fdd46e9dcafa08a7d80f2c1f99b9d0d8d304eb1b409",
"repo_slug": "mgallet92i/waterfall",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_mgallet92i_waterfall_waterfall_227b54b0/readme"
}