maestronew-feature

name	maestro:new-feature
description	Create a new feature/bug track with spec and implementation plan. Interactive interview generates requirements spec, then phased TDD plan. Use when starting work on a new feature, bug fix, or chore.
argument-hint	<feature description>
stage	discovery
audience	both

New Feature -- Specification & Planning

Create a new development feature with a requirements specification and phased implementation plan. Every feature, bug fix, or chore gets its own feature entry.

Arguments

$ARGUMENTS

The feature description. Examples: "Add dark mode support", "Fix login timeout", "Refactor connection pooling"

---

Step 1: Validate Prerequisites

Inputs: Filesystem state, maestro_status output.

Actions:

1. Call maestro_status (MCP) or maestro status (CLI) to check initialization state.
2. If maestro is not initialized: "Run maestro init first." Stop.
3. Check global memory has product info (maestro memory-read --key product). If missing: "Run maestro skill maestro:setup to configure project context." Stop.

Outputs: Confirmed .maestro/ directory is initialized with global memory.

Transition: Proceed to Step 2 when initialization is confirmed.

Failure: If .maestro/ does not exist at all, stop and instruct the user to run maestro init. Do not create .maestro/ manually -- init does more than just create the directory.

---

Step 2: Parse Input

Inputs: $ARGUMENTS string.

Actions:

1. Extract feature description from $ARGUMENTS.
2. If empty, ask user for type (feature/bug/chore) and description.
3. If the description is too vague, ask for clarification before proceeding.

Outputs: A feature description string (1-3 sentences).

Transition: Proceed to Step 3 when you have a description with enough detail to classify.

Recognizing Vague Descriptions

Input	Problem	Follow-up
"fix bug"	No indication of what bug	"Which bug? What's broken, and where?"
"improvements"	No specifics	"Which part of the system? What specific improvement?"
"update the thing"	Ambiguous target	"Which module or feature? What should change about it?"
"dark mode"	Acceptable	Clear enough to proceed -- can refine in interview
"Add rate limiting to REST API"	Good	Proceed directly

Rule: If you can't classify the description as feature/bug/chore from the words alone, it's too vague. Ask once. If still vague after one follow-up, accept what you have and let the interview fill in gaps.

---

Step 3: Generate Feature Name

Inputs: Feature description.

Actions: Generate a kebab-case feature name (2-4 words, descriptive).

Outputs: Feature name string.

Examples:

• "Add dark mode support" --> dark-mode
• "Fix login timeout on slow connections" --> fix-login-timeout
• "Refactor connection pooling" --> refactor-conn-pool

Rules:

• Use the most distinctive words from the description (skip articles, prepositions)
• Bug fixes: include "fix" in the name
• Max 4 words, kebab-case
• No dates in the name

Transition: Proceed to Step 4.

---

Step 4: Duplicate Check

Inputs: Generated feature name, maestro_feature_list output.

Actions: Call maestro_feature_list (MCP) or maestro feature-list (CLI). Warn if any existing feature starts with the same prefix.

Outputs: Warning message if duplicate found, otherwise silent.

If duplicate found: Ask the user: "A feature with a similar name already exists: {existing_name}. Continue creating a new feature, or work on the existing one?"

