nwave-ai 1.1.27rc2

Modern CLI installer for nwave with rich terminal UI

nWave

AI agents that guide you from idea to working code — with you in control at every step.

nWave runs inside Claude Code. You describe what to build. Specialized agents handle requirements, architecture, test design, and implementation. You review and approve at each stage.

Quick Start

1. Install (in your terminal — not inside Claude Code):

pipx install nwave-ai
nwave-ai install

No repository clone needed. This installs nWave from PyPI and sets up agents and commands in ~/.claude/.

Don't have pipx? Install it first: pip install pipx && pipx ensurepath, then restart your terminal. pipx docs. Windows users: Use WSL, not cmd.exe or PowerShell. Install WSL first: wsl --install

Full setup details: Installation Guide

Staying updated — nWave checks for new versions when you open Claude Code. When an update is available, you'll see a note in Claude's context with the version and what changed. To update, run two commands in your terminal: pip install --upgrade nwave-ai (pulls the new package), then nwave-ai install (deploys the new framework files). To control check frequency: set update_check.frequency in ~/.nwave/des-config.json (daily / weekly / every_session / never).

2. Use (inside Claude Code, after reopening it):

/nw:discuss "user login with email and password"   # Requirements
/nw:design --architecture=hexagonal                 # Architecture
/nw:distill "user-login"                            # Acceptance tests
/nw:deliver                                         # TDD implementation

Four commands. Four human checkpoints. One working feature.

Full walkthrough: Your First Feature

Control Your Token Spend — Without Sacrificing Quality

nWave enforces proven engineering practices — TDD, peer review, mutation testing — at every step. /nw:rigor lets you scale the depth of those practices to match the stakes of your work. A config tweak doesn't need the same investment as a security-critical feature. You pick the profile; nWave enforces it everywhere.

/nw:rigor                    # Interactive: compare profiles, pick one
/nw:rigor lean               # Quick switch: apply immediately
/nw:rigor custom             # Build your own: choose each setting

Profile	Agent	Reviewer	Review	TDD	Mutation	Est. Cost	When to Use
lean	haiku	--	no	R→G	no	lowest	Spikes, config, docs
standard ⭐	sonnet	haiku	single	full 5-phase	no	moderate	Most work
thorough	opus	sonnet	double	full 5-phase	no	higher	Critical features
exhaustive	opus	opus	double	full 5-phase	≥80% kill	highest	Production core
custom	you choose	you choose	you choose	you choose	you choose	depends	Your exact combo
inherit	yours	haiku	single	full 5-phase	no	varies	You pick the model

Pick once — it persists across sessions. Change anytime. Every /nw:deliver, /nw:design, /nw:review respects your choice automatically. Need a combination no preset covers? /nw:rigor custom walks you through each setting.

/nw:rigor lean        # prototype fast
/nw:deliver           # haiku crafter, no review, RED→GREEN only
/nw:rigor standard    # ready to ship — bump up
/nw:deliver           # sonnet crafter, haiku reviewer, full TDD

Understanding DES Messages

DES is nWave's quality enforcement layer — it monitors every agent Task invocation during feature delivery to prevent unbounded execution, enforce TDD discipline, and protect accidental edits. Most DES messages are normal enforcement, not errors. They appear when agents skip required safety checks or when your code contains patterns that look like step execution.

Message	What It Means	What To Do
MISSING_MAX_TURNS	Task invocation forgot to set max_turns parameter.	Add max_turns=30 (or appropriate value) to the Task call. Recommended: 15 (quick), 25 (background), 30 (standard), 35 (research).
DES_MARKERS_MISSING	Task prompt mentions a step ID (01-01 pattern) but lacks DES markers.	Either: add DES markers for step execution, OR add <!-- DES-ENFORCEMENT : exempt --> comment if it's not actually step work.
Source write blocked	You tried to edit a file during active /nw:deliver outside a DES task.	Edit requests must go through the active deliver session. If you need to make changes, finalize the current session first.
TDD phase incomplete	Sub-agent returned without finishing all required TDD phases.	Re-dispatch the same agent to complete missing phases (typically COMMIT or refactoring steps).
nWave update available	SessionStart detected a newer version available.	Optional. Run nwave-ai install when ready to upgrade, or dismiss and continue working.
False positive blocks	Your prompt accidentally matches step-ID pattern (e.g., dates like "2026-02-09").	Add <!-- DES-ENFORCEMENT : exempt --> comment to exempt the Task from step-ID enforcement.

These messages protect code quality but never prevent your work — they guide you toward the safe path.

How It Works

  machine        human         machine        human         machine
    │              │              │              │              │
    ▼              ▼              ▼              ▼              ▼
  Agent ──→ Documentation ──→ Review ──→ Decision ──→ Agent ──→ ...
 generates    artifacts      validates   approves    continues

Each wave produces artifacts that you review before the next wave begins. The machine never runs unsupervised end-to-end.

The full workflow has six waves. Use all six for greenfield projects, or jump straight to /nw:deliver for brownfield work.

Wave	Command	Agent	Produces
DISCOVER	/nw:discover	product-discoverer	Market validation
DISCUSS	/nw:discuss	product-owner	Requirements
DESIGN	/nw:design	solution-architect	Architecture + ADRs
DEVOPS	/nw:devops	platform-architect	Infrastructure readiness
DISTILL	/nw:distill	acceptance-designer	Given-When-Then tests
DELIVER	/nw:deliver	software-crafter	Working implementation

22 agents total: 6 wave agents, 5 cross-wave specialists, 11 peer reviewers. Full list: Commands Reference

Documentation

Getting Started

• Installation Guide — Setup instructions
• Your First Feature — Build a feature end-to-end (tutorial)
• Jobs To Be Done — Which workflow fits your task

Guides & Reference

• Agents & Commands Reference — All agents, commands, skills, templates
• Invoke Reviewers — Peer review workflow
• Troubleshooting — Common issues and fixes

Community

• Discord — Questions, feedback, success stories
• GitHub Issues — Bug reports and feature requests
• Contributing — Development setup and guidelines

License

MIT — see LICENSE for details.