How nwave-ai/nwave works
nWave is an AI-assisted feature-delivery framework used primarily inside Claude Code. Its documented workflow moves through discover, diverge, discuss, design, devops, distill, and deliver, with specialized agents producing artifacts for human review at each gate. The runtime also installs and diagnoses the CLI, enforces project activation and step-completion rules through DES hooks, and provides feature-delta validation and outcomes deduplication. The README documents the wave workflow, but the supplied tree does not expose its agent/artifact implementation; detailed wiring below is limited to the available source excerpts.
Main entry points: session_start_handler.py Session start · hook_router.py Hook routing · subagent_stop_service.py Completion validation · registry_service.py Outcome registry
Components 22
CLI and Setup
- nwave-ai CLI
nwave_ai/cli.py - Installer
scripts/install/install_nwave.py - Seven-wave workflow
nwave_ai
DES Enforcement
- Hook routing
src/des/adapters/drivers/hooks/hook_router.py - Session start
src/des/adapters/drivers/hooks/session_start_handler.py - Housekeeping
src/des/application/housekeeping_service.py - Update checks
src/des/application/update_check_service.py - Pending updates
src/des/application/pending_update_service.py - Package adapters
src/des/adapters/driven/package_managers/uv_package_manager_adapter.py - Subagent stop
src/des/adapters/drivers/hooks/subagent_stop_handler.py - Completion validation
src/des/application/subagent_stop_service.py - Step state
src/des/domain/step_file_repository.py
Specification Tools
- Feature-delta CLI
nwave_ai/feature_delta/cli.py - Delta validation
nwave_ai/feature_delta/application/validator.py - Delta rules
nwave_ai/feature_delta/domain/rules - Outcomes CLI
nwave_ai/outcomes/cli.py - Outcome registry
nwave_ai/outcomes/application/registry_service.py - Collision detection
nwave_ai/outcomes/application/collision_detector.py
Health and Updates
- Doctor checks
nwave_ai/doctor/runner.py
Other components
- Developer
- Claude Code
- Project files
Connections 23
- Developer → Claude Code: uses
- Claude Code → Seven-wave workflow: guides delivery
- Developer → nwave-ai CLI: runs commands
- nwave-ai CLI → Installer: invokes install
- Claude Code → Hook routing: dispatches events
- Hook routing → Session start: routes session
- Session start → Housekeeping: runs housekeeping
- Session start → Update checks: checks updates
- Session start → Pending updates: applies pending update
- Pending updates → Package adapters: upgrades package
- Package adapters → Installer: reruns install
- Hook routing → Subagent stop: routes stop
- Subagent stop → Completion validation: validates completion
- Completion validation → Project files: reads execution log
- Completion validation → Project files: writes audit data
- Developer → Feature-delta CLI: validates delta
- Feature-delta CLI → Delta validation: invokes validation
- Delta validation → Delta rules: applies rules
- Developer → Outcomes CLI: manages outcomes
- Outcomes CLI → Outcome registry: registers or checks
- Outcome registry → Collision detection: checks collisions
- Outcome registry → Project files: reads and writes registry
- Developer → Doctor checks: runs diagnostics