Tutorial: Your First Delivery

Setup

Run from a directory where you want the tutorial project created (e.g. ~/projects):

curl -fsSL https://raw.githubusercontent.com/nWave-ai/nWave/main/docs/guides/tutorial-first-delivery/setup.py | python3

Prefer to read first? See manual-setup.md.

After setup you should have

• A tutorial-ascii-art/ directory containing src/ascii_art/__init__.py, tests/test_ascii_art.py, tests/fixtures/diagonal.ppm, and pyproject.toml
• A .venv/ virtual environment with pytest installed
• Three failing acceptance tests in tests/test_ascii_art.py (run pytest tests/ -v to confirm)

What You'll Build

An image-to-ASCII-art converter. Give it any photo, get ASCII art in your terminal.

Before — Einstein's 1947 portrait (public domain, photo by Oren Jack Turner):

After — the same image converted to ASCII with image_to_ascii('einstein.ppm', width=72):

::::::::::........::......::.:::::::::.........................
::::::::::::......:--:-==+=--::::::::..........................
:::::::::::::..::::-+++*++*##**==--===:.:::....................
::::::::-:::::::::+*++**##%%########***=-:...::::..............
::::::----::::--=++*##%#########%%%#######++==------............
::::::---:==-++++*#%%%%%%%%%%%%%%%%%%%%%##########*+=..........
::--------+++***####%%%%%%####%%#%%#%%%%####%%%%%%#*++:::......
--------===+++***#%%##%%%###########%%#####%%##%%#####-:::....
-------====+##*#######################################+--:....
---------+==+**##########*************############**#####*.:..
-------=+=+*######*******==++++*****###############***#**##-...
======+==********+==+***+=-==+++****##############****###**#+-:
========+++++*******#**++-:--====++**#############*****###***=-:
========+++****###++**++=--:--==+++**##############***********+-
=====+++++++*****+===+*+=--::---====+*#############***###*****+-
====+*+***##*+*++*===+*++--:::--:.:::-=**####**==+++**##*******+
++++++++*#****+===---+*+=--:::--=::::-.:-=***=-....-=**##***+*+-
++++**********+++----=*+---::::-:..:-:-:::*#+=::-=+=++****+#*++=
+++++++**##****-.:::--=-:::-===-::--++=-::+##***+=+=-*#*+++*#++:
++=++==++*+***+-.:.........-========++=-::-*###+=+****+++++***=-
====+==+=+++**+=-...:......:-=++++++*+--::-+#*##******=++=++*+==
===+++==*+**+*==-...........-==+++++++:  .-+*#**#*****=====++*+-
=====++++*++++=:--.::.......:--==+++=..:...-+**=*#****==-=+++=+:
==========+=+*+=-:.........:-:.:=++=---:.. ..+***=***=:-+=++=+*:
=====++++++++++=+=:.........-:.:---=------=====****+++::--++-:-
===+++++++++++++++:  ...........::--::-:.-:--:-=++**+:.:........
+++++++++********=..  ..............      ....-::=++-.........
+++++++++++++**--:         .... .....:::---===++=--.........
+++++++++===**-...                ..::-==+++***+-++**+:.......
+++======-=++-:...                  ...::--:-=---=+++=*++++=-.
+==---:-+++=-:=:                          ....:-----=+=--===+++
=--:-+**+**+-. .::.. .                   .:-: .:-=----==-=+--==

You define what "done" looks like. nWave writes the code to get there.

Step 1 of 5: Inspect the starter project (~2 minutes)

After running setup, cd tutorial-ascii-art and activate the virtualenv:

cd tutorial-ascii-art
source .venv/bin/activate

Windows users: Replace source .venv/bin/activate with .venv\Scripts\activate.

What's inside:

tutorial-ascii-art/
  src/ascii_art/__init__.py    # Empty — this is what nWave will implement
  tests/test_ascii_art.py      # 3 acceptance tests (already written for you)
  tests/fixtures/diagonal.ppm  # 4x4 test image (white diagonal on black)
  pyproject.toml

Run the tests to confirm they fail:

pytest tests/ -v

