nWave-ai 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:
- Continue that project — switch to
/nw-continue - Start fresh with different name — ask for distinguishing name
- 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".
Source: nWave-ai/nWave → nWave/skills/nw-new/SKILL.md