maestro:blueprint

# Maestro Blueprint

Generate two artifacts for every blueprint in the maestro project:

1. **Plan spec** (`.md`) -- maestro-format plan saved to `.maestro/plans/{feature-name}.md`
2. **Visual blueprint** (`.html`) -- interactive HTML presentation saved to `~/.agent/diagrams/{feature-name}-blueprint.html`

The `.md` plan follows maestro conventions and integrates with tracks, missions, and the existing planning workflow. The `.html` is the visual version of the same content.

## Workflow

### 1. Explore (Subagents)

Before generating anything, understand the affected codebase areas. Launch parallel explore subagents.

**Maestro-specific areas to check:**
- `src/features/<name>/` -- feature-scoped code; each feature is a bounded context with its own `commands/`, `usecases/`, `domain/`, `ports/`, `adapters/`, `services.ts`, and `index.ts` public surface
- `src/infra/` -- plumbing that isn't a feature (init, doctor, status, install, update, uninstall, mission-control commands; config and git ports/adapters)
- `src/shared/` -- generic utilities with no domain knowledge (`lib/` for fs, yaml, shell, output; `domain/` for IDs, UI config; top-level `errors.ts`, `version.ts`)
- `src/tui/` -- TUI rendering if the change affects Mission Control
- `skills/built-in/` -- if the change affects built-in skills
- `.maestro/context/` -- read product.md and tech-stack.md for project context
- `.maestro/tracks/` -- check for related existing tracks
- `tests/` -- existing test patterns

**What to look for:**
- Existing implementations that can be reused
- The feature-folder layout: cross-feature imports must go through `@/features/<name>` (the feature's `index.ts`); deep paths into another feature are forbidden and enforced by `bun run check:boundaries`
- The hexagonal pattern inside each feature: port -> adapter -> usecase -> command -> test
- Conventions from AGENTS.md (types, naming, async, imports, feature-folder layout)
- Files that will need modification
- Related tracks or plans already in `.maestro/`

### 2. Synthesize and Decide

After subagents report back, synthesize findings. Determine depth level:

| Level | When | Sections |
|---|---|---|
| **Light** | 1-2 files, obvious change | Context, File Changes, Verification |
| **Standard** | Feature spanning several files | Context, Critical Files, Phases, Verification |
| **Full** | Architectural change, new command/tool, cross-cutting | All sections including Design Decisions, Risks |

If a structural fork exists (e.g., "should this be a port+adapter or a direct implementation?"), ask the user after exploration. Reference specific code you found.

### 3. Write the Plan Spec (.md)

Save to `.maestro/plans/{feature-name}.md`. Follow the maestro plan format:

```markdown
# Blueprint: Feature Name

> One-line summary.

## Context

What exists today, what's broken/missing, what the world looks like after.
Include motivation -- why this change matters for maestro.

## Critical Files

| File | Role | Change |
|------|------|--------|
| `src/features/<name>/commands/foo.command.ts` | CLI command | New |
| `src/features/<name>/usecases/foo.usecase.ts` | Business logic | New |
| `src/features/<name>/ports/foo.port.ts` | Port interface | New |
| `src/features/<name>/adapters/foo.adapter.ts` | Adapter | New |
| `src/features/<name>/services.ts` | Feature composition | Wire new adapter |
| `src/features/<name>/index.ts` | Public surface | Export new command/types |
| `src/services.ts` | Composition root | Wire feature services (if new feature) |
| `src/index.ts` | CLI root | Add command registration |

## Design Decisions

**Decision 1: Why X over Y**
- Considered: approach A, approach B
- Chose: approach A because [reason]
- Trade-off: [what we give up]

## Phases

### Phase 1: Phase Name (~duration)

**Delivers:** What this phase produces that can be verified.

#### Tasks

1. **Task 1.1: Task name**
   - Files: `src/path/file.ts`
   - Description: What to do
   - _Acceptance: what proves this works_

2. **Task 1.2: Task name**
   - Files: `src/path/file.ts`
   - Description: What to do
   - _Acceptance: criteria_
   - _Depends on: Task 1.1_

#### Test Plan
- Unit: `bun test tests/unit/foo/`
- Integration: what to test

### Phase 2: ...

## Dependencies

\`\`\`mermaid
graph TD
  T1.1 --> T1.2
  T1.2 --> T2.1
\`\`\`

## Risks

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Specific risk | High/Med/Low | High/Med/Low | What to do |

## Verification

- [ ] Build: `bun run build && ./dist/maestro --version`
- [ ] Tests: `bun test`
- [ ] TUI (if applicable): `maestro mission-control --render-check --size 120x40`
- [ ] CLI: `maestro <command-under-test>`
- [ ] Release: `bun run release:local && command -v maestro && maestro --version` (if user-facing)
```

### 4. Generate the Visual Blueprint (.html)

Read the reference template at `./templates/blueprint-full.html` before generating. Also read the CSS patterns at `./references/css-patterns.md`.

The HTML contains the same content as the `.md` plan but presented visually with:
- KPI summary cards (files, phases, LOC, risk)
- Architecture diagram (Mermaid with zoom controls)
- Phase timeline
- Collapsible per-phase details with file changes and tasks
- Dependency DAG (if full depth)
- Risk matrix table (if full depth)
- Verification checklist

For Mermaid theming and libraries, read `./references/libraries.md`.
For responsive navigation (4+ sections), read `./references/responsive-nav.md`.
For detailed guidance on each section's content, read `./references/sections-guide.md`.

Save to `~/.agent/diagrams/{feature-name}-blueprint.html`.

### 5. Style

Follow the visual-explainer quality bar:
- Distinctive Google Fonts pairing (never Inter/Roboto/Arial)
- CSS custom properties for full light/dark theme support
- Semantic color naming (`--phase-active`, `--file-add`)
- Staggered fade-in animations, `prefers-reduced-motion` respected
- Vary palette each time -- don't repeat the sam