Agent Skills: New Feature -- Specification & Planning

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 --json output.

Actions:

1. Call maestro status --json (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>" --json

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 task-sync -- Generate tasks from approved plan
• maestro skill maestro:implement -- Execute the implementation
• maestro skill maestro:review -- Verify implementation correctness
• maestro status --json -- 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.