nWave: a seven-wave delivery process that runs inside Claude Code
AI agents that guide you from idea to working code, with you in control at every step.
At a glance
- What is it?
- nWave is an MIT-licensed Python CLI plus a set of Claude Code agents and commands that split feature delivery into seven reviewable waves. It is a process tool with a gate at every step, and the gates are the point.
- Who is it for?
- Adopt nWave if your team already works in Claude Code and wants agent output to land in a named, reviewable artifact structure rather than in a chat scrollback. Do not adopt it if you want a framework that runs your own orchestration loop in CI, or if you cannot accept that a skipped commit was, until v3.22.1, counted as completed work.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 10 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem nWave targets: agent output with no review surface
Most agentic coding tools produce a diff. nWave produces a sequence of artifacts with a human approval gate between each one. The README frames the pain directly: before nWave, a developer asks where to start, whether requirements or code come first, and which agent to use. The project's answer is to fix the order in advance. Feature delivery is split into seven waves: discover, diverge, discuss, design, devops, distill, deliver. Specialized agents produce artifacts at each wave, and the README states that you review and approve before proceeding. That is the whole proposition. It is aimed at developers and small teams already inside Claude Code who find that a single long agent session blurs requirements, design and implementation into one unreviewable block. The audience is narrow on purpose. If you are not in Claude Code, the command surface described in the README does not exist for you, and the installation guide points pipx, OpenCode and Codex users at separate instructions.
How the seven waves and the buddy command fit together
The mechanism visible in the material is a fixed pipeline plus a router. The pipeline is the seven waves, each with agents that write artifacts, and each wave ending at an approval step. The router is /nw-buddy. The README gives the first command as /nw-buddy What should I do next? and says the buddy reads your project, tells you which wave to start, where your artifacts are, and how to use nWave for your specific context. It also states this works on day one with no configuration. So the entry point is not a config file but a question. Artifacts are organized per feature, and the README links a Wave Directory Structure guide and a Feature Delta Format (L7) guide for authoring features in what it calls the lean single-file model. There is also an Outcomes Registry, described as catching duplicate rules and operations at design time, with a CLI reference page. Taken together, the data flow is: the buddy inspects the repository, names a wave, agents emit artifacts into a per-feature directory, a registry checks for duplicated rules at design time, and you approve before the next wave. Where the documentation is thin is the internals of the buddy itself. The README does not describe how it reads the project or what it inspects, so treat the routing as opaque and verify it on your own repository rather than assuming a particular detection heuristic.
Installing nWave and the CLI surface you actually touch
The README gives a one-line install: sh -c "$(curl -fsSL https://raw.githubusercontent.com/nWave-ai/nWave/main}/scripts/install/install.sh)". Note the stray brace before /scripts in the README text as supplied; the published install path is scripts/install/install.sh on the main branch, and that brace is worth checking against the live file before you pipe it to a shell. Requirements are Python 3.10+ and Claude Code. The installer sets up the nwave-ai CLI and wires nWave into Claude Code in one step, preferring uv when available and supporting pipx without recommending it. You restart Claude Code when it finishes. The v3.19 release notes document the user-facing command surface in one place: install, uninstall, doctor, status, project, mode, attribution, completion, version, including pass-through of install flags to the underlying installer. The same notes describe per-project activation. Globally installed hooks are opt-in per repository. Unmarked repositories stay silent and the hooks exit 0. A tracked .nwave/local-config.json marker plus a global activation.mode setting, with opt-in as the default and all as the alternative, decide where nWave runs. The commands nwave-ai project enable, nwave-ai project disable, nwave-ai mode and nwave-ai status manage that state. The notes also say existing projects auto-adopt on first /nw- use, so the opt-in gate does not break an existing setup. For CI or non-interactive use, the README defers to the Installation Guide rather than documenting flags inline, and there is a separate offline and air-gapped install guide for machines without PyPI access.
The known limitation in v3.22.1 and what it means for release tooling
The release notes are unusually direct about a defect that survived the maintenance release. Under Known limitation, v3.22.1 states that the commit-metadata correction reported in issue #78 is not complete: some generated metadata may not be recognized as Git trailers, and readers are told to keep tracking #78 rather than rely on the correction. If your pipeline parses trailers, for example to derive changelogs or to link commits back to features, that is a real gap and not a cosmetic one. The v3.22.1 notes also list a fix for a skipped commit no longer counting as completed work (#99), which implies that before this release a skipped commit could be recorded as done. Both items matter for the same reason: nWave's value rests on the accuracy of its own bookkeeping, since the artifacts and the wave state are what you are asked to trust. A second boundary comes from the release scope statement. Graphify ran only inside the release workflow's isolated verification environment and is not included in release artifacts or installed for users. No polyglot toolchain was added, and the installed polyglot templates are unchanged from v3.21. The release remains a v3 release and does not include the experimental v4 line, so anyone reading about v4 features should not expect them in this artifact.
Where nWave is the wrong tool, and what to use instead
nWave is the wrong tool when the process is the thing you want to own. It imposes seven named waves and a review gate at each one. That is a cost as much as a control. If your team already has a delivery process, nWave does not adapt to it; you adapt to the wave names, the per-feature artifact directory, and the approval step. A concrete alternative in the same space is a plain Claude Code setup with hand-written skills and subagents, which the repository's own topic list names as claude-code-skills and claude-code-subagents. The difference in approach is that you write the prompts and the directory conventions yourself, and nothing enforces a wave order or an approval gate. You get full control over what the agent sees and no framework to upgrade. The trade is that you also get no buddy to route you, no outcomes registry to catch duplicated rules at design time, and no shared artifact layout for a second developer joining the project, which is the case the Team Rollout Guide addresses. For a solo developer on a small feature, the seven-wave structure can be more ceremony than the task warrants, and the documentation-density setting exists precisely because the full wave output is not always wanted; the README links a guide on configuring doc density and the v3.22.1 notes mention supported documentation-density prompt modes being documented and validated (#84). Choosing between the two approaches comes down to whether you want the ordering decided for you.
Maintenance cadence, upgrade cost and the MIT licence
The release history shows a steady maintenance line rather than a burst. v3.22.1 landed on 2026-09-05, v3.22.0 a week earlier on 2026-08-29, and v3.21.0 back on 2026-06-27. The gap between v3.21.0 and v3.22.0 is roughly two months, and v3.22.1 is described as the current corrective maintenance release for the v3 line, carrying forward twelve community fixes across installation, configuration, finalization, diagnostics, repository hygiene, command discovery and contributor guidance. That is a useful signal about upgrade cost: the project ships corrective releases that touch installation and hook wiring, so an upgrade is not purely a code change. The v3.19 notes describe a behavioural change in activation that was softened by auto-adoption on first /nw- use, which is the pattern to expect. The v3.15 notes describe a methodology change, a 3-Phase TDD Canon of RED, GREEN, COMMIT replacing a legacy 5-phase contract, documented in ADR-025, with dual-canon backward compatibility for existing audit logs. That is the kind of change that can affect how your artifacts look across a version boundary, so read the What's New page for a release before upgrading a repository that already holds wave artifacts. On licensing, the repository is MIT, which permits commercial use and modification; that is a statement about the licence text, not legal advice, and if you redistribute nWave inside a product you should read the licence file and your own obligations rather than rely on this summary.
Who should adopt nWave, and the first three things to check
The fit is a team that already lives in Claude Code, has more than one developer touching the same feature set, and wants agent output to accumulate in a named artifact structure instead of a session. The Team Rollout Guide exists for exactly the second-developer case, and the per-project activation model in v3.19 means you can turn nWave on for one repository and leave the rest silent. The misfit is a solo developer on small changes, anyone outside Claude Code who wants the same command surface, and anyone who needs the wave state to be authoritative for release automation, given that the commit-metadata correction in #78 is stated as incomplete. Three checks before you commit a repository. First, run nwave-ai doctor and nwave-ai status after install to confirm the hooks are wired and the activation mode is what you expect. Second, confirm the install script path in the README matches the live file, since the supplied README text contains a stray brace in the URL. Third, if you parse Git trailers anywhere downstream, reproduce that path against a v3.22.1 commit before you depend on it, because the release notes tell you not to rely on the #78 correction yet. Everything else in the release, including the SHA-256 content fingerprint change and the removal of the gitlint toolchain, is hardening you inherit by upgrading rather than work you have to schedule.
Editorial conclusion
Adopt nWave if your team already works in Claude Code and wants agent output to land in a named, reviewable artifact structure rather than in a chat scrollback. Do not adopt it if you want a framework that runs your own orchestration loop in CI, or if you cannot accept that a skipped commit was, until v3.22.1, counted as completed work. Before committing, run nwave-ai doctor and nwave-ai status on one repository, then check whether the commit-metadata issue tracked as #78 affects your trailer-based release tooling, because the v3.22.1 release notes state that correction is incomplete.
Community notes