maestro-brainstorm

<purpose>
Multi-role brainstorming with cross-role conflict resolution. Auto mode: guidance-specification → parallel role analysis → cross-role review → resolution writeback. Single role mode: individual role analysis for existing session.

Pipeline: grill (optional) → **brainstorm** → roadmap / analyze / blueprint.
</purpose>

<required_reading>
@~/.maestro/workflows/brainstorm.md
</required_reading>

<deferred_reading>
- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (in cross-role review)
</deferred_reading>

<context>
$ARGUMENTS -- topic text for auto mode, or role name for single role mode.

**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
**Produced files**: `guidance-specification.md`, `design-research.md` (optional), `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md` (per selected role).

**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert

**Flags**:

| Flag | Effect | Default |
|------|--------|---------|
| `--yes` / `-y` | Auto mode — skip interactive questions, use defaults | false |
| `--count N` | Number of roles to select (max 9) | 3 |
| `--session ID` | Use existing session | — |
| `--update` | Update existing analysis (single role) | false |
| `--skip-questions` | Skip context gathering questions | false |
| `--include-questions` | Force context gathering even if analysis exists | false |
| `--style-skill PKG` | Style package for ui-designer role | — |

### Pre-load specs
1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
2. Optional — proceed without if unavailable.

### Role Knowledge
1. `maestro search --category arch` → identify relevant entries
2. `maestro load --type knowhow --id <id1> [id2...]` → load selected documents
</context>

<interview_protocol>
Follows @~/.maestro/workflows/interview-mechanics.md standard.

**Interaction mode**: convergent menu-driven
**Decision tree** (flexible order — user may jump between branches): mode (auto / single-role / review-only) → role selection and --count → --from upstream source (grill:ID, blueprint:ID, @file, path) → whether to enable design-research and DESIGN.md sub-pipeline
**Scope guard**: only brainstorm decisions; do not pre-resolve roadmap/plan choices
**Writeback target**: guidance-specification.md §11 (create section if absent)
**Additional skip conditions**: --skip-questions, --session (existing session)
**Exit condition**: on consensus or explicit user signal → finalize session metadata
</interview_protocol>

<execution>
Follow '~/.maestro/workflows/brainstorm.md' completely.

### Phase Gates (MANDATORY, BLOCKING)

These gates apply to Auto mode (full pipeline). Do NOT advance past a gate until ALL conditions are met.

**GATE 1: Framework → Role Analysis** (Step 1 → Step 3)
- REQUIRED: `guidance-specification.md` written with §10 feature decomposition and RFC 2119 keywords.
- REQUIRED: Role selection completed (interactive or auto-default).
- BLOCKED if missing: complete framework generation before spawning role agents.

**GATE 2: Role Analysis → Cross-Role Review** (Step 3 → Step 4.5)
- REQUIRED: Every selected role has `{role}/analysis.md` with §2 Decision Digest (4 tables).
- REQUIRED: Per-feature files `{role}/analysis-F-*.md` written for each feature in §10.
- BLOCKED if missing: complete all role analyses before spawning cross-role-reviewer.

**GATE 2.5: Cross-Role Review → Boundary Grill** (Step 4.5 → Step 4.6)
Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-role-reviewer output.
Input: reviewer findings + role Decision Digests. Scope guard: "only brainstorm decisions; do not pre-resolve roadmap/plan choices".
IF conflicts → results to `guidance-specification.md` §12.5 + feed into GATE 3. NON-BLOCKING.

**GATE 3: Cross-Role Review → Completion** (Step 4.5/4.6 → Report)
- REQUIRED: Cross-role-reviewer output received with `patch_targets[]`.
- REQUIRED: Boundary grill completed (if conflicts detected, results logged).
- REQUIRED: If findings > 0, resolutions applied via Edit AND logged in `guidance-specification.md` §12.
- REQUIRED: If findings == 0, final report explicitly states "No cross-role issues detected".
- BLOCKED if missing: complete review synthesis before reporting.

### Artifact Verification (before completion report)

```
AUTO_MODE_REQUIRED = [
  "guidance-specification.md",            // Step 1
  "{role}/analysis.md" (per selected role), // Step 3
  "{role}/analysis-F-*.md" (per feature),   // Step 3
]
```
If any artifact is missing: DO NOT report completion. Go back and produce the missing artifact.

### Evidence Requirement

Role analysis findings in `{role}/analysis.md` §2 Decision Digest MUST cite concrete evidence:
- Code references (file:line), API endpoints, data models from the codebase
- User-provided constraints from interview
- Cross-role references to other role analyses
Decisions w