maestro-flow 0.5.2 → 0.5.31

package/workflows/brainstorm.md

@@ -1,6 +1,6 @@
 # Workflow: Brainstorm
 
-Unified brainstorming workflow with dual-mode operation: auto pipeline (full multi-role analysis) and single role analysis mode.
+Dual-mode brainstorming: auto pipeline (full multi-role analysis) or single role analysis.
 
 ## Architecture
 
@@ -27,25 +27,8 @@ Artifacts N×Role     Cross-  Apply  1×Role
 
 ## Dual-Mode Routing
 
-### Auto Mode (full pipeline)
-Triggered by `--yes`/`-y` flag or user selection.
-
-```
-Phase 1: Mode Detection → Parse args, detect mode
-Phase 1.5: Terminology & Boundary → Extract terms, collect Non-Goals
-Phase 2: Interactive Framework → 7 sub-phases (context → topic → roles → questions → conflicts → check → spec)
-Phase 3: Parallel Role Analysis → N concurrent {role}/ multi-file via role-design-author
-Phase 4: Cross-Role Review → cross-role-reviewer compares Decision Digests (read-only)
-Phase 5: Apply Resolutions → AskUserQuestion per finding → patch role files + guidance §12
-```
-
-### Single Role Mode
-Triggered when first arg is a valid role name.
-
-```
-Phase 1: Mode Detection → Parse args, detect mode
-Phase 3: Single Role Analysis → Detection → Context → Agent → Validation
-```
+**Auto Mode** (`--yes`/`-y`): Phase 1 → 1.5 → 2 → 3 → 4 → 5 (full pipeline)
+**Single Role Mode** (first arg = role name): Phase 1 → 3 (single role)
 
 ## Input
 
@@ -102,17 +85,13 @@ All brainstorm output goes to scratch:
     └── ...
 ```
 
-Clarifications and audit trail live in `guidance-specification.md` §11 Appendix. Cross-Role Resolutions in §12.
-
 ---
 
 ## Process
 
 ### Step 1: Parse & Route (Mode Detection)
 
-Parse $ARGUMENTS to determine execution mode:
-
-**Mode Detection (ordered by priority)**:
+**Mode Detection (priority order)**:
 1. `--review-only` flag → **Review-Only Mode** (requires `--session ID`; runs Step 4.5 + Step 5 only)
 2. `--yes` or `-y` flag → **Auto Mode** (no question asked)
 3. First non-flag arg matches valid role name → **Single Role Mode**
@@ -142,23 +121,19 @@ Parse $ARGUMENTS to determine execution mode:
 
 ---
 
-### Step 1.3: Load Upstream Context (if `--from` specified)
+### Step 1.3: Load Upstream Context (if `--from`)
 
-Resolve upstream source and load `context-package.json`:
-- `--from grill:ID` → `state.json.artifacts[type=grill, id=ID].context_package` → load
-- `--from blueprint:ID` → `state.json.artifacts[type=blueprint, id=ID].context_package` → load
-- `--from @file` → read file directly as upstream material
-- `--from path/` → load `path/context-package.json`
+Resolve to `context-package.json` (`grill:ID` / `blueprint:ID` / `@file` / `path/`).
 
-From loaded context-package, pre-seed brainstorm session:
-- `domain.terminology[]` → pre-populate Step 2 terminology (skip re-extraction for locked terms)
-- `constraints[status=locked]` → inject into guidance §4-N as pre-decided constraints (skip re-asking)
-- `non_goals[]` → pre-populate Step 2 non-goals (skip re-asking for these)
-- `open_questions[]` → seed Step 3 Phase 1 probing questions
-- `insights[]` → pass to role-design-author in Step 4 as additional context
-- `requirements[]` → seed Step 3 Phase 4.5 feature decomposition
+Pre-seed from context-package:
+- `domain.terminology[]` → Step 2 (skip locked terms)
+- `constraints[locked]` → guidance §4-N
+- `non_goals[]` → Step 2
+- `open_questions[]` → Step 3 Phase 1
+- `insights[]` → Step 4 role agents
+- `requirements[]` → Step 3 Phase 4.5
 
-Store as `upstream_context` (in-memory). If source not found, warn (W007) and continue without upstream.
+W007 if source not found: continue without upstream.
 
 ---
 
@@ -168,19 +143,11 @@ Store as `upstream_context` (in-memory). If source not found, warn (W007) and co
 specs_content = maestro spec load --category arch
 ```
 
-Pass to role-design-author in Step 4 for architecture-aware role analysis.
-
 ---
 
