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"

.