by nWave-ai
AI agents that guide you from idea to working code, with you in control at every step.
# Add to your Claude Code skills
git clone https://github.com/nWave-ai/nWaveAI agents that guide you from idea to working code — with human judgment at every gate.
nWave runs inside Claude Code. It breaks feature delivery into seven waves (discover, diverge, discuss, design, devops, distill, deliver). Specialized agents produce artifacts at each wave. You review and approve before proceeding. The machine never runs unsupervised end-to-end.
/nw-buddy — Your AI concierge. Not sure where to start? Ask the buddy. It reads your project and gives contextual answers about methodology, commands, project state, and troubleshooting.For upgrading from v3.3 or earlier, see Breaking Changes below.
machine human machine human machine
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
Agent ──→ Documentation ──→ Review ──→ Decision ──→ Agent ──→ ...
generates artifacts validates approves continues
No comments yet. Be the first to share your thoughts!
Each wave produces artifacts that you review before the next wave begins. The machine never runs unsupervised end-to-end.
The workflow has seven waves. Entry point depends on your context:
| Wave | Command | Agent | Entry? |
|------|---------|-------|--------|
| DISCOVER | /nw-discover | product-discoverer | Greenfield: explore market and problem space |
| DIVERGE | /nw-diverge | nw-diverger | Greenfield: structured brainstorming before converging |
| DISCUSS | /nw-discuss | product-owner | All: write requirements and user journeys |
| DESIGN | /nw-design | system-designer, ddd-architect, solution-architect | All: architecture and domain model |
| DEVOPS | /nw-devops | platform-architect | All: infrastructure and deployment |
| DISTILL | /nw-distill | acceptance-designer | All: acceptance tests (Given-When-Then) |
| DELIVER | /nw-deliver | software-crafter | All: TDD implementation |
Wave routing: Entry points vary by context:
DISTILL → DELIVER is always the terminal pair. See the Wave Routing Guide for the full decision matrix.
40 agents total: 10 wave agents (including 3 DESIGN specialists), 1 concierge, 8 cross-wave specialists, 14 peer reviewers, 7 business agents. Full list: Commands Reference
match/case statements and X | Y union type syntax introduced in Python 3.10. Verify with python3 --version.Full feature support. Install from PyPI:
pipx install nwave-ai
nwave-ai install
Agents and commands go to ~/.claude/.
Don't have pipx? Install with:
pip install pipx && pipx ensurepath, then restart your terminal. Windows users: Use WSL (Windows Subsystem for Linux). Install with:wsl --install
Full setup details: Installation Guide
Quick setup, but does not support all features (DES enforcement, hook customization, rigor profiles). Use the CLI installer for full functionality.
/plugin marketplace add nwave-ai/nwave
/plugin install nw@nwave-marketplace
Restart Claude Code and type /nw- to see available commands.
nWave also works with OpenCode, an open-source IDE for AI pair programming. Installation requires a few extra steps to configure OpenCode's environment.
Install prerequisites:
npm install -g opencode-ai
pipx install nwave-ai
Configure OpenCode:
mkdir -p ~/.config/opencode
echo '{"model": "openai/gpt-4o-mini"}' > ~/.config/opencode/opencode.json
Set your OpenAI API key:
export OPENAI_API_KEY=your-key-here
Install nWave into OpenCode:
nwave-ai install
Compatibility notes:
tool.execute.before mechanism/nw-discuss, /nw-design, /nw-distill, /nw-deliver commands for best results| Scenario | Use | Why | |----------|-----|-----| | First time | CLI | Full features, recommended path | | Team rollout | CLI | Automation, full DES enforcement | | Contributing | CLI | Dev scripts, internals access | | Quick trial | Plugin | Fast setup, but limited features |
Start with the buddy:
/nw-buddy What should I do next?
The buddy reads your project and gives contextual answers. Use it anytime you're unsure of the next step, where to find documents, or how a feature of nWave works.
Ready to build? Follow the waves:
/nw-diverge "user authentication approaches" # Design exploration (optional for greenfield)
/nw-discuss "user login with email and password" # Requirements
/nw-design --architecture=hexagonal # Architecture
/nw-distill "user-login" # Acceptance tests
/nw-deliver # TDD implementation
Each wave produces artifacts you review. The machine never runs unsupervised end-to-end.
Full walkthrough: Your First Feature
nWave checks for new versions when you open Claude Code. When available, you'll see a note in your context with version details and changes.
Plugin (self-hosted marketplace):
/plugin marketplace update nwave-marketplace
Available immediately after release — no review delay.
Plugin (official Anthropic directory):
The official directory pins plugins to reviewed versions. Updates go through Anthropic's review before reaching users. If you want the latest sooner, switch to the self-hosted marketplace:
/plugin marketplace add nwave-ai/nwave
/plugin install nw@nwave-marketplace
CLI method:
pipx upgrade nwave-ai
nwave-ai install
Adjust check frequency:
# Edit ~/.nwave/des-config.json: "update_check.frequency" = "daily", "weekly", "every_session", or "never"
Plugin method:
/plugin uninstall nw
CLI method:
nwave-ai uninstall # Remove agents, commands, config, DES hooks
pipx uninstall nwave-ai # Remove the Python package
Both methods remove agents, commands, and configuration from ~/.claude/. Your project files are unaffected.
nWave enforces proven engineering practices (TDD, peer review, mutation testing) at every step. Use /nw-rigor to adjust the depth of quality practices to match your task's risk level. A config tweak needs less rigor than a security-critical feature.
/nw-rigor # Interactive: compare profiles
/nw-rigor lean # Quick switch to lean mode
/nw-rigor custom # Build your own combination
| Profile | Agent | Reviewer | TDD | Mutation | Cost | Use When | |---------|-------|----------|-----|----------|------|----------| | lean | haiku | none | RED→GREEN | no | lowest | Spikes, config, docs | | standard (default) | sonnet | haiku | full 5-phase | no | moderate | Most features | | thorough | opus | sonnet | full 5-phase | no | higher | Critical features | | exhaustive | opus | opus | full 5-phase | ≥80% kill | highest | Production core | | custom | you choose | you choose | you choose | you choose | varies | Exact combination |
Picked once, persists across sessions. Every /nw-deliver, /nw-design, /nw-review respects your choice. Need to mix profiles? /nw-rigor custom walks 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
DES is nWave's quality enforcement layer — it monitors every Agent tool invocation during feature delivery to 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.
DES also runs automatic housekeeping at every session start: it removes audit logs beyond the retention window, cleans up signal files left by crashed sessions, and rotates the skill-loading log when it grows too large. This happens silently in the background and never blo