with one click
maestro-brainstorm
// Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
// Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
| name | maestro-brainstorm |
| description | Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation |
Pipeline position: downstream of maestro-grill (optional stress-test). Upstream of maestro-roadmap, maestro-analyze, and maestro-blueprint (all consume brainstorm output).
<required_reading> @~/.maestro/workflows/brainstorm.md </required_reading>
<deferred_reading>
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 | — |
maestro spec load --category arch to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.maestro wiki list --category archmaestro wiki load <id1> [id2] [id3...]<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>
Follow '~/.maestro/workflows/brainstorm.md' completely. ### Standalone report=== BRAINSTORM READY ===
Session: {session_id}
Output: {output_dir}
Mode: {auto|single-role}
Roles: {selected_roles}
Findings: {review_findings_count} cross-role issues, {resolutions_applied} resolutions applied
Status: COMPLETE
========================
End the step by calling the CLI (no text block output):
maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
Status verdicts:
--concerns--reasonAuto mode:
| Condition | Suggestion |
|---|---|
| Project not initialized | /maestro-init |
| Need formal spec package | /maestro-blueprint --from brainstorm:{artifact_id} |
| Quick roadmap needed | /maestro-roadmap --from brainstorm:{artifact_id} |
| Need deeper analysis first | /maestro-analyze {topic} --from brainstorm:{artifact_id} |
| Need stress-testing first | /maestro-grill {topic} |
html-prototypes/ produced with 2+ files and user wants to browse | Load ~/.maestro/workflows/brainstorm-visualize.md and launch visualizer server |
| DESIGN.md established during Step 3.5 | /maestro-impeccable build <feature-description> |
Single role mode:
| Condition | Suggestion |
|---|---|
| More roles needed | /maestro-brainstorm {next_role} --session {session_id} |
| All roles done, run synthesis | /maestro-brainstorm {topic} --session {session_id} |
<error_codes>
| Code | Severity | Condition | Recovery |
|---|---|---|---|
| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
| E002 | error | No active session for single role mode | Guide user to run auto mode first |
| E003 | error | Invalid role name | Show valid roles list |
| E006 | error | --review-only but no {role}/analysis.md found | Run auto or single-role mode first |
| E007 | error | --review-only but guidance-specification.md missing | Run auto mode to generate guidance first |
| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
| W002 | warning | Project context (.workflow/) not found | Continue without project context |
| W003 | warning | Role template not found | Use generic analysis structure |
| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
| W005 | warning | External research agent failed | Continue without designResearchContext |
| W006 | warning | Reviewer patch_targets heading drift (no match) | Skip that patch; report in final summary |
| </error_codes> |
<success_criteria> Auto mode:
guidance-specification.md §11 and session metadataguidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition (§10), decision tracking (§11), cross-role resolutions placeholder (§12)design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)ui-designer in selected_roles AND Step 3.5 ran: .workflow/impeccable/DESIGN.md exists (visual style established via impeccable explore){role}/analysis.md written for each selected role, containing §2 Decision Digest (4 tables) + §3 Cross-Cutting Foundations + §4 File Index{role}/analysis-F-{id}-{slug}.md written per feature (one file per feature, < 2000 words)system-architect/analysis.md §3 includes Data Model + State Machine when system-architect is selectedui-designer/analysis.md references DESIGN.md visual constraints when ui-designer is selected{role}/analysis.md §2 Decisions table has ≥ 1 row per featurepatch_targets[] for every findingguidance-specification.md §12 "Cross-Role Resolutions"Single role mode:
{role}/analysis.md written with §2 Decision Digest + §4 File Index{role}/analysis-F-*.md written when guidance §10 feature list available<on_complete> @~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null </on_complete>
Use when a topic needs structured multi-dimensional investigation before planning or decision-making
Generate formal specification package (Product Brief, PRD, Architecture, Epics) through 6-phase document chain
Use when a confirmed plan is ready for implementation
Use when stress-testing a plan, idea, or requirement against codebase reality before brainstorming
Initialize project with auto state detection
Audit current milestone for cross-phase integration gaps