maestro-flow-one 0.2.5 → 0.2.7

package/maestro-flow/commands/lifecycle/brainstorm.md

@@ -1,112 +1,116 @@
----
-name: maestro-brainstorm
-description: Brainstorm with auto pipeline or single-role analysis
-argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
-</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
-</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}/`.
-**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.
-
-**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Flags**:
-- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
-- `--count N`: Number of roles to select (default 3, max 9)
-- `--session ID`: Use existing session
-- `--update`: Update existing analysis (single role)
-- `--skip-questions`: Skip context gathering questions
-- `--include-questions`: Force context gathering even if analysis exists
-- `--style-skill PKG`: Style package for ui-designer role
-
-### 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
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/brainstorm.md' completely.
-
-**Next-step routing on completion:**
-
-Auto mode:
-- Project not initialized → Skill({ skill: "maestro-init" })
-- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
-- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
-- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
-- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
-
-Single role mode:
-- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
-- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
-</execution>
-
-<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 |
-| 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 |
-</error_codes>
-
-<success_criteria>
-**Auto mode**:
-- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
-- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
-- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
-- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists AND exactly one of `html-prototypes/` / `ascii-mockups/` / `api-sketches/` exists with `README.md` + ≥1 prototype file
-- [ ] ui-designer/analysis.md references each prototype via `@-notation`
-- [ ] HTML prototypes are self-contained (no external `<link>`/`<script src>` URLs — warn only)
-- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
-- [ ] UI-bearing feature specs reference the corresponding prototype in Section 3 (Interface Contract)
-- [ ] feature-index.json and synthesis-changelog.md
-- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
-- [ ] All user decisions captured with Decision Recording Protocol
-- [ ] Session metadata updated with completion status
-- [ ] Confidence scored per role completion and after cross-role analysis
-- [ ] Readiness gate checked before spec generation
-- [ ] Pressure pass completed on at least 1 feature spec
-- [ ] Confidence summary appended to synthesis-changelog.md
-
-**Single role mode**:
-- [ ] analysis.md written to `{output_dir}/{role}/`
-- [ ] Feature-point organization used when feature list available
-- [ ] Framework reference included when guidance-specification.md exists
-- [ ] Session metadata updated
-</success_criteria>
+---
+name: maestro-brainstorm
+description: Brainstorm with auto pipeline or single-role analysis
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
+</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
+</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}/`.
+**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.
+
+**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--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
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → Skill({ skill: "maestro-init" })
+- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
+- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
+- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-ui-craft <feature-description> --chain build` to build with the established design system"
+
+Single role mode:
+- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
+- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
+</execution>
+
+<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 |
+| 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 |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
+- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
+- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
+- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
+- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists with UX analysis (interaction flows, state design, information architecture)
+- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints in Section 3 (Interface Contract)
+- [ ] feature-index.json and synthesis-changelog.md
+- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
+- [ ] All user decisions captured with Decision Recording Protocol
+- [ ] Session metadata updated with completion status
+- [ ] Confidence scored per role completion and after cross-role analysis
+- [ ] Readiness gate checked before spec generation
+- [ ] Pressure pass completed on at least 1 feature spec
+- [ ] Confidence summary appended to synthesis-changelog.md
+
+**Single role mode**:
+- [ ] analysis.md written to `{output_dir}/{role}/`
+- [ ] Feature-point organization used when feature list available
+- [ ] Framework reference included when guidance-specification.md exists
+- [ ] Session metadata updated
+</success_criteria>