GitHub

nWave Tutorial Index

Tutorials teach by doing: a guided, hands-on lesson with a visible result. Pick by the job you want to learn.

The nwdes steps these lessons walk are your assistant's to run in real work; tutorial 1 is the one you type by hand — see For your assistant.

Currency note (v4). The tutorials under "The wave tutorials" and "Standalone lessons" were written for the 3.x workflow. The /nw-* commands they teach still exist, but 3.x delivery internals (per-wave directories, roadmap.json, execution-log.json) were removed in v4 and replaced by the nwdes handoff (What's new in v4). They are kept because the wave concepts and command behavior they teach still apply; expect artifact paths to differ.


Start here

# Tutorial Description JTBD Level Status
1 First feature with nwdes A safe walk through the command flow in a throwaway repository: create a handoff, declare one slice, observe RED, implement, reach GREEN, render examination material "See the delivery flow once, safely" Beginner Current (v4)
2 Deliver a feature (how-to) The practical first run on the v4 route: handoff, product facts, design, oracle, craft, review, examination, integration "Ship a feature fast with quality" Beginner Current (v4)
3 Fix a bug (how-to) The lean v4 route on one understood defect "Fix this defect properly, not just patch it" Beginner Current (v4)

Tutorial 1 uses fixed role-output fixtures, so it needs no model calls — read its disclaimer before treating anything in it as delivery evidence.


The wave tutorials (3.x workflow)

Sequenced lessons following the wave sequence DISCOVER → DIVERGE → DISCUSS → DESIGN → DEVOPS → DISTILL → DELIVER. Read the currency note above before starting.

# Tutorial Description JTBD Level
4 From Idea to Validated Problem (/nw-discover) Product discovery: validate a problem exists before writing code "Make sure I'm building the right thing" Intermediate
5 Exploring Design Directions (/nw-diverge) Evaluate multiple solution approaches and recommend one "Choose between competing design approaches" Intermediate
6 Requirements and UX Journey (/nw-discuss) Turn a validated problem into user stories with acceptance criteria "Get clear, testable requirements without a PM" Intermediate
7 Architecture Design (/nw-design + /nw-diagram) Design system architecture and generate diagrams from requirements "Make the right architecture decisions early" Intermediate
8 Generating Acceptance Tests (/nw-distill) Turn user stories and architecture into executable BDD acceptance tests "Turn requirements into executable specs" Intermediate
9 Delivering the Feature (/nw-deliver) Whole delivery on a multi-component feature (teaches the 3.x roadmap flow; for v4 use Deliver a feature) "Ship a non-trivial feature end-to-end" Intermediate
10 Production Readiness (/nw-devops) CI/CD, infrastructure design, and deployment strategy "Get to production with confidence" Intermediate

Standalone lessons (3.x workflow)

# Tutorial Description JTBD Level
11 Understanding the Delivery Pipeline What happened inside a 3.x /nw-deliver run, and how to read its artifacts "Know what the tool is doing so I can trust it" Beginner
12 Writing Acceptance Tests That Guide Delivery Write your own tests from scratch and deliver against them "Define what 'done' means, then let AI build it" Beginner
13 Safe Refactoring with Mikado (/nw-refactor + /nw-mikado) Untangle a messy codebase with progressive levels and the Mikado Method "Safely improve legacy code without breaking things" Intermediate
14 Debugging with 5 Whys (/nw-root-why) Investigate a production bug with systematic root cause analysis "Find the real cause, not just the symptom" Intermediate
15 Evidence-Based Research (/nw-research) Research a technology choice with verified sources "Make informed decisions backed by evidence" Beginner
16 Validating Your Test Suite (/nw-mutation-test) Mutation testing to find gaps in test coverage "Know if my tests actually catch bugs" Intermediate
17 Creating Quality Documentation (/nw-document) Generate DIVIO-compliant docs from existing code "Keep documentation accurate and useful" Beginner
18 Your First Outcome Register and check an outcome with the nwave-ai outcomes CLI "Measure what my work changed" Beginner

The 3.x-era first-run tutorials (Your First Delivery, Hello nWave, Your First Feature) are superseded by the v4 route above and kept as history.