// 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 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
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
Execute feature tasks following TDD workflow. Single-agent by default, --team for parallel Agent Teams, Sub Agent Parallels. Use when ready to implement a planned feature.
| name | maestro:design |
| description | 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. |
| argument-hint | <feature description> |
| stage | ["discovery","research","planning"] |
| audience | orchestrator |
Full-ceremony specification process for ambitious features. Produces the same spec.md + plan.md output as a standard feature but through deep, multi-step discovery inspired by BMAD methodology.
When to use this instead of a quick feature:
$ARGUMENTS
The feature description. Examples: "Add user authentication with OAuth and RBAC", "Build real-time collaboration engine", "Implement HIPAA-compliant patient portal"
This skill uses a step-file architecture. Each step is a self-contained file in reference/steps/. You MUST load ONE step at a time, execute it fully, then load the NEXT. Previous step files get dropped from context.
Rules:
Check maestro_status for initialized project.
--> Read and follow reference/steps/step-01-init.md
Extract description, infer type, generate kebab-case feature name.
--> Read and follow reference/steps/step-02-parse-input.md
Create feature via maestro_feature_create or maestro feature-create.
--> Read and follow reference/steps/step-03-create-dir.md
Classify project type, domain, and complexity using reference/classification-data.md.
--> Read and follow reference/steps/step-04-classification.md
Define vision, measurable success criteria, and MVP/Growth/Vision scope.
--> Read and follow reference/steps/step-05-vision.md
Map ALL user types with narrative journeys. Minimum 3 journeys. Extract capability hints.
--> Read and follow reference/steps/step-06-journeys.md
Domain-specific requirements and risk analysis. Skipped if domain=general AND complexity=low.
--> Read and follow reference/steps/step-07-domain.md
Synthesize FRs from all discovery. Grouped by capability area. Each FR testable and implementation-agnostic.
--> Read and follow reference/steps/step-08-functional.md
Performance, security, scalability, compatibility. Measurable format.
--> Read and follow reference/steps/step-09-nonfunctional.md
Compose enriched spec from all discovery. Present for approval. Save spec to feature memory.
--> Read and follow reference/steps/step-10-spec-approval.md
Scan codebase for existing patterns relevant to this feature. Feed into plan context.
--> Read and follow reference/steps/step-11-codebase-scan.md
Generate plan with FR traceability and coverage matrix. Present for approval. Write plan via maestro_plan_write.
--> Read and follow reference/steps/step-12-plan.md
Scan runtime skill list for skills matching this feature's domain/tech. Store matches in feature.json.
--> Read and follow reference/steps/step-13-skills.md
If Beads (BR) is available and initialized, sync plan into BR epics/issues. Skip if not available.
--> Read and follow reference/steps/step-14-br-sync.md
Validate FR coverage, AC coverage, dependency sanity, scope alignment. Pass/fail gate.
--> Read and follow reference/steps/step-15-readiness.md
Update feature.json, commit, display summary.
--> Read and follow reference/steps/step-16-commit.md
Design is not a goal -- it is a gate. You are done when an autonomous agent can execute the plan without asking questions.
The Handoff Test: Read every task in the plan. For each one, ask: "Could a worker agent execute this with zero clarification?" If the answer is no for any task, the design is not done.
Done criteria:
Not done criteria (keep going):
Design produces spec.md. Plan-write consumes it. The bridge between them is how design decisions become task structure.
| Design artifact | Becomes in plan |
|---|---|
| FR (functional requirement) | One or more tasks with Addresses: FR-N |
| User journey | Sequence of tasks ordered by journey flow |
| Domain constraint | Task guardrail in Must NOT do section |
| NFR (performance, security) | Verification command in task's Verify section |
| Codebase pattern (step 11) | Code snippets that follow the existing convention |
| Out-of-scope item | Explicit exclusion in task's Must NOT do |
After design completes, the approved spec feeds directly into maestro plan-write --feature <name> (CLI) or maestro_plan_write (MCP). The plan-write command expects:
## Discovery section (min 100 chars) -- summarize what design discoveredAddresses: FR-Nmaestro memory-write so plan-write can reference themOutput contract: Design produces spec.md + plan.md. The maestro:implement skill consumes both. The spec is the "what", the plan is the "how and in what order."
When the plan reaches the task-writing stage, apply these conventions to every task.
Each step is one action (2-5 minutes):
The Depends on annotation declares task execution order:
Always include Depends on for each task. Use none to enable parallel starts.
Maximize parallelism. If two tasks touch different files and have no data dependency, they should both be Depends on: none or depend only on shared infrastructure tasks.
### N. Task Name
**Depends on**: none
**Addresses**: FR-1, FR-3
**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`
**What to do**:
- Step 1: Write the failing test
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
- Step 2: Run test to verify it fails
- Run: `pytest tests/path/test.py::test_name -v`
- Expected: FAIL with "function not defined"
- Step 3: Write minimal implementation
```python
def function(input):
return expected
```
- Step 4: Run test to verify it passes
- Run: `pytest tests/path/test.py::test_name -v`
- Expected: PASS
- Step 5: Commit
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
**Must NOT do**:
- {Task guardrail -- derived from domain constraints and out-of-scope items}
**References**:
- `{file:lines}` -- {Why this reference matters}
**Verify**:
- [ ] Run: `{command}` --> {expected}
- [ ] {Additional acceptance criteria}
All verification MUST be agent-executable (no human intervention):
`bun test` --> all pass
`curl -X POST /api/x` --> 201
NOT: "User manually tests..."
NOT: "Visually confirm..."
Addresses: FR-N tracing back to the specBefore approving the spec (step 10) or plan (step 12), run this checklist mentally.
| Check | Pass | Fail |
|---|---|---|
| Every FR is testable | "System returns 401 for unauthorized requests" | "System handles auth" |
| Success criteria are measurable | "Response time < 200ms p95" | "System is fast" |
| MVP scope is ruthlessly small | 3-8 FRs for MVP | 15+ FRs all marked MVP |
| Out of scope is explicit | "No admin dashboard in MVP" | Silence on boundaries |
| Edge cases derived from journeys | Error paths from step 6 journey mapping | "Handle errors appropriately" |
| Domain constraints are specific | "PHI must be encrypted at rest (AES-256)" | "Follow HIPAA" |
| Check | Pass | Fail |
|---|---|---|
| Coverage matrix has 0 orphans | Every FR mapped to a task | FR-7 shows -- |
| Tasks are self-contained | Worker can execute without asking questions | "Implement the auth layer" |
| Dependencies are minimal | Max 2-3 deps per task | Task 8 depends on 1,2,3,4,5 |
| Verification is executable | bun test -- auth --> all pass | "Check it works" |
| No implicit ordering | Explicit Depends on for every task | "Do this after the DB task" |
| Phase boundaries are meaningful | Each phase produces a testable increment | Phases split arbitrarily |
Design invites over-engineering. Recognize these patterns and cut them.
| Trap | Signal | Fix |
|---|---|---|
| Abstraction astronautics | "Let's build a plugin system so we can..." | Build the concrete thing. Abstract when the second use case appears. |
| Premature generalization | "This should work for any provider, not just Stripe" | Build for Stripe. Add the interface when provider #2 arrives. |
| Spec-driven scope creep | "While we're at it, we should also..." | Check the MVP tier. If it's not MVP, it goes in Growth. |
| Architecture tourism | "We should use event sourcing / CQRS / microservices" | Does the simplest architecture fail? If not, use the simplest architecture. |
| Defensive over-specification | 25+ FRs for a CRUD feature | If classification says "low complexity", the spec should be short. Match depth to complexity. |
| Gold-plated NFRs | "99.99% uptime" for an internal tool | Match NFRs to actual user expectations. Internal tools do not need carrier-grade SLAs. |
The test: For every design decision, ask: "What is the simplest thing that could work?" If your design is more complex than that, you need a stated reason why.
After saving the plan, the design phase is complete. The handoff artifact is:
.maestro/features/<feature-name>/
spec.md -- What to build (from step 10)
plan.md -- How to build it, in what order (from step 12)
These two files are the complete handoff. The maestro:implement skill consumes them.
Transition options:
maestro plan-write (recommended for hive workflows) -- Run maestro plan-write --feature <name> or maestro_plan_write with the plan content. This enters the standard hive workflow: plan-approve, tasks-sync, worktree-start.
maestro:implement (direct execution) -- Open new session with maestro:implement. The skill reads spec.md and plan.md, then executes tasks sequentially with checkpoints.
Subagent-driven (this session) -- Stay in this session. Dispatch a fresh subagent per task. Review between tasks. Fast iteration but no worktree isolation.
Before handing off, verify:
maestro memory-write or maestro_memory_writemaestro init -- Initialize maestro for the project (run first)maestro_feature_create -- Create a feature to work onmaestro:design -- You are here. Deep discovery for ambitious featuresmaestro_plan_write -- Write the plan from design outputmaestro_plan_approve -- Approve the plan for executionmaestro_tasks_sync -- Generate tasks from approved planmaestro:implement -- Execute the implementation planmaestro:review -- Verify implementation against specmaestro_status -- Check progress across all featuresmaestro_feature_complete -- Mark feature doneA feature created here produces spec.md and plan.md that maestro:implement or maestro plan-write consumes. The enriched spec serves as the baseline for maestro:review. Deep specs lead to better implementations -- invest in the discovery.