-### Auto Mode Steps (Phase 1.5 → Phase 1.7 → Phase 2 → Phase 3 → Phase 4)
-
 ### Step 1.7: External Research — Design Routes (Auto Mode, Optional)
 
-Spawn `workflow-external-researcher` agent to discover design alternatives, architecture patterns, and competitive approaches for the brainstorm topic. This enriches the framework generation and role analyses with external knowledge.
-
-**Trigger**: Always in auto mode. Skip if `--skip-questions` and no tech keywords detected.
-
-**Auto-suggest when**: Topic contains technology keywords, architecture terms, or "design" / "pattern" / "alternative" in the description.
+**Trigger**: Always in auto mode. Skip if `--skip-questions` and no tech keywords.
 
 ```
 // Step 1.7.1: Spawn external researcher for design routes
@@ -218,47 +185,28 @@ Return structured markdown only — do NOT write files.
 designResearchContext = agent_output
 ```
 
-`designResearchContext` is passed into:
-- Step 2 (Terminology): enriches domain term extraction
-- Step 3 Phase 1 (Topic Analysis): provides external design alternatives
-- Step 4 (Parallel Role Analysis): each role-design-author receives design research as additional context
+`designResearchContext` → Steps 2, 3, 4. Persisted to `{output_dir}/design-research.md`.
 
-Also persisted to `{output_dir}/design-research.md` for future reference.
-
-If research fails (W005): `designResearchContext = null`, continue without external context.
+W005 on failure: continue without external context.
 
 ---
 
 ### Step 1.8: Load Project Context (if `.workflow/` exists)
 
-Load existing project history to ground brainstorming in what's already been built:
-
-- From `.workflow/project.md`: `### Validated` → already_shipped, `### Active` → current_scope, `## Context` → project_history
-- From `.workflow/state.json.accumulated_context`: `deferred[]` → deferred_items, `key_decisions[]` → existing_constraints
+- `project.md`: Validated → already_shipped, Active → current_scope
+- `state.json.accumulated_context`: `deferred[]` → brainstorming seeds, `key_decisions[]` → constraints
 
-Pass `project_context` into Step 2 (terminology) and Step 3 (framework generation):
-- `already_shipped` informs what exists — brainstorm should explore extensions, not re-invent
-- `deferred_items` are high-value brainstorming seeds
-- `lessons_learned` surface pitfalls to avoid
+Pass into Steps 2 and 3.
 
 ---
 
 ### Step 2: Terminology & Boundary Definition (Auto Mode)
 
-Extract core terminology and define scope boundaries before framework generation.
+1. Extract 5-10 core domain terms (merge upstream locked terms if available)
+2. AskUserQuestion for Non-Goals (multiSelect, include "其他" option)
+3. Store terminology + non_goals to session
 
-1. Analyze topic description and any project context (project.md, roadmap.md, project_context from Step 1.8)
-2. Extract 5-10 core domain terms:
-   - term (canonical), definition, aliases, category (core|technical|business)
-   - If `upstream_context` loaded (Step 1.3): merge `upstream_context.domain.terminology[]` — locked terms are pre-populated, only extract NEW terms not already in upstream
-3. AskUserQuestion for Non-Goals (multiSelect=true):
-   - If `upstream_context` loaded: pre-select `upstream_context.non_goals[]`, ask only for additions
-   - Else: generate 4-5 context-aware exclusion candidates based on topic
-   - Include "其他（请补充）" option for custom exclusions
-   - If user selects "其他", follow up with free-text question
-4. Store terminology table and non_goals to session state
-
-**Skip if**: `--yes` flag (use auto-generated terms, empty non-goals)
+**Skip if**: `--yes` (auto-generate terms, empty non-goals)
 
 ### Step 3: Interactive Framework Generation (Auto Mode)
 
@@ -324,38 +272,17 @@ Seven sub-phases producing guidance-specification.md:
 
 ### Step 3.5: Visual Style Foundation (Auto Mode, conditional)
 
-When `ui-designer` is among the selected roles, establish the project's visual direction before role analysis begins. This ensures all downstream UX analysis works within a confirmed design system.
-
-**Condition**: Skip if `.workflow/impeccable/DESIGN.md` already exists (visual direction already locked).
+**Condition**: `ui-designer` selected AND `.workflow/impeccable/DESIGN.md` does not exist. Skip with `--skip-design`.
 
