{"id":44737849,"url":"https://github.com/nwave-ai/nwave","last_synced_at":"2026-04-10T16:05:38.431Z","repository":{"id":338367923,"uuid":"1156929150","full_name":"nWave-ai/nWave","owner":"nWave-ai","description":"AI agents that guide you from idea to working code, with you in control at every step.","archived":false,"fork":false,"pushed_at":"2026-02-18T09:17:35.000Z","size":1397,"stargazers_count":103,"open_issues_count":2,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-02-19T01:31:01.761Z","etag":null,"topics":["ai","atdd","bdd","claude-code","devops","jobs-to-be-done","lean-ux","software-architecture","software-craftsmanship","tdd"],"latest_commit_sha":null,"homepage":"https://nwave.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nWave-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T08:10:46.000Z","updated_at":"2026-02-18T21:50:07.000Z","dependencies_parsed_at":"2026-02-18T23:00:38.093Z","dependency_job_id":null,"html_url":"https://github.com/nWave-ai/nWave","commit_stats":null,"previous_names":["nwave-ai/nwave"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/nWave-ai/nWave","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nWave-ai%2FnWave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nWave-ai%2FnWave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nWave-ai%2FnWave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nWave-ai%2FnWave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nWave-ai","download_url":"https://codeload.github.com/nWave-ai/nWave/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nWave-ai%2FnWave/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29637400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","atdd","bdd","claude-code","devops","jobs-to-be-done","lean-ux","software-architecture","software-craftsmanship","tdd"],"created_at":"2026-02-15T20:09:36.831Z","updated_at":"2026-04-10T16:05:38.409Z","avatar_url":"https://github.com/nWave-ai.png","language":"Python","readme":"# nWave\n\nAI agents that guide you from idea to working code — with human judgment at every gate.\n\nnWave runs inside [Claude Code](https://claude.com/product/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.\n\n## What's New in v3.5\n\n**[Full changelog →](https://github.com/nWave-ai/nWave/tree/main/docs/guides/whats-new-v35/)**\n\n- **`/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.\n- **DIVERGE wave** — Structured brainstorming before convergence. Explore design options with JTBD analysis, competitive research, and SCAMPER ideation before locking into a solution.\n- **Three DESIGN architects** — Routes to the right specialist for your need: system-level architecture (Titan), domain/DDD modeling (Hera), or application-level design (Morgan).\n- **SSOT document model** — Single source of truth for product documents. Build feature spec once, reuse across requirements, design, testing, and delivery — no document sprawl.\n\nFor upgrading from v3.3 or earlier, see [Breaking Changes](#breaking-changes) below.\n\n## How It Works\n\n```text\n  machine        human         machine        human         machine\n    │              │              │              │              │\n    ▼              ▼              ▼              ▼              ▼\n  Agent ──→ Documentation ──→ Review ──→ Decision ──→ Agent ──→ ...\n generates    artifacts      validates   approves    continues\n```\n\nEach wave produces artifacts that you review before the next wave begins. The machine never runs unsupervised end-to-end.\n\nThe workflow has seven waves. Entry point depends on your context:\n\n| Wave | Command | Agent | Entry? |\n|------|---------|-------|--------|\n| DISCOVER | `/nw-discover` | product-discoverer | Greenfield: explore market and problem space |\n| DIVERGE | `/nw-diverge` | nw-diverger | Greenfield: structured brainstorming before converging |\n| DISCUSS | `/nw-discuss` | product-owner | All: write requirements and user journeys |\n| DESIGN | `/nw-design` | system-designer, ddd-architect, solution-architect | All: architecture and domain model |\n| DEVOPS | `/nw-devops` | platform-architect | All: infrastructure and deployment |\n| DISTILL | `/nw-distill` | acceptance-designer | All: acceptance tests (Given-When-Then) |\n| DELIVER | `/nw-deliver` | software-crafter | All: TDD implementation |\n\n**Wave routing**: Entry points vary by context:\n- **Greenfield project**: Start at DISCOVER or DIVERGE, proceed through all waves\n- **Brownfield feature**: Start at DIVERGE or DISCUSS, skip to DESIGN\n- **Bug fix**: Jump straight to DISTILL (write failing test) then DELIVER\n- **Refactoring**: Jump to DELIVER (green already, refactor inside existing tests)\n\nDISTILL → DELIVER is always the terminal pair. See the [Wave Routing Guide](https://github.com/nWave-ai/nWave/tree/main/docs/guides/wave-routing-and-entry-points/) for the full decision matrix.\n\n40 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](https://github.com/nWave-ai/nWave/tree/main/docs/reference/commands/index.md)**\n\n## Quick Start\n\n### Requirements\n\n- **Python 3.10+** — nWave's DES hooks use `match/case` statements and `X | Y` union type syntax introduced in Python 3.10. Verify with `python3 --version`.\n\n### CLI Installer (Recommended)\n\nFull feature support. Install from PyPI:\n\n```bash\npipx install nwave-ai\nnwave-ai install\n```\n\nAgents and commands go to `~/.claude/`.\n\n\u003e **Don't have pipx?** Install with: `pip install pipx \u0026\u0026 pipx ensurepath`, then restart your terminal.\n\u003e **Windows users**: Use WSL (Windows Subsystem for Linux). Install with: `wsl --install`\n\nFull setup details: **[Installation Guide](https://github.com/nWave-ai/nWave/blob/main/docs/guides/installation-guide/README.md)**\n\n### Plugin (Limited)\n\nQuick setup, but does not support all features (DES enforcement, hook customization, rigor profiles). Use the CLI installer for full functionality.\n\n```\n/plugin marketplace add nwave-ai/nwave\n/plugin install nw@nwave-marketplace\n```\n\nRestart Claude Code and type `/nw-` to see available commands.\n\n### OpenCode Support (Alternative IDE)\n\nnWave also works with [OpenCode](https://github.com/opencode-dev/opencode), an open-source IDE for AI pair programming. Installation requires a few extra steps to configure OpenCode's environment.\n\n**Install prerequisites:**\n```bash\nnpm install -g opencode-ai\npipx install nwave-ai\n```\n\n**Configure OpenCode:**\n```bash\nmkdir -p ~/.config/opencode\necho '{\"model\": \"openai/gpt-4o-mini\"}' \u003e ~/.config/opencode/opencode.json\n```\n\n**Set your OpenAI API key:**\n```bash\nexport OPENAI_API_KEY=your-key-here\n```\n\n**Install nWave into OpenCode:**\n```bash\nnwave-ai install\n```\n\n**Compatibility notes:**\n- ~67% of nWave features work natively on OpenCode via compatibility paths\n- DES hooks integrate via OpenCode's `tool.execute.before` mechanism\n- Some advanced subagent coordination may differ from Claude Code — use the core `/nw-discuss`, `/nw-design`, `/nw-distill`, `/nw-deliver` commands for best results\n- For full feature parity and support, Claude Code remains the primary environment\n\n### Which method?\n\n| Scenario | Use | Why |\n|----------|-----|-----|\n| First time | CLI | Full features, recommended path |\n| Team rollout | CLI | Automation, full DES enforcement |\n| Contributing | CLI | Dev scripts, internals access |\n| Quick trial | Plugin | Fast setup, but limited features |\n\n### Use (inside Claude Code, after reopening it)\n\n**Start with the buddy:**\n\n```\n/nw-buddy What should I do next?\n```\n\nThe 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.\n\n**Ready to build? Follow the waves:**\n\n```\n/nw-diverge \"user authentication approaches\"       # Design exploration (optional for greenfield)\n/nw-discuss \"user login with email and password\"   # Requirements\n/nw-design --architecture=hexagonal                 # Architecture\n/nw-distill \"user-login\"                            # Acceptance tests\n/nw-deliver                                         # TDD implementation\n```\n\nEach wave produces artifacts you review. The machine never runs unsupervised end-to-end.\n\nFull walkthrough: **[Your First Feature](https://github.com/nWave-ai/nWave/tree/main/docs/guides/tutorial-first-feature/)**\n\n## Keeping nWave Updated\n\nnWave checks for new versions when you open Claude Code. When available, you'll see a note in your context with version details and changes.\n\n**Plugin (self-hosted marketplace):**\n```\n/plugin marketplace update nwave-marketplace\n```\n\nAvailable immediately after release — no review delay.\n\n**Plugin (official Anthropic directory):**\n\nThe 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:\n\n```\n/plugin marketplace add nwave-ai/nwave\n/plugin install nw@nwave-marketplace\n```\n\n**CLI method:**\n```bash\npipx upgrade nwave-ai\nnwave-ai install\n```\n\n**Adjust check frequency:**\n```bash\n# Edit ~/.nwave/des-config.json: \"update_check.frequency\" = \"daily\", \"weekly\", \"every_session\", or \"never\"\n```\n\n## Uninstalling\n\n**Plugin method:**\n```\n/plugin uninstall nw\n```\n\n**CLI method:**\n```bash\nnwave-ai uninstall              # Remove agents, commands, config, DES hooks\npipx uninstall nwave-ai        # Remove the Python package\n```\n\nBoth methods remove agents, commands, and configuration from `~/.claude/`. Your project files are unaffected.\n\n## Token Efficiency — Scale Quality to Stakes\n\nnWave 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.\n\n```\n/nw-rigor                    # Interactive: compare profiles\n/nw-rigor lean               # Quick switch to lean mode\n/nw-rigor custom             # Build your own combination\n```\n\n| Profile | Agent | Reviewer | TDD | Mutation | Cost | Use When |\n|---------|-------|----------|-----|----------|------|----------|\n| **lean** | haiku | none | RED→GREEN | no | lowest | Spikes, config, docs |\n| **standard** (default) | sonnet | haiku | full 5-phase | no | moderate | Most features |\n| **thorough** | opus | sonnet | full 5-phase | no | higher | Critical features |\n| **exhaustive** | opus | opus | full 5-phase | ≥80% kill | highest | Production core |\n| **custom** | *you choose* | *you choose* | *you choose* | *you choose* | varies | Exact combination |\n\nPicked 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.\n\n```\n/nw-rigor lean        # prototype fast\n/nw-deliver           # haiku crafter, no review, RED→GREEN only\n/nw-rigor standard    # ready to ship — bump up\n/nw-deliver           # sonnet crafter, haiku reviewer, full TDD\n```\n\n## Understanding DES Messages\n\nDES 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.\n\nDES 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 blocks your session.\n\n| Message | What It Means | What To Do |\n|---------|---------------|-----------|\n| **DES_MARKERS_MISSING** | Agent prompt mentions a step ID (01-01 pattern) but lacks DES markers. | Either: add DES markers for step execution, OR add `\u003c!-- DES-ENFORCEMENT : exempt --\u003e` comment if it's not actually step work. |\n| **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. |\n| **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). |\n| **nWave update available** | SessionStart detected a newer version available. | Optional. Run `pipx upgrade nwave-ai \u0026\u0026 nwave-ai install` when ready to upgrade, or dismiss and continue working. |\n| **False positive blocks** | Your prompt accidentally matches step-ID pattern (e.g., dates like \"2026-02-09\"). | Add `\u003c!-- DES-ENFORCEMENT : exempt --\u003e` comment to exempt the agent call from step-ID enforcement. |\n\nThese messages protect code quality but never prevent your work — they guide you toward the safe path.\n\n## Documentation\n\n### Getting Started\n\n- **[Installation Guide](https://github.com/nWave-ai/nWave/blob/main/docs/guides/installation-guide/README.md)** — Setup instructions\n- **[Your First Feature](https://github.com/nWave-ai/nWave/tree/main/docs/guides/tutorial-first-feature/)** — Build a feature end-to-end (tutorial)\n- **[Jobs To Be Done](https://github.com/nWave-ai/nWave/tree/main/docs/guides/jobs-to-be-done-guide/)** — Which workflow fits your task\n\n### Guides \u0026 Reference\n\n- **[Agents \u0026 Commands Reference](https://github.com/nWave-ai/nWave/tree/main/docs/reference/index.md)** — All agents, commands, skills, templates\n- **[Wave Directory Structure](https://github.com/nWave-ai/nWave/tree/main/docs/guides/wave-directory-structure/)** — How wave outputs are organized per feature\n- **[Invoke Reviewers](https://github.com/nWave-ai/nWave/tree/main/docs/guides/invoke-reviewer-agents/)** — Peer review workflow\n- **[Troubleshooting](https://github.com/nWave-ai/nWave/tree/main/docs/guides/troubleshooting-guide/)** — Common issues and fixes\n\n## Community\n\n- **[Discord](https://discord.gg/Cywj3uFdpd)** — Questions, feedback, success stories\n- **[GitHub Issues](https://github.com/nWave-ai/nWave/issues)** — Bug reports and feature requests\n- **[Contributing](CONTRIBUTING.md)** — Development setup and guidelines\n\n## Breaking Changes\n\n### Command Format (v2.8.0)\n\n**Starting with v2.8.0, all slash commands use hyphen format instead of colons.**\n\n| Before (v2.7.x) | After (v2.8.0+) |\n|---|---|\n| `/nw:deliver` | `/nw-deliver` |\n| `/nw:design` | `/nw-design` |\n| `/nw:discuss` | `/nw-discuss` |\n| `/nw:distill` | `/nw-distill` |\n| `/nw:discover` | `/nw-discover` |\n| *All other commands* | `/nw-{command}` |\n\n**Why?** Commands migrated from Claude Code's dynamic `commands/` directory to the stable `skills/` system to prevent commands from disappearing during long sessions.\n\n**To upgrade**: Run `pipx upgrade nwave-ai \u0026\u0026 nwave-ai install` (CLI) or `/plugin marketplace update nwave-marketplace` (plugin). Old `/nw:` commands are automatically removed.\n\n## Privacy\n\nnWave does not collect user data. See [Privacy Policy](PRIVACY.md) for details.\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnwave-ai%2Fnwave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnwave-ai%2Fnwave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnwave-ai%2Fnwave/lists"}