# nwave-ai/nwave architecture

> Architecture diagram of the GitHub repository nwave-ai/nwave, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nwave-ai/nwave
- Repository: https://github.com/nwave-ai/nwave
- Video tour (about a minute): https://gitdiagram.com/nwave-ai/nwave/video

## Overview

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: [`src/des/adapters/drivers/hooks/session_start_handler.py`](https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/drivers/hooks/session_start_handler.py) (Session start), [`src/des/adapters/drivers/hooks/hook_router.py`](https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/drivers/hooks/hook_router.py) (Hook routing), [`src/des/application/subagent_stop_service.py`](https://github.com/nwave-ai/nwave/blob/main/src/des/application/subagent_stop_service.py) (Completion validation), [`nwave_ai/outcomes/application/registry_service.py`](https://github.com/nwave-ai/nwave/blob/main/nwave_ai/outcomes/application/registry_service.py) (Outcome registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Setup"]
  node_cli["nwave-ai CLI<br/>[cli.py]"]
  node_installer["Installer<br/>[install_nwave.py]"]
  node_wave_workflow["Seven-wave workflow"]
end

subgraph group_des["DES Enforcement"]
  node_hook_router["Hook routing<br/>[hook_router.py]"]
  node_session_handler["Session start"]
  node_housekeeping["Housekeeping"]
  node_update_service["Update checks"]
  node_pending_update["Pending updates"]
  node_pm_adapter["Package adapters"]
  node_stop_handler["Subagent stop"]
  node_stop_service["Completion validation"]
  node_step_repository["Step state"]
end

subgraph group_spec["Specification Tools"]
  node_feature_cli["Feature-delta CLI<br/>[cli.py]"]
  node_feature_validator["Delta validation<br/>[validator.py]"]
  node_feature_rules["Delta rules"]
  node_outcomes_cli["Outcomes CLI<br/>[cli.py]"]
  node_registry_service["Outcome registry"]
  node_collision["Collision detection"]
end

subgraph group_diagnostics["Health and Updates"]
  node_doctor["Doctor checks<br/>[runner.py]"]
end

node_user(("Developer"))
node_claude(("Claude Code"))
node_project_files[("Project files")]

node_user -->|"uses"| node_claude
node_claude -->|"guides delivery"| node_wave_workflow
node_user -->|"runs commands"| node_cli
node_cli -->|"invokes install"| node_installer
node_claude -->|"dispatches events"| node_hook_router
node_hook_router -->|"routes session"| node_session_handler
node_session_handler -->|"runs housekeeping"| node_housekeeping
node_session_handler -->|"checks updates"| node_update_service
node_session_handler -->|"applies pending update"| node_pending_update
node_pending_update -->|"upgrades package"| node_pm_adapter
node_pm_adapter -->|"reruns install"| node_installer
node_hook_router -->|"routes stop"| node_stop_handler
node_stop_handler -->|"validates completion"| node_stop_service
node_stop_service -->|"reads execution log"| node_project_files
node_stop_service -->|"writes audit data"| node_project_files
node_user -->|"validates delta"| node_feature_cli
node_feature_cli -->|"invokes validation"| node_feature_validator
node_feature_validator -->|"applies rules"| node_feature_rules
node_user -->|"manages outcomes"| node_outcomes_cli
node_outcomes_cli -->|"registers or checks"| node_registry_service
node_registry_service -->|"checks collisions"| node_collision
node_registry_service -->|"reads and writes registry"| node_project_files
node_user -->|"runs diagnostics"| node_doctor

click node_cli "https://github.com/nwave-ai/nwave/blob/main/nwave_ai/cli.py"
click node_installer "https://github.com/nwave-ai/nwave/blob/main/scripts/install/install_nwave.py"
click node_wave_workflow "https://github.com/nwave-ai/nwave/tree/main/nwave_ai"
click node_hook_router "https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/drivers/hooks/hook_router.py"
click node_session_handler "https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/drivers/hooks/session_start_handler.py"
click node_housekeeping "https://github.com/nwave-ai/nwave/blob/main/src/des/application/housekeeping_service.py"
click node_update_service "https://github.com/nwave-ai/nwave/blob/main/src/des/application/update_check_service.py"
click node_pending_update "https://github.com/nwave-ai/nwave/blob/main/src/des/application/pending_update_service.py"
click node_pm_adapter "https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/driven/package_managers/uv_package_manager_adapter.py"
click node_stop_handler "https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/drivers/hooks/subagent_stop_handler.py"
click node_stop_service "https://github.com/nwave-ai/nwave/blob/main/src/des/application/subagent_stop_service.py"
click node_step_repository "https://github.com/nwave-ai/nwave/blob/main/src/des/domain/step_file_repository.py"
click node_feature_cli "https://github.com/nwave-ai/nwave/blob/main/nwave_ai/feature_delta/cli.py"
click node_feature_validator "https://github.com/nwave-ai/nwave/blob/main/nwave_ai/feature_delta/application/validator.py"
click node_feature_rules "https://github.com/nwave-ai/nwave/tree/main/nwave_ai/feature_delta/domain/rules"
click node_outcomes_cli "https://github.com/nwave-ai/nwave/blob/main/nwave_ai/outcomes/cli.py"
click node_registry_service "https://github.com/nwave-ai/nwave/blob/main/nwave_ai/outcomes/application/registry_service.py"
click node_collision "https://github.com/nwave-ai/nwave/blob/main/nwave_ai/outcomes/application/collision_detector.py"
click node_doctor "https://github.com/nwave-ai/nwave/blob/main/nwave_ai/doctor/runner.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_installer,node_wave_workflow toneBlue
class node_hook_router,node_session_handler,node_housekeeping,node_update_service,node_pending_update,node_pm_adapter,node_stop_handler,node_stop_service,node_step_repository,node_project_files toneAmber
class node_feature_cli,node_feature_validator,node_feature_rules,node_outcomes_cli,node_registry_service,node_collision toneMint
class node_doctor toneRose
class node_user,node_claude toneIndigo
```

## Components

### CLI and Setup

- [nwave-ai CLI](https://github.com/nwave-ai/nwave/blob/main/nwave_ai/cli.py): `nwave_ai/cli.py`
- [Installer](https://github.com/nwave-ai/nwave/blob/main/scripts/install/install_nwave.py): `scripts/install/install_nwave.py`
- [Seven-wave workflow](https://github.com/nwave-ai/nwave/tree/main/nwave_ai): `nwave_ai`

### DES Enforcement

- [Hook routing](https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/drivers/hooks/hook_router.py): `src/des/adapters/drivers/hooks/hook_router.py`
- [Session start](https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/drivers/hooks/session_start_handler.py): `src/des/adapters/drivers/hooks/session_start_handler.py`
- [Housekeeping](https://github.com/nwave-ai/nwave/blob/main/src/des/application/housekeeping_service.py): `src/des/application/housekeeping_service.py`
- [Update checks](https://github.com/nwave-ai/nwave/blob/main/src/des/application/update_check_service.py): `src/des/application/update_check_service.py`
- [Pending updates](https://github.com/nwave-ai/nwave/blob/main/src/des/application/pending_update_service.py): `src/des/application/pending_update_service.py`
- [Package adapters](https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/driven/package_managers/uv_package_manager_adapter.py): `src/des/adapters/driven/package_managers/uv_package_manager_adapter.py`
- [Subagent stop](https://github.com/nwave-ai/nwave/blob/main/src/des/adapters/drivers/hooks/subagent_stop_handler.py): `src/des/adapters/drivers/hooks/subagent_stop_handler.py`
- [Completion validation](https://github.com/nwave-ai/nwave/blob/main/src/des/application/subagent_stop_service.py): `src/des/application/subagent_stop_service.py`
- [Step state](https://github.com/nwave-ai/nwave/blob/main/src/des/domain/step_file_repository.py): `src/des/domain/step_file_repository.py`

### Specification Tools

- [Feature-delta CLI](https://github.com/nwave-ai/nwave/blob/main/nwave_ai/feature_delta/cli.py): `nwave_ai/feature_delta/cli.py`
- [Delta validation](https://github.com/nwave-ai/nwave/blob/main/nwave_ai/feature_delta/application/validator.py): `nwave_ai/feature_delta/application/validator.py`
- [Delta rules](https://github.com/nwave-ai/nwave/tree/main/nwave_ai/feature_delta/domain/rules): `nwave_ai/feature_delta/domain/rules`
- [Outcomes CLI](https://github.com/nwave-ai/nwave/blob/main/nwave_ai/outcomes/cli.py): `nwave_ai/outcomes/cli.py`
- [Outcome registry](https://github.com/nwave-ai/nwave/blob/main/nwave_ai/outcomes/application/registry_service.py): `nwave_ai/outcomes/application/registry_service.py`
- [Collision detection](https://github.com/nwave-ai/nwave/blob/main/nwave_ai/outcomes/application/collision_detector.py): `nwave_ai/outcomes/application/collision_detector.py`

### Health and Updates

- [Doctor checks](https://github.com/nwave-ai/nwave/blob/main/nwave_ai/doctor/runner.py): `nwave_ai/doctor/runner.py`

### Other components

- **Developer**
- **Claude Code**
- **Project files**

## Connections

- 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