-**Execution** (sequential):
+1. If PRODUCT.md missing: `Skill({ skill: "maestro-impeccable", args: "teach" })`
+2. `Skill({ skill: "maestro-impeccable", args: "explore" })` → produces DESIGN.md
+3. Record `design_system_established: true` in session metadata
 
-1. **Product context** — if `.workflow/impeccable/PRODUCT.md` missing:
-   ```
-   Skill({ skill: "maestro-impeccable", args: "teach" })
-   ```
-   This runs the teach interview to establish brand, users, personality, anti-references.
-
-2. **Visual exploration** — multi-style comparison and selection:
-   ```
-   Skill({ skill: "maestro-impeccable", args: "explore" })
-   ```
-   This generates multiple design system variants as HTML prototypes, launches visual comparison, and lets the user select/mix. Produces DESIGN.md on completion.
-
-3. Record in session metadata: `design_system_established: true`, `design_md_path: ".workflow/impeccable/DESIGN.md"`
-
-**`--yes` mode**: `explore` auto-selects variant 1 without visual comparison. `teach` still requires minimal input if PRODUCT.md is missing.
-
-**Skip mode**: If user explicitly passes `--skip-design` to brainstorm, skip this step entirely. ui-designer role will generate its own independent theme in Phase 2.
+`--yes`: auto-selects variant 1.
 
 ### Step 4: Parallel Role Analysis (Auto Mode)
 
-For EACH selected role, spawn a `role-design-author` agent in parallel. Each agent produces a multi-file analysis under `{output_dir}/{role}/`.
-
-**Path resolution (orchestrator responsibility, BEFORE invocation)**:
-- Resolve `{output_dir}` to an **absolute path** (e.g., `D:/proj/.workflow/scratch/20260521-brainstorm-foo`). Do NOT pass the literal `.workflow/...` relative form — agent Write tool requires absolute paths.
-- Expand `~/` in `role_template_path` to the user home absolute path.
-- For absent optional fields (e.g., `style_skill` when role ≠ ui-designer, `design_research` when Step 1.7 was skipped), pass the literal string `null` — never a conditional placeholder like `{x if y}`.
+Spawn `role-design-author` per role in parallel. ALWAYS use absolute paths. Pass `null` (literal string) for absent optional fields.
 
 ```
 Agent({
@@ -388,28 +315,16 @@ Agent({
 })
 ```
 
-**Output Contract**: each agent writes files under `{output_dir}/{role}/`:
-- `analysis.md` — INDEX document containing §1 Role Mandate, §2 Decision Digest (4 tables), §3 Cross-Cutting Foundations, §4 File Index, §5 Outstanding TODOs
-- `analysis-F-{id}-{slug}.md` — one per feature (< 2000 words each)
-- `findings-{slug}.md` — additional discoveries (0 or more, < 1000 words each)
+**Output per role**: `analysis.md` (index), `analysis-F-{id}-{slug}.md` (per feature, <2000 words), `findings-{slug}.md` (optional, <1000 words).
 
