Design -- Deep Discovery & Specification

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:

• Multi-component systems with many moving parts
• Regulated domains (healthcare, fintech, govtech)
• Unclear or complex requirements that need thorough discovery
• Features where getting the spec wrong is expensive

Arguments

$ARGUMENTS

The feature description. Examples: "Add user authentication with OAuth and RBAC", "Build real-time collaboration engine", "Implement HIPAA-compliant patient portal"

Step Sequence

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:

• NEVER load multiple step files simultaneously
• ALWAYS read the entire step file before executing
• NEVER skip steps or reorder the sequence
• Steps 4-9 include an A/P/C menu -- the user MUST select [C] before you proceed

Step 1: Validate Prerequisites

Check maestro status --json for initialized project. --> Read and follow reference/steps/step-01-init.md

Step 2: Parse Input & Generate Feature Name

Extract description, infer type, generate kebab-case feature name. --> Read and follow reference/steps/step-02-parse-input.md

Step 3: Create Feature

Create feature via maestro feature-create or maestro feature-create. --> Read and follow reference/steps/step-03-create-dir.md

Step 4: Project Classification

Classify project type, domain, and complexity using reference/classification-data.md. --> Read and follow reference/steps/step-04-classification.md

Step 5: Vision & Success Criteria

Define vision, measurable success criteria, and MVP/Growth/Vision scope. --> Read and follow reference/steps/step-05-vision.md

Step 6: User Journey Mapping

Map ALL user types with narrative journeys. Minimum 3 journeys. Extract capability hints. --> Read and follow reference/steps/step-06-journeys.md

Step 7: Domain & Scoping

Domain-specific requirements and risk analysis. Skipped if domain=general AND complexity=low. --> Read and follow reference/steps/step-07-domain.md

Step 8: Functional Requirements Synthesis

Synthesize FRs from all discovery. Grouped by capability area. Each FR testable and implementation-agnostic. --> Read and follow reference/steps/step-08-functional.md

Step 9: Non-Functional Requirements

Performance, security, scalability, compatibility. Measurable format. --> Read and follow reference/steps/step-09-nonfunctional.md

Step 10: Spec Draft & Approval

Compose enriched spec from all discovery. Present for approval. Save spec to feature memory. --> Read and follow reference/steps/step-10-spec-approval.md

Step 11: Codebase Pattern Scan

Scan codebase for existing patterns relevant to this feature. Feed into plan context. --> Read and follow reference/steps/step-11-codebase-scan.md

Step 12: Implementation Plan with Traceability

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

Step 13: Detect Relevant Skills

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

Step 14: Plan-to-BR Sync

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

Step 15: Pre-Implementation Readiness Gate

Validate FR coverage, AC coverage, dependency sanity, scope alignment. Pass/fail gate. --> Read and follow reference/steps/step-15-readiness.md

Step 16: Feature Registration, Commit & Summary

Update feature.json, commit, display summary. --> Read and follow reference/steps/step-16-commit.md

When Design Is "Done Enough"

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:

• Every task has exact file paths, complete code snippets, and executable verification commands
• No task says "add validation" or "implement error handling" -- it says what, where, and how
• Dependencies form a DAG (no cycles, infrastructure before consumers)
• Coverage matrix shows 0 orphaned FRs
• Readiness gate passes (step 15)
• Each design decision has a stated reason (not just a choice)

Not done criteria (keep going):

• A task requires domain knowledge that is not in the spec or context files
• Verification steps say "manually check" or "visually confirm"
• Two tasks modify the same file with no dependency between them
• A task's "What to do" section requires inference about the codebase

Design-to-Plan Bridge

Design produces spec.md. Plan-write consumes it. The bridge between them is how design decisions become task structure.

How Design Decisions Map to Tasks

The plan-write Connection

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:

1. A ## Discovery section (min 100 chars) -- summarize what design discovered
2. FR references -- plan tasks trace back to spec FRs via Addresses: FR-N
3. Non-Goals / Ghost Diffs -- derived from the spec's Out of Scope section
4. Context files -- design should save key findings via maestro memory-write so plan-write can reference them

Output 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."

Task Structure & Handoff

When the plan reaches the task-writing stage, apply these conventions to every task.

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

Task Dependencies

The Depends on annotation declares task execution order:

• Depends on: none -- No dependencies; can run immediately or in parallel
• Depends on: 1 -- Depends on task 1
• Depends on: 1, 3 -- Depends on tasks 1 and 3

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.

Task Template

### 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..."

Remember

• Exact file paths always
• Complete code in plan (not "add validation")
• Exact commands with expected output
• Reference relevant skills with @ syntax
• DRY, YAGNI, TDD, frequent commits
• All acceptance criteria must be agent-executable (zero human intervention)
• Every task must have Addresses: FR-N tracing back to the spec

Design Review Checklist

Before approving the spec (step 10) or plan (step 12), run this checklist mentally.

Spec Review

Plan Review

Over-Engineering Traps

Design invites over-engineering. Recognize these patterns and cut them.

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.

Execution Handoff

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:

1. 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.

2. maestro:implement (direct execution) -- Open new session with maestro:implement. The skill reads spec.md and plan.md, then executes tasks sequentially with checkpoints.

3. 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:

• Readiness gate passed (step 15)
• All context files saved via maestro memory-write or maestro memory-write
• Feature metadata committed (step 16)

Relationship to Other Commands

• maestro init -- Initialize maestro for the project (run first)
• maestro feature-create -- Create a feature to work on
• maestro:design -- You are here. Deep discovery for ambitious features
• maestro plan-write -- Write the plan from design output
• maestro plan-approve -- Approve the plan for execution
• maestro task-sync -- Generate tasks from approved plan
• maestro:implement -- Execute the implementation plan
• maestro:review -- Verify implementation against spec
• maestro status --json -- Check progress across all features
• maestro feature-complete -- Mark feature done

A 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.