nWave: a seven-wave delivery workflow for Claude Code

The problem nWave is aimed at: agent output with no review points

Most coding agents give you one long turn. You describe a feature, the agent writes files, and you inspect the diff afterwards. When the result is wrong, the failure is usually upstream of the code: the requirements were never written down, the design was never agreed, and nobody noticed until the tests failed.

nWave takes the opposite position. It splits feature delivery 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. The unit of work is not a prompt, it is a set of documents that a human signs off on.

That makes it a poor fit for quick scripts and a reasonable fit for teams that already argue about requirements. The README frames the audience through a before/after pair: before nWave, the question is where to start and which agent to use; after nWave, a buddy command reads the project and returns a concrete next step. The framework assumes you have a project directory worth reading.

How the seven waves and the artifact directory fit together

The mechanism is a directory convention plus a set of Claude Code commands. Each wave writes its artifacts into a per-feature workspace, and the repository ships a guide called Wave Directory Structure that documents how those artifacts are organized. The waves are not just labels: the release notes for v3.22.1 mention routing platform and delivery architecture work to the appropriate specialist, which implies different agents own different waves and the framework decides which one handles a given piece of work.

A second mechanism sits under the design wave. The Outcomes Registry is described as a way to catch duplicate rules and operations at design time, and the v3.22.1 notes record that the installed registry now includes the schema it needs. That is a design-time check, not a lint step after the fact.

The plugin payload is generated. The pyproject.toml force-includes nWave/agents, nWave/scripts, nWave/skills, nWave/tasks/nw, nWave/templates, nWave/framework-catalog.yaml and nWave/VERSION into the wheel, alongside scripts/install, scripts/shared, the DES library under lib/python/des, and schemas. Contributor guidance in v3.22.1 identifies the generated plugin payload and its canonical sources, which tells you the .claude-plugin directory is not edited by hand.

One more piece is worth naming because it changes how the tool behaves on a shared machine. Since v3.19 the globally installed DES 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, opt-in by default or all, decides where nWave runs.

Installing nWave and running your first command

The README gives a five-minute install path. Requirements are Python 3.10 or newer and Claude Code. The installer wires the nwave-ai CLI into Claude Code in one step, prefers uv when it is available, and supports pipx without recommending it.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/nWave-ai/nWave/main}/scripts/install/install.sh)"

Restart Claude Code when the installer finishes. If you need CLI flags, environment variables, CI or non-interactive use, or manual and offline steps, the README points to the Installation Guide rather than listing them inline.

The first command runs inside Claude Code, not in your shell. Type it in the Claude Code prompt:

/nw-buddy What should I do next?

The README says the buddy reads your project and reports which wave to start, where your artifacts are, and how to use nWave for your specific context. It is documented as working on day one with no configuration. After that, the tutorial called Your First Feature is the end-to-end walkthrough the README points to for zero to working code.

For per-repository control, the v3.19 notes document a small command surface. These run in your shell, not inside Claude Code:

nwave-ai project enable
nwave-ai mode
nwave-ai status

The CLI reference lists install, uninstall, doctor, status, project, mode, attribution, completion and version as the user-facing commands, and notes that install passes flags through to the underlying installer. Running nwave-ai status is the quickest way to see whether a given repository is marked for activation.

Where nWave gets in the way

The most concrete limitation is documented by the maintainers themselves. The v3.22.1 notes state that the commit-metadata correction reported in issue #78 is not complete: some generated metadata may not be recognized as Git trailers. The note asks readers to keep tracking #78 rather than relying on that correction in v3.22.1. If your pipeline parses commit trailers, test against your own history before you depend on it.

The second constraint is the activation model. Because hooks are globally installed but opt-in per repository, a repository that has not been marked stays silent. That is good hygiene and a bad surprise: a developer who expects nWave to react and gets nothing should check nwave-ai status before debugging the agent.

The third is scope. The release notes are explicit that v3.22.1 remains a v3 release and does not include the experimental v4 line, and that no polyglot toolchain was added while the installed polyglot templates are unchanged from v3.21. The project also classifies itself as Development Status 3 - Alpha in pyproject.toml, despite the version number reading 3.22.1.

Finally, the workflow itself is the cost. Seven waves with approval gates mean seven opportunities to be asked a question. If your feature is a two-line fix, the framework produces more artifacts than code.

nWave against a plain Claude Code session

The honest alternative is not another framework. It is using Claude Code directly, with your own conventions for where specs live and when you review.

The difference is where the structure lives. In a plain session, the process is in your head and in whatever you paste into the prompt. In nWave, the process is in the repository: named waves, named agents, and artifacts written to a documented directory per feature. That is the trade. You get repeatability across developers and a paper trail; you give up the ability to skip a step because today the step is obviously unnecessary.

The second alternative is a lighter tool that only does test-driven development. nWave has a TDD canon of its own. The v3.15 notes describe a 3-phase contract, RED then GREEN then COMMIT, replacing a legacy 5-phase contract of PREPARE, RED_ACCEPTANCE, RED_UNIT, GREEN, COMMIT, documented in ADR-025, with dual-canon backward compatibility for existing audit logs. A dedicated TDD runner would do that one job with less surrounding ceremony. nWave bundles it into a wider delivery process, which is either the point or the overhead depending on what you needed.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-05. Releases arrive on a real cadence: v3.21.0 on 2026-06-27, v3.22.0 on 2026-08-29, and v3.22.1 on 2026-09-05. The v3.22.1 notes describe it 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.

Upgrade cost is concentrated in two places. The first is the documentation-density setting: v3.22.1 documents and validates supported documentation-density prompt modes, and there is a guide on configuring doc density that controls lean versus full wave output. If you have tuned that, re-read the guide after upgrading. The second is methodology. The move from the 5-phase to the 3-phase TDD canon is the kind of change that can invalidate existing audit logs, and the notes claim dual-canon backward compatibility rather than a clean break.

Security work is part of the upgrade story. The v3.22.0 hardening replaced legacy content fingerprints with SHA-256 and removed the vulnerable gitlint toolchain. If you are pinned to an older v3 release for other reasons, that change is the argument for moving.

The licence is MIT, declared in both LICENSE and the pyproject.toml license field, and the package is published as nwave-ai on the Python side. MIT is permissive, but the repository also carries a PRIVACY.md and the installer writes hooks into a globally installed location, so the practical question for a company is not the licence text, it is what the hooks read and where artifacts are stored. That is a policy review, not a legal one, and the PRIVACY.md file is the place to start it.

Editorial conclusion

Adopt nWave if you already work inside Claude Code, your team writes features down before coding, and you want artifacts reviewed at named gates rather than a single agent turn you have to trust. Skip it if you want a library you import, if your work is exploratory and rarely reaches a spec, or if you cannot run the installer on developer machines. Before committing, verify three things: that your Python version is 3.10 or newer, that the opt-in activation behaves as you expect by running nwave-ai status in a repository you have not enabled, and that the open commit-metadata issue #78 does not affect how your pipeline reads generated Git trailers.

Frequently asked questions

Official sources

1. License: MIT
2. nWave-ai/nWave on GitHub
3. Project website
4. README
5. Releases