• Continue -- Create the new feature (user confirms it's distinct work)
• Use existing -- Stop and point user to the existing feature

Transition: Proceed to Step 4.5 when duplicate check passes or user confirms continuation.

---

Step 4.5: BR Bootstrap Check

Inputs: Filesystem state, br CLI availability.

Actions: If .beads/ does not exist and br is available: br init --prefix maestro --json. Skip silently if br is not installed.

Outputs: .beads/ directory created, or nothing.

Transition: Always proceed to Step 5 (this step never blocks).

---

Step 5: Create Feature

Inputs: Feature name from Step 3.

Actions:

maestro_feature_create({ name: "<feature-name>", description: "<description>" })

Or CLI: maestro feature-create <feature-name> --description "<description>"

Outputs: Feature directory created at .maestro/features/<feature-name>/ with feature.json.

Transition: Proceed to Step 6.

---

Step 6: Auto-Infer Feature Type

Inputs: Feature description from Step 2.

Actions: Analyze description keywords to classify as feature, bug, or chore.

Outputs: Classified type, presented to user for confirmation only if ambiguous.

Inference Decision Tree

Description contains bug keywords?
  --> YES: classify as "bug"
  --> NO:
    Description contains chore keywords?
      --> YES: classify as "chore"
      --> NO:
        Description contains feature keywords?
          --> YES: classify as "feature"
          --> NO: AMBIGUOUS -- ask user

Keyword Lists

Type	Keywords (match any)
bug	fix, broken, error, crash, incorrect, regression, timeout, fail, wrong, missing, undefined, null, exception, 404, 500
chore	refactor, cleanup, clean up, migrate, upgrade, rename, reorganize, extract, move, restructure, deprecate, remove, delete, update dependency
feature	add, build, create, implement, support, introduce, enable, new, allow, provide, expose, integrate

Confidence Levels

• High confidence (auto-classify, tell user): Description matches 2+ keywords from one type and 0 from others. Example: "Fix crash on login timeout" has "fix," "crash," "timeout" -- all bug keywords. Classify as bug, inform user: "Classifying as bug based on description."
• Medium confidence (auto-classify, ask to confirm): Description matches 1 keyword from one type. Example: "Add cleanup for stale sessions" -- "add" is feature, "cleanup" is chore. Ask: "This could be a feature (adding new cleanup behavior) or a chore (cleaning up existing code). Which is it?"
• Low confidence (must ask): No keywords match, or keywords from multiple types are present equally. Ask: "Is this a feature, bug, or chore?"

Transition: Proceed to Step 7 when type is determined.

---

Step 7: Specification Interview

Inputs: Feature type from Step 6, feature description from Step 2.

Actions: Run the type-specific interview to gather requirements. See reference/interview-questions.md for all questions per type (feature/bug/chore).

Key behaviors:

1. Batch questions -- present all questions for the type in a single interaction
2. Auto-infer what you can -- scan the codebase before asking Q2 (interaction type) and Q5 (affected modules). Pre-fill obvious answers.
3. Probe vague answers once -- if an answer is one sentence or less, ask one follow-up. Accept after that.
4. Don't ask what you know -- if the project is clearly a CLI (no UI framework, no web server), don't offer "UI component" as an interaction type option.

Outputs: Complete set of interview answers covering: behavior, interaction type, constraints, edge cases, scope, and out-of-scope items.

Transition: Proceed to Step 8 when all questions are answered.

Failure: If user abandons the interview mid-way, save whatever answers you have and ask: "Want to continue later? I can save progress." Do NOT delete the feature directory.

---

Step 8: Draft Specification

Inputs: Interview answers from Step 7, spec template from reference/spec-template.md.

Actions:

1. Compose the spec from interview answers using the template structure.
2. Use the type-specific variation (bug specs have Reproduction sections, chore specs have Scope of Change sections -- see reference/spec-template.md).
3. Run the quality checklist from the template before presenting.
4. Present full draft for approval.

Outputs: Complete spec document, presented to user for approval.

Draft Quality Gates

Before presenting the spec to the user, verify these internally (do not show the checklist to the user):

• Overview states the "why" -- not just the "what"
• Every functional requirement is independently testable
• Edge cases section has at least 3 items
• Out of Scope section has at least 2 items
• Acceptance criteria are binary pass/fail
• No implementation details leaked into requirements

If any gate fails, fix the draft before presenting. Do not present a draft you know is incomplete.

Approval Loop

Present the full spec to the user. Max 3 revision rounds.

Round 1-2: Apply requested changes, re-present. Normal iteration.

Round 3 (final): If still not approved, ask: "We've been through 3 rounds. Should I apply your latest feedback and finalize, or do we need to step back and reconsider the scope?"

When to push back (politely, once):

• User adds scope that contradicts Out of Scope: "This was listed as out of scope -- should I move it in scope?"
• User removes all edge cases: "I'd recommend keeping at least the error handling cases."
• User makes acceptance criteria untestable: "How would we verify that? Can we make it a specific check?"

After pushing back once, accept the user's decision.

Outputs: Approved spec written to .maestro/features/<feature-name>/spec.md.

Transition: Proceed to Step 9 when spec is approved and written.

---

Step 9: Generate Implementation Plan

Inputs: Approved spec from Step 8, global memory context.

Actions:

1. Read context from global memory: maestro memory-read --key workflow, maestro memory-read --key tech-stack, maestro memory-read --key guidelines.
2. Scan the codebase for auto-inferable values (see reference/plan-template.md "Auto-Inference from Codebase" section): test framework, test file convention, source structure, module pattern, existing analogous features.
3. Present inferred defaults to the user: "I detected {framework} as your test framework and {dir} as your test directory. The plan will use these. Change? [yes/no]"
4. Generate the plan using reference/plan-template.md for structure and rules.
5. Apply TDD or ship-fast pattern based on workflow memory (default: TDD if not specified).
6. Present full plan for approval.

Outputs: Complete implementation plan with phases, tasks, and verification steps.

Plan Quality Gates

Before presenting the plan, verify:

• Every spec requirement maps to at least one task
• Every phase produces a testable, demonstrable increment
• No phase is just "setup" with nothing testable
• Task count is within sizing guidelines (see plan template)
• Dependencies flow forward (no circular references)
• Phase verification steps have concrete commands, not just "run tests"

Approval Loop

Same protocol as spec approval (Step 8): max 3 rounds, push back on scope creep, accept user decision after one objection.

Outputs: Approved plan written via maestro_plan_write (MCP) or maestro plan-write --feature <feature-name> (CLI).

Transition: Proceed to Step 9.5 when plan is approved and written.

---

Step 9.5: Detect Relevant Skills

Inputs: Feature description, spec content, runtime's installed skill list.

Actions: Scan the runtime's installed skill list. Record skills whose description matches this feature's domain/tech. Store names + relevance in feature.json skills array.

Outputs: List of matched skill names (may be empty).

When to populate: Only include skills whose description has a clear keyword match with the feature's tech stack or domain. "maestro:tdd" matches if the plan uses TDD pattern. "maestro:review" always matches. Don't include skills based on vague associations.

When to leave empty: If no skills match, set "skills": []. Do not force matches.

Transition: Proceed to Step 9.7.

---

Step 9.7: Plan-to-BR Sync

Inputs: Approved plan, .beads/ directory state, br CLI availability.

Actions: If .beads/ directory exists AND command -v br succeeds: run plan-to-BR sync per reference/plan-to-br-sync.md (in the maestro:implement skill). Otherwise skip entirely.

Outputs: BR epic and issues created (or nothing).

Transition: Always proceed to Step 10 (this step never blocks).

---

Step 10: Commit

Inputs: All files created in Steps 5-9.7.

Actions:

git add .maestro/features/<feature-name>
# Include beads state if BR sync was performed
[ -d ".beads" ] && git add .beads/
git commit -m "chore(maestro:new-feature): add feature <feature-name>"

Outputs: Git commit with all feature files.

Transition: Proceed to Step 11.

Failure: If git commit fails (dirty working tree, hook failure), report the error and ask the user how to proceed. Do NOT force-commit or skip hooks.

---

Step 11: Summary

Inputs: All data from prior steps.

Actions: Display feature creation summary.

Output format:

## Feature Created

**{feature description}**
- Name: `<feature-name>`
- Type: {type}
- Phases: {count}
- Tasks: {count}

**Files**:
- `.maestro/features/<feature-name>/spec.md`
- `.maestro/features/<feature-name>/plan.md`
- `.maestro/features/<feature-name>/feature.json`

**Next**: `maestro plan-approve --feature <feature-name>` then `maestro tasks-sync --feature <feature-name>`

---

Red Flags -- STOP and Fix

These indicate the spec or plan has problems. Fix before proceeding.

Red Flag	Problem	Fix
Spec has no edge cases	Requirements not thought through	Generate at least 3 from the requirements
Acceptance criteria say "works correctly"	Not testable	Rewrite as specific, verifiable checks
Plan has a "setup" phase with nothing testable	Over-scaffolding, no increment	Merge setup tasks into first real phase
Single task covers 5+ files	Task too big	Split by file group or concern
Plan has 20+ tasks	Scope too large for one feature	Split into multiple features
Spec mentions specific technology in requirements	Implementation detail leaked	Rewrite as a behavior requirement
All tasks are "implement X" with no test tasks	TDD not applied	Inject TDD sub-tasks per plan template
Phase has no completion verification	No checkpoint	Add verification meta-task
Description matches existing feature	Duplicate work	Check with user: extend existing or start new

---

Relationship to Other Commands

Recommended workflow:

• maestro init -- Initialize maestro for the project
• maestro skill maestro:setup -- Scaffold project context (run first)
• maestro skill maestro:new-feature -- You are here. Create a feature with spec and plan
• maestro_plan_approve -- Approve the plan for execution
• maestro_tasks_sync -- Generate tasks from approved plan
• maestro skill maestro:implement -- Execute the implementation
• maestro skill maestro:review -- Verify implementation correctness
• maestro_status -- Check progress across all features
• maestro skill maestro:revert -- Undo implementation if needed

A feature created here produces spec.md and plan.md that maestro:implement consumes. The spec also serves as the baseline for maestro:review to validate against. Good specs lead to good implementations -- be thorough in the interview.