-See `.claude/agents/role-design-author.md` for the full output contract.
-
-**Digest-Based Validation** (orchestrator reads ONLY `analysis.md` per role, not sub-files):
-- Read `{role}/analysis.md` §2 Decision Digest:
-  - Decisions table: verify ≥ 1 row per feature in feature_list → feature coverage check
-  - RFC 2119 keywords in Constraints column → keyword count check
-- Read `{role}/analysis.md` §4 File Index:
-  - Verify listed files actually exist on disk (glob check)
-  - Verify feature coverage matches feature_list
-- system-architect specifically: verify §3 contains "Data Model" and "State Machine" headings
-- Warn if any analysis-F-*.md > 2000 words (from agent's return protocol `total_lines`)
-
-**Parallel Safety**: Each agent writes only to its own `{role}/` directory. No shared output, no cross-agent dependencies.
+**Validation** (read only `analysis.md`):
+- §2: ≥1 decision per feature, RFC 2119 keywords present
+- §4: listed files exist on disk, feature coverage matches
+- system-architect: §3 has "Data Model" and "State Machine" headings
 
 ### Step 4.5: Cross-Role Review (Auto Mode)
 
-After all role analyses are produced, spawn ONE `cross-role-reviewer` agent. The agent compares Decision Digests from each role's `analysis.md` — it does NOT read per-feature sub-files unless it needs deeper context.
+Spawn ONE `cross-role-reviewer` to compare Decision Digests across roles.
 
 ```
 Agent({
@@ -431,57 +346,31 @@ Agent({
 })
 ```
 
-**Agent output** (parsed by orchestrator):
-- `conflicts[]` — C-IDs with role-A vs role-B contradictions from §2 Decisions/Positions comparison
-- `gaps[]` — G-IDs from §2 Interfaces consumer references without matching definitions
-- `synergies[]` — S-IDs from §2 Findings Summary with concrete patch suggestions
-- `need_deeper_context[]` — (optional) specific sub-files the reviewer needs to read for ambiguous cases
+**Output**: `conflicts[]`, `gaps[]`, `synergies[]`, `need_deeper_context[]` (optional).
 
-**Deeper context handling**: If the reviewer returns `need_deeper_context` entries, the orchestrator reads those specific files and re-invokes the reviewer via SendMessage with the injected content. Expected to happen in < 10% of reviews.
+If `need_deeper_context`: read specific files, re-invoke reviewer. Skip Step 5 if all arrays empty.
 
-Store as `review_findings` in session memory. Skip Step 5 entirely if all three arrays are empty.
-
-If `--yes` flag set: auto-apply each finding's suggested resolution without AskUserQuestion (still proceed to Step 5 writeback).
+`--yes`: auto-apply resolutions (still proceed to Step 5 writeback).
 
 ### Step 5: Apply Cross-Role Resolutions (Auto Mode)
 
-Consume `review_findings` from Step 4.5 and apply user-confirmed resolutions to the relevant role analysis files and `guidance-specification.md`.
-
-**Sub-phase 5.1: Interactive Confirmation (skip if `--yes`)**
-- For each finding (conflicts → gaps → synergies, in that order), call AskUserQuestion (max 4 per round):
-  - **Conflict question** options: "Accept suggested resolution" (recommended) / "Pick role A's stance" / "Pick role B's stance" / "Defer to TODO"
-  - **Gap question** options: "Accept suggested addition" (recommended) / "Skip this gap" / "Defer to TODO"
-  - **Synergy question** options: "Apply patch" (recommended) / "Skip"
-- Question text MUST cite the exact role folder + `target_heading` from the agent output (heading text, not section number).
-- Store user choices as `resolutions[]`.
+**5.1: Interactive Confirmation (skip if `--yes`)**
 
-**Sub-phase 5.2: Apply Patches to Role Files**
+AskUserQuestion per finding (max 4 per round). MUST cite exact role folder + `target_heading`.
 
-The reviewer's output includes a `patch_targets[]` block per finding with closed-vocabulary `edit_type` (`annotate_after_heading` / `annotate_and_strikeout` / `append_to_section`). The orchestrator consumes these directly — do NOT re-parse the prose.
+**5.2: Apply Patches to Role Files**
 
-For each accepted finding, iterate over its `patch_targets[]`:
+Consume `patch_targets[]` per finding. Edit types: `annotate_after_heading` / `annotate_and_strikeout` / `append_to_section`.
 
-**Conflict patches** (edit_type usually `annotate_and_strikeout`):
-- Locate `target_heading` in `target_file` (e.g., `system-architect/analysis-F-002-skill-engine.md`) via Edit string match (heading text MUST match verbatim).
-- Insert `edit_content` (a `> blockquote` Cross-Role Resolution line) immediately after the matched heading.
-- Wrap the original paragraph below the heading in `<!-- superseded by C-XXX -->` … `<!-- /superseded -->` HTML comments so the original text stays readable but downstream tooling treats it as non-authoritative.
-- If the user chose "Pick role A's stance" → strikeout role B's site only; vice versa. If "Accept suggested resolution" → strikeout BOTH role-A and role-B sites (both supersede to the new resolution).
+| Type | Action |
+|------|--------|
+| Conflict (`annotate_and_strikeout`) | Insert resolution blockquote after heading, wrap original in `<!-- superseded -->` |
+| Gap (`annotate_after_heading` + `append_to_section`) | Breadcrumb at reference site, definition at owner site. Both MUST succeed. |
+| Synergy (`annotate_after_heading` × 2) | Cross-reference in BOTH files. Original untouched. |
 
-**Gap patches** (edit_type pair: `annotate_after_heading` at reference site + `append_to_section` at owner site):
-- At reference site: insert the breadcrumb annotation pointing to the owner site.
-- At owner site: append the actual definition content (1-3 lines from `edit_content`).
-- Both edits MUST succeed; if owner-site append fails, roll back reference-site annotation.
+**On heading mismatch**: skip patch, log finding ID, surface in Step 7 report. NEVER invent headings.
 
-**Synergy patches** (edit_type `annotate_after_heading` × 2):
-- Insert cross-reference annotations in BOTH role files. Synergy is symmetric — alignment must be visible from either entry point.
-- Original content untouched.
-
-**Edit failure handling**:
-- If `target_heading` does not match verbatim, log the finding ID and target, skip the patch, and surface to the user in Step 7 final report ("3 patches skipped — heading drift").
-- Never invent the heading; refusal to patch is safer than wrong patch.
-
-**Sub-phase 5.3: Append to guidance §12**
-Append a new subsection to `guidance-specification.md` §12 Cross-Role Resolutions capturing the audit trail:
+**5.3: Append to guidance §12**
 ```markdown
 ### Cross-Role Resolutions (added {date})
 | ID | Type | Source(s) | Resolution | Applied to |
@@ -491,18 +380,12 @@ Append a new subsection to `guidance-specification.md` §12 Cross-Role Resolutio
 | S-001 | synergy | ux-expert/analysis-F-005-tui.md "## Interface Contract" / sme/findings-ndjson.md "## Recommendation" | applied | both annotated |
 ```
 
-**Sub-phase 5.4: Finalization**
-- Update session metadata (`review_findings_count`, `resolutions_applied`, `completion_status`).
-- Emit completion report (see Step 7).
+**5.4: Finalization** — Update session metadata, emit completion report (Step 7).
 
 ---
 
-### Single Role Mode Steps
-
 ### Step 6: Single Role Analysis
 
-Execute analysis for ONE specified role with optional interactive context gathering.
-
 **Step 6.1: Detection & Validation**
 - Validate role_name against VALID_ROLES list
 - Detect session (--session or find existing)
@@ -531,23 +414,16 @@ Execute analysis for ONE specified role with optional interactive context gather
 
 ---
 
-### Review-Only Mode Steps
-
-### Step 6.5: Review-Only Mode
-
-Triggered by `--review-only --session ID`. Skips Phase 3 entirely; runs only Step 4.5 + Step 5 against the existing role analysis files.
+### Step 6.5: Review-Only Mode (`--review-only --session ID`)
 
 **Step 6.5.1: Validation**
 - Require `--session ID`. Error E002 if missing.
 - Glob `{output_dir}/*/analysis.md`. Error E006 if zero files found (no role analyses to review).
 - Require `guidance-specification.md` to exist (for decision-ID context). Error E007 if missing.
 
-**Step 6.5.2: Execute Step 4.5 + Step 5**
-- Reuse the exact same logic as auto mode Step 4.5 (spawn cross-role-reviewer with analysis indexes) and Step 5 (interactive confirmation + patch application + guidance §12 audit).
-- Skip Step 5.1 interactive confirmation if `--yes` also passed.
+**Step 6.5.2**: Run Step 4.5 + Step 5. Skip 5.1 if `--yes`.
 
-**Step 6.5.3: Report**
-- Same as review-only mode report in Step 7.
+**Step 6.5.3**: Report (same as review-only report in Step 7).
 
 ---
 
@@ -621,20 +497,3 @@ Write `{output_dir}/context-package.json` by extracting from session artifacts:
 Register artifact in state.json with additional field:
   `context_package: "{output_dir}/context-package.json"`   (relative to .workflow/)
 
----
-
-## Quality Criteria
-
-- If `designResearchContext` is set: guidance-specification.md references external design findings
-- guidance-specification.md uses RFC 2119 keywords (MUST/SHOULD/MAY)
-- Concepts & Terminology section with 5-10 core terms
-- Non-Goals section with rationale
-- Feature Decomposition table (max 8 features, independently implementable)
-- Each `{role}/analysis.md` contains §2 Decision Digest with all four tables (Decisions, Interfaces, Cross-Cutting Positions, Findings Summary)
-- Each `{role}/analysis.md` §4 File Index accurately lists all written files with headings
-- Each `{role}/analysis-F-*.md` < 2000 words, each `findings-*.md` < 1000 words
-- system-architect's `analysis.md` §3 includes: Data Model, State Machine, Error Handling, Observability
-- Cross-role review runs (Step 4.5) and produces structured findings from §2 Digest comparison with `patch_targets[]` blocks
-- **If review yielded findings**: each accepted resolution is annotated in the affected role analysis file AND logged in guidance §12 "Cross-Role Resolutions"
-- **If review yielded zero findings**: guidance §12 unchanged; final report explicitly notes "No cross-role issues detected"
-- Heading-drift patch failures (if any) are surfaced in the final report, not silently dropped