nwave-ai/nw-new

NW-NEW: Start a New Feature

Wave: CROSS_WAVE (entry point) Agent: Main Instance (self — wizard) Command: /nw-new

Overview

Conversational wizard that asks the user to describe their feature|classifies it|recommends a starting wave|launches it. Eliminates need to understand the 6-wave pipeline before using nWave.

You (the main Claude instance) run this wizard directly. No subagent delegation.

Behavior Flow

Step 1: Feature Description Intake

Ask the user to describe what they want to build. If provided as argument, use that.

If vague (fewer than 3 meaningful words or unclassifiable):

• Ask: What system is being changed?
• Ask: What problem are you solving?
• Ask: Who benefits from this change?
• Provide example: "Add rate limiting to prevent API abuse"

Do NOT proceed until you have a clear, actionable description.

Step 2: Feature ID Derivation

Derive feature ID per rules in ~/.claude/nWave/skills/common/wizard-shared-rules.md (section: Feature ID Derivation).

Examples: "Add rate limiting to the API gateway" -> rate-limiting-api-gateway | "OAuth2 upgrade" -> oauth2-upgrade | "Implement a real-time notification system with WebSocket support for mobile and desktop clients" -> real-time-notification-system-websocket

Show derived ID via AskUserQuestion. Allow override with custom value.

Step 3: Name Conflict Check

Check if docs/feature/{feature-id}/ exists. If so, offer via AskUserQuestion:

1. Continue that project — switch to /nw-continue
2. Start fresh with different name — ask for distinguishing name
3. Archive and restart — move to docs/feature/{feature-id}-archived-{date}/

Step 4: Clarifying Questions

Use AskUserQuestion:

Q1: New or existing behavior?

• New functionality that doesn't exist yet
• Changing/improving existing functionality
• Fixing a bug or regression

Q2: Requirements readiness?

• Clear requirements in my head but nothing written
• Rough idea, need to explore further
• Haven't validated whether problem is worth solving

Step 5: Feature Classification

Based on description and answers, classify:

• User-facing — UI/UX visible to end users
• Backend — APIs, services, data processing
• Infrastructure — DevOps, CI/CD, tooling
• Cross-cutting — Spans multiple layers (auth, logging, etc.)

Show classification for user confirmation.

Step 6: Greenfield vs Brownfield Detection

Scan filesystem:

• Check if src/ or equivalent has code
• Check if docs/feature/ has prior feature directories
• Check for existing test directories

No source code and no prior features -> greenfield | Otherwise -> brownfield

Step 7: Wave Recommendation

Decision tree:

IF "fixing a bug":
    -> /nw-root-why ("Investigate the root cause first")
IF "haven't validated the problem":
    -> /nw-discover ("Validate the problem space before building")
IF "rough idea, need to explore":
    -> /nw-discuss ("Define requirements and acceptance criteria")
IF "clear requirements, nothing written":
    -> /nw-discuss ("Formalize requirements into user stories")
IF existing DISCUSS artifacts found:
    -> /nw-design ("Requirements exist, design the architecture")
IF existing DESIGN artifacts found:
    -> /nw-distill ("Architecture exists, create acceptance tests")
IF all prior waves complete:
    -> /nw-deliver ("Ready for implementation")
DEFAULT:
    -> /nw-discuss ("Start by defining what to build")

Show recommendation with rationale via AskUserQuestion: recommended wave command|why this wave (one sentence)|what it produces.

Step 8: Launch

After user confirms, create project directory:

mkdir -p docs/feature/{feature-id}

Invoke recommended wave command by reading its task file and following instructions, passing feature ID as argument.

Error Handling

| Error | Response | |-------|----------| | Vague description (< 3 meaningful words) | Ask follow-up questions with example | | Name conflict with existing project | Offer continue/rename/archive options | | User cannot classify feature type | Default to "cross-cutting", note uncertainty | | No clear wave recommendation | Default to DISCUSS with explanation |

Success Criteria

• [ ] User described feature in plain language
• [ ] Project ID derived and confirmed by user
• [ ] No name conflicts (or resolved)
• [ ] Feature classified by type
• [ ] Starting wave recommended with rationale
• [ ] User confirmed recommendation
• [ ] Wave command launched with correct feature ID

Examples

Example 1: Greenfield backend feature

/nw-new "Add rate limiting to the API gateway"

Derives rate-limiting-api-gateway, detects no prior artifacts (greenfield), asks clarifying questions. User says "new functionality, clear requirements." Recommends DISCUSS, launches /nw-discuss "rate-limiting-api-gateway".

Example 2: Bug fix

/nw-new "Fix authentication timeout errors"

Detects "fix" in description. User confirms bug. Recommends /nw-root-why "authentication timeout errors".

Example 3: Unclear problem

/nw-new "Build a customer feedback system"

User says they haven't validated whether customers want this. Recommends DISCOVER, launches /nw-discover "customer-feedback-system".