nwave-ai/nw-roadmap
Creates a phased roadmap.json for a feature goal with acceptance criteria and TDD steps. Use when planning implementation steps before execution.
npx skills add https://github.com/nWave-ai/nWave --skill nw-roadmapWave: CROSS_WAVE
Agent: Architect (nw-solution-architect) or domain-appropriate agent
Dispatches expert agent to fill a pre-scaffolded YAML roadmap skeleton. CLI tools handle structure; agent handles content.
Output: docs/feature/{feature-id}/deliver/roadmap.json
/nw-roadmap @nw-solution-architect "Migrate monolith to microservices"
/nw-roadmap @nw-software-crafter "Replace legacy authentication system"
/nw-roadmap @nw-product-owner "Implement multi-tenant support"
You MUST execute these steps in order. Do NOT skip any.
des.cli.roadmap init via Bash BEFORE invoking agent. Gate: CLI exits 0; stop and report error on non-zero exit.des-roadmap init \
--project-id {feature-id} \
--goal "{goal-description}" \
--output docs/feature/{feature-id}/deliver/roadmap.json
For complex projects add: --phases 3 --steps "01:3,02:2,03:1"
Do NOT write the file manually.
@{agent-name}
Fill in the roadmap skeleton at docs/feature/{feature-id}/deliver/roadmap.json.
Replace every TODO with real content. Do NOT change the YAML structure
(phases, steps, keys). Fill in: names, descriptions, acceptance criteria,
time estimates, dependencies, and implementation_scope paths.
Goal: {goal-description}
# Test paradigm mandate (STANDING 2026-05-05) — apply per test level
GUARD — emit by deliverable_type (ADR-PST-003 / OPEN-5-A): the mandate
block below applies ONLY when `deliverable_type == application` (or when
deliverable_type is unset — application is the default). For a plugin/skill
deliverable, do NOT emit the mandate; instead include this one-line directive
in each step's `implementation_notes`:
STRUCTURAL VERIFICATION (mandatory, plugin/skill): This step ships prompt
text / config / docs, not application code, so the Hypothesis + state-delta
unit mandate does not apply. Verify the deliverable structurally — a golden
assertion (skill-lint) over the changed markdown/config asserting the
required block is present and correctly shaped — gated at CI + pre-push.
When `deliverable_type == application` (or unset), for EVERY step's
`implementation_notes`, include this directive verbatim unless the step is
documented as exempt:
TEST PARADIGM (mandatory): Unit tests for this step MUST be written as
property-based tests using Hypothesis @given strategies + state-delta
matchers (assert_state_delta over a declared universe with strict=True).
Single-example unit tests are FALLBACK only — document why in a
`# bypass:` comment if used. Acceptance scenarios MUST be framed as
Property: blocks (quantified preconditions + invariant outcomes) where
the contract supports it; classic Scenario: is fallback. Integration
and E2E tests REMAIN single-example — they verify wiring, not
invariants. Universe declaration is mandatory even when only one slot
is checked: the unchanged() predicate covers the rest.
STAGE CONTEXT (cascade): NEW code = Stage 0 (paradigm-from-day-zero,
no debt accumulates). Bug-prone legacy code = Stage 1 first (state-
delta migration captures hidden mutations, 33-75% yield), THEN Stage 2
PBT amplification (low yield by design — surface is debt-paid). Don't
expect high hit rate on Stage-1-completed surfaces; that's healthy.
See nw-tdd-methodology::Paradigm Mandate for the full debt-payoff
framing.
When a step's contract genuinely cannot be expressed as a property
(e.g., golden-file diff, exact error string, single-shot UI flow),
include in `implementation_notes`:
EXEMPT FROM PARADIGM: <one-sentence reason>. Compensate with
property-based test at <unit|integration> level on adjacent slot.
Context to pass (if available): measurement baseline|mikado-graph.md|existing docs.
des-roadmap validate via Bash. Gate: exit 0 = success; exit 1 = print errors and stop; exit 2 = usage error, stop.des-roadmap validate docs/feature/{feature-id}/deliver/roadmap.json
Keep agent prompt minimal. Agent knows roadmap structure and planning methodology.
Pass: skeleton file path + goal description + measurement context (if available).
Do not pass: YAML templates|phase guidance|step decomposition rules.
For performance roadmaps, include measurement context inline so agent can validate targets against baselines.
des.cli.roadmap init executed via Bash (exit 0)des.cli.roadmap validate executed via Bash (exit 0)/nw-roadmap @nw-solution-architect "Migrate authentication to OAuth2"
Derives feature-id="migrate-auth-to-oauth2", scaffolds skeleton, invokes agent to fill TODOs, validates. Produces docs/feature/migrate-auth-to-oauth2/deliver/roadmap.json.
/nw-roadmap @nw-solution-architect "Optimize test suite execution"
Passes measurement data inline. Agent fills skeleton, validates targets against baseline, prioritizes largest bottleneck first.
/nw-roadmap @nw-software-crafter "Extract payment module from monolith"
Agent fills skeleton with methodology: mikado, references mikado-graph.md, maps leaf nodes to steps.
/nw-roadmap @agent "goal" # 1. Plan (init -> agent fills -> validate)
/nw-execute @agent "feature-id" "01-01" # 2. Execute steps
/nw-finalize @agent "feature-id" # 3. Finalize
Take nwave-ai/nw-roadmap from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.