maestro-brainstorm

name	maestro-brainstorm
description	Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation

Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).

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>

• scratch-index.json — read when operating in scratch mode
• index.json — read when operating in phase mode
• brainstorm-visualize.md — read when html-prototypes/ produced and user wants to browse them </deferred_reading>

$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 spec load --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. Browse accumulated knowledge for this role: maestro wiki list --category arch
2. Analyze the index, identify entries relevant to the current task
3. Load selected documents: maestro wiki load <id1> [id2] [id3...]
4. Review loaded knowledge before proceeding

<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
========================

Ralph-invoked completion

End the step by calling the CLI (no text block output):

maestro ralph complete <idx> --status {STATUS} [--evidence {path}]

Status verdicts:

• DONE — Normal completion
• DONE_WITH_CONCERNS — Completed with caveats; pass --concerns
• NEEDS_RETRY — Tooling error / transient issue; ralph will retry
• BLOCKED — External hard blocker; pass --reason

Next-step routing

Auto 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:

• Interactive mode: interview decision table written to guidance-specification.md §11 and session metadata
• guidance-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)
• If 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 selected
• ui-designer/analysis.md references DESIGN.md visual constraints when ui-designer is selected
• Each {role}/analysis.md §2 Decisions table has ≥ 1 row per feature
• Cross-role review (Step 4.5) executed; reviewer compares §2 Decision Digests; output includes patch_targets[] for every finding
• If findings exist: each accepted resolution applied via replace_file_content(annotate / strikeout / append) AND logged in guidance-specification.md §12 "Cross-Role Resolutions"
• If zero findings: final report explicitly states "No cross-role issues detected"; guidance §12 unchanged
• Heading-drift patch failures surfaced in final report (if any)
• Session metadata updated with completion status (review_findings_count, resolutions_applied, patches_skipped)

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
• §2 Decisions table references guidance decision IDs
• Session metadata updated
• Session sealed via finish-work (auto mode only) </success_criteria>

<on_complete> @~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null </on_complete>