FAILED test_ascii_art.py::test_converts_image_to_ascii_with_correct_width
FAILED test_ascii_art.py::test_output_uses_only_density_characters
FAILED test_ascii_art.py::test_bright_pixels_produce_dense_characters

3 failed

That's your first result — red tests that define the feature. Three behaviors, fully specified:

1. Correct width: Convert with width=20, every line is exactly 20 characters
2. Valid characters: Output uses only the density ramp " .:-=+*#%@"
3. Brightness mapping: White pixels → dense chars (@, #), dark → sparse ( , .)

You don't need to tell nWave how to implement it — just what the result must look like.

Next: you'll hand these red tests to nWave and watch it turn them green.

Step 2 of 5: Let nWave Deliver (~8 minutes)

AI output varies between runs. Your code will differ from the examples below. That is normal. We define success by what the code does (tests pass), not what the agent says.

Open Claude Code and start the delivery:

claude

Then type this Claude Code command (not a terminal command):

/nw-deliver "Image-to-ASCII art converter using PPM format"

● nw-solution-architect(Fill roadmap skeleton)
  ⎿  Done (3 tool uses · 9.8k tokens · 25s)

● nw-software-crafter(Execute step 01-01)
  ⎿  Done (10 tool uses · 17.0k tokens · 1m 14s)

● nw-software-crafter-reviewer(Adversarial review)
  ⎿  Done (8 tool uses · 13.6k tokens · 42s)

⎿  PreToolUse:Task hook error     ← DES validation checkpoint (normal)
⎿  DES_MARKERS_MISSING: ...       ← Occasionally appears on first try, auto-retries

Step 3 of 5: See the Result (~1 minute)

When delivery completes, you'll see a summary table. Run your tests:

pytest tests/ -v

Expected:

test_ascii_art.py::test_converts_image_to_ascii_with_correct_width PASSED
test_ascii_art.py::test_output_uses_only_density_characters PASSED
test_ascii_art.py::test_bright_pixels_produce_dense_characters PASSED

3 passed

All green. Now try the converter on the test fixture:

PYTHONPATH=src python3 -c "
from ascii_art import image_to_ascii
print(image_to_ascii('tests/fixtures/diagonal.ppm', width=40))
"

You should see a small ASCII diagonal — bright characters along the diagonal, dark everywhere else.

If you see ModuleNotFoundError: Make sure your venv is activated and you included PYTHONPATH=src.

Next: you'll try a more interesting image and explore the output.

Step 4 of 5: Explore (~2 minutes)

Create a gradient image and convert it:

PYTHONPATH=src python3 -c "
width, height = 32, 16
with open('gradient.ppm', 'w') as f:
    f.write(f'P3\n{width} {height}\n255\n')
    for y in range(height):
        row = []
        for x in range(width):
            v = int(255 * x / (width - 1))
            row.append(f'{v} {v} {v}')
        f.write('  '.join(row) + '\n')

from ascii_art import image_to_ascii
print(image_to_ascii('gradient.ppm', width=60))
"

You should see a smooth ramp from spaces on the left (dark) to @ signs on the right (bright):

 .:-=+*#%@  .:-=+*#%@  .:-=+*#%@  .:-=+*#%@  .:-=+*#%@  .:-=

Look at the git log to see how nWave built the code:

git log --oneline

abc1234 green(ascii-art): implement brightness mapping
def5678 green(ascii-art): implement character validation
ghi9012 green(ascii-art): implement width conversion

Every commit maps to a TDD step. You can trace exactly how the code was built.

Next: a recap of what nWave did for you.

Step 5 of 5: What Just Happened (~1 minute)

You started with 3 failing tests and an empty __init__.py. nWave delivered:

• A roadmap breaking the feature into implementation steps
• Production code built through strict TDD (every test was red before green)
• Refactored code checked against progressive quality levels
• Peer review by an independent reviewer agent
• Mutation testing validating your test suite catches real bugs
• Atomic commits at every green step — traceable via git log --oneline

Next Steps

This tutorial used /nw-deliver directly — you wrote the acceptance tests by hand. The full nWave workflow has specialized agents for every stage:

Each guide is ~5 minutes and builds on the previous one. By the end, you'll know the complete workflow.

Last Updated: 2026-02-17