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/nWaveLast scanned: 5/16/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-16T06:21:46.156Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
AI 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.
Requirements: Python 3.10+ and Claude Code.
# Step 1: install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Step 2: install the nWave CLI
uv tool install nwave-ai
# Step 3: install nWave into Claude Code
nwave-ai install
# Step 4: verify everything is healthy
nwave-ai doctor
Restart Claude Code after step 3. The installer prints a success panel with the installed version number; run nwave-ai doctor to confirm everything is healthy.
Inside Claude Code, type:
/nw-buddy What should I do next?
The buddy reads your project and tells you which wave to start, where your artifacts are, and how to use nWave for your specific context. It works on day one with no configuration.
Before nWave: "Where do I start? Requirements doc or code first? Which agent?" After nWave: The buddy reads your project and gives you a concrete next step.
Using pipx or OpenCode instead? See alternative install methods.
| Resource | What it covers | |----------|---------------| | Your First Feature | End-to-end walkthrough, zero to working code | | Team Rollout Guide | Onboard a second developer onto an nWave project | | Offline / Air-Gapped Install | Install nWave on a machine without PyPI access | | Jobs To Be Done | Which wave fits your task | | Wave Directory Structure | How artifacts are organized per feature | | Feature Delta Format (L7) | Author features in the lean single-file model | | Outcomes Registry | Catch duplicate rules and operations at design time | | Configuring Doc Density | Control lean vs full wave output | | Agents and Commands Reference | All agents and commands | | Troubleshooting | Common issues and fixes |
feature-delta.md with schema-typed section headings (## Wave: <WAVE> / [REF|WHY|HOW] <name>). Tier-1 [REF] is auto-produced; Tier-2 [WHY] and [HOW] are opt-in via --expand. Downstream agents grep section headings instead of reading whole subdirectories. See Feature Delta Format (L7).nwave-ai validate-feature-delta <path> checks structural rules (E1–E5) and emits JSON for CI integration. Vendor-neutral: no hooks auto-installed; pick a recipe from Enforcement Recipes (12 platforms covered).nwave-ai outcomes register|check|check-delta flags spec-level collisions before code is written, via type-shape + keyword Jaccard. See Why an outcomes registry? and Your first outcome.lean vs full density controls how much each wave emits. Tune token cost per wave. See Configuring Doc Density.nwave-ai uninstall --force now removes all installed artifacts (skills/nw-*, lib/python/des/, all 5 DES hook event types in settings.json) while preserving user-created skills. Previous versions left ~197 skill dirs and 3 hook entries behind. See Troubleshooting → Uninstall left files behind.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
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 then 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.Follow the Install in 5 Minutes steps at the top of this page. Agents and commands go to ~/.claude/.
Don't have uv? Install with:
curl -LsSf https://astral.sh/uv/install.sh | shor see uv installation docs. Alternatively, use pipx (requires Python 3.10+):pip install pipx && pipx ensurepath. Windows users: Use WSL (Windows Subsystem for Linux). Install with:wsl --install
Full setup details: Installation Guide
Using pipx:
pipx install nwave-ai
nwave-ai install
nwave-ai doctor
Using OpenCode (open-source IDE alternative):
npm install -g opencode-ai
uv tool install nwave-ai # or: pipx install nwave-ai
mkdir -p ~/.config/opencode
echo '{"model": "openai/gpt-4o-mini"}' > ~/.config/opencode/opencode.json
export OPENAI_API_KEY=your-key-here
nwave-ai install
OpenCode compatibility: about 67% of nWave features work natively. For full feature parity, Claude Code remains the primary environment. See OpenCode compatibility notes below.
Using Codex (OpenAI CLI):
# Step 1: install Codex CLI if not already installed
# (Download from https://platform.openai.com/docs/guides/codex)
# Step 2: install nWave CLI
uv tool install nwave-ai # or: pipx install nwave-ai
# Step 3: install nWave into Codex
nwave-ai install --platform codex
# Step 4: verify DES hooks are wired
nwave-ai doctor
Codex integration: nWave's DES enforcement (TDD phase gates, validation hooks) fires when you run Codex sessions, j