菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
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-track |
| 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 | <track description> |
Create a new development track with a requirements specification and phased implementation plan. Every feature, bug fix, or chore gets its own track.
$ARGUMENTS
The track description. Examples: "Add dark mode support", "Fix login timeout", "Refactor connection pooling"
Inputs: Filesystem state.
Actions:
.maestro/context/product.md exists. If not: "Run /maestro:setup first." Stop..maestro/tracks.md exists. If missing, create it with this header:# Tracks Registry
Active and completed development tracks.
Outputs: Confirmed .maestro/ directory is initialized.
Transition: Proceed to Step 2 when both files exist.
Failure: If .maestro/ does not exist at all, stop and instruct the user to run /maestro:setup. Do not create .maestro/ manually -- setup does more than just create the directory.
Inputs: $ARGUMENTS string.
Actions:
$ARGUMENTS.Outputs: A track 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: Track description.
Actions: Generate ID in format {shortname}_{YYYYMMDD} (2-4 words, snake_case + date).
Outputs: Track ID string.
Examples:
dark_mode_20260225login_timeout_fix_20260225refactor_conn_pool_20260225Rules:
Transition: Proceed to Step 4.
Inputs: Generated track ID, existing .maestro/tracks/ directories.
Actions: Scan .maestro/tracks/* directories. Warn if any starts with the same short name prefix (the part before the date).
Outputs: Warning message if duplicate found, otherwise silent.
If duplicate found: Ask the user: "A track with a similar name already exists: {existing_id}. Continue creating a new track, 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: Track ID from Step 3.
Actions:
mkdir -p .maestro/tracks/{track_id}
Outputs: Empty track directory created.
Transition: Proceed to Step 6.
Inputs: Track 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: Track type from Step 6, track 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 track 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/tracks/{track_id}/spec.md.
Transition: Proceed to Step 9 when spec is approved and written.
Inputs: Approved spec from Step 8, project context files.
Actions:
.maestro/context/workflow.md, tech-stack.md, guidelines.md.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.workflow.md (default: TDD if not specified).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 to .maestro/tracks/{track_id}/plan.md.
Transition: Proceed to Step 9.5 when plan is approved and written.
Inputs: Track description, spec content, runtime's installed skill list.
Actions: Scan the runtime's installed skill list. Record skills whose description matches this track's domain/tech. Store names + relevance in metadata.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 track'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-12 (this step never blocks).
Inputs: All data from prior steps.
Actions: Write metadata.json, index.md, update tracks.md. See reference/metadata-and-registry.md for all schemas, templates, commit message, and summary format.
Outputs: Three files written/updated:
.maestro/tracks/{track_id}/metadata.json.maestro/tracks/{track_id}/index.md.maestro/tracks.md (appended)Transition: Proceed to Step 13.
Inputs: All files created in Steps 5-12.
Actions:
git add .maestro/tracks/{track_id} .maestro/tracks.md
# Include beads state if BR sync was performed
[ -d ".beads" ] && git add .beads/
git commit -m "chore(maestro:new-track): add track {track_id}"
Outputs: Git commit with all track files.
Transition: Proceed to Step 14.
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 metadata from prior steps.
Actions: Display track creation summary.
Output format:
## Track Created
**{track description}**
- ID: `{track_id}`
- Type: {type}
- Phases: {count}
- Tasks: {count}
**Files**:
- `.maestro/tracks/{track_id}/spec.md`
- `.maestro/tracks/{track_id}/plan.md`
- `.maestro/tracks/{track_id}/metadata.json`
- `.maestro/tracks/{track_id}/index.md`
**Next**: `/maestro:implement {track_id}`
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 track | Split into multiple tracks |
| 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 track | Duplicate work | Check with user: extend existing or start new |
Recommended workflow:
/maestro:setup -- Scaffold project context (run first)/maestro:new-track -- You are here. Create a feature/bug track with spec and plan/maestro:implement -- Execute the implementation/maestro:review -- Verify implementation correctness/maestro:status -- Check progress across all tracks/maestro:revert -- Undo implementation if needed/maestro:note -- Capture decisions and context to persistent notepadA track 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.