// 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.
Use when bootstrapping, updating, or reviewing AGENTS.md — teaches what makes effective agent memory, how to structure sections, signal vs noise filtering, and when to prune stale entries
Use before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
Deep discovery and specification for ambitious features. Full BMAD-inspired interview with classification, vision, journeys, domain analysis, and FR synthesis. Same output contract (spec.md + plan.md) as a standard feature but far richer. Use for multi-component systems, regulated domains, or unclear requirements.
Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Use when working with Docker containers — debugging container failures, writing Dockerfiles, docker-compose for integration tests, image optimization, or deploying containerized applications
| 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 |
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
The feature description. Examples: "Add dark mode support", "Fix login timeout", "Refactor connection pooling"
Inputs: Filesystem state, maestro_status output.
Actions:
maestro_status (MCP) or maestro status (CLI) to check initialization state.maestro init first." Stop.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.
Inputs: $ARGUMENTS string.
Actions:
$ARGUMENTS.Outputs: A feature description string (1-3 sentences).
Transition: Proceed to Step 3 when you have a description with enough detail to classify.
| 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.
Inputs: Feature description.
Actions: Generate a kebab-case feature name (2-4 words, descriptive).
Outputs: Feature name string.
Examples:
dark-modefix-login-timeoutrefactor-conn-poolRules:
Transition: Proceed to Step 4.
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?"
Transition: Proceed to Step 4.5 when duplicate check passes or user confirms continuation.
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).
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.
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.
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
| 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 |
Transition: Proceed to Step 7 when type is determined.
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:
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.
Inputs: Interview answers from Step 7, spec template from reference/spec-template.md.
Actions:
reference/spec-template.md).Outputs: Complete spec document, presented to user for approval.
Before presenting the spec to the user, verify these internally (do not show the checklist to the user):
If any gate fails, fix the draft before presenting. Do not present a draft you know is incomplete.
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):
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.
Inputs: Approved spec from Step 8, global memory context.
Actions:
maestro memory-read --key workflow, maestro memory-read --key tech-stack, maestro memory-read --key guidelines.reference/plan-template.md "Auto-Inference from Codebase" section): test framework, test file convention, source structure, module pattern, existing analogous features.reference/plan-template.md for structure and rules.Outputs: Complete implementation plan with phases, tasks, and verification steps.
Before presenting the plan, verify:
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.
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.
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).
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.
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>`
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 |
Recommended workflow:
maestro init -- Initialize maestro for the projectmaestro skill maestro:setup -- Scaffold project context (run first)maestro skill maestro:new-feature -- You are here. Create a feature with spec and planmaestro_plan_approve -- Approve the plan for executionmaestro_tasks_sync -- Generate tasks from approved planmaestro skill maestro:implement -- Execute the implementationmaestro skill maestro:review -- Verify implementation correctnessmaestro_status -- Check progress across all featuresmaestro skill maestro:revert -- Undo implementation if neededA 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.