brainstorm

# Brainstorming Ideas Into Designs Host-neutral workflow. Invoke by skill name (`brainstorm`). Claude Code slash routing, YAML hook loaders, and `.claude/chain` live in `references/claude-code.md`. Transform rough ideas into fully-formed designs through intelligent agent selection and structured exploration. **Core principle:** Analyze the topic, select relevant agents dynamically, explore alternatives in parallel, present design incrementally. ## Argument Resolution ```python TOPIC = "$ARGUMENTS" # Full argument string, e.g., "API design for payments" # $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access) ``` --- ## STEP -1: MCP Probe + Resume Check Probe MCP servers once at skill start, store capabilities, and resume from any prior crashed session. Each phase emits a JSON handoff file consumed by the next. Full procedure + handoff-file table: `Read("references/mcp-probe-resume.md")` --- ## STEP 0: Project Context Discovery **BEFORE creating tasks or selecting agents**, detect the project tier. This becomes the **complexity ceiling** for all downstream decisions. ### Auto-Detection (scan codebase) ```python # PARALLEL — quick signals (launch all in ONE message) Grep(pattern="take-home|assignment|interview|hackathon", glob="README*", output_mode="content") Grep(pattern="take-home|assignment|interview|hackathon", glob="*.md", output_mode="content") Glob(pattern=".github/workflows/*") Glob(pattern="**/Dockerfile") Glob(pattern="**/terraform/**") Glob(pattern="**/k8s/**") Glob(pattern="CONTRIBUTING.md") ``` ### Tier Classification | Signal | Tier | |--------|------| | README says "take-home", "assignment", time limit | **1. Interview** | | < 10 files, no CI, no Docker | **2. Hackathon** | | `.github/workflows/`, 10-25 deps | **3. MVP** | | Module boundaries, Redis, background jobs | **4. Growth** | | K8s/Terraform, DDD structure, monorepo | **5. Enterprise** | | CONTRIBUTING.md, LICENSE, minimal deps | **6. Open Source** | **If confidence is low**, ask the user: ```python AskUserQuestion(questions=[{ "question": "What kind of project is this?", "header": "Project tier", "options": [ {"label": "Interview / take-home", "description": "8-15 files, 200-600 LOC, simple architecture"}, {"label": "Startup / MVP", "description": "MVC monolith, managed services, ship fast"}, {"label": "Growth / enterprise", "description": "Modular monolith or DDD, full observability"}, {"label": "Open source library", "description": "Minimal API surface, exhaustive tests"} ], "multiSelect": false }]) ``` **Pass the detected tier as context to ALL downstream agents and phases.** The tier constrains which patterns are appropriate — see `scope-appropriate-architecture` skill for the full matrix. > **Override:** User can always override the detected tier. Warn them of trade-offs if they choose a higher tier than detected. --- ## STEP 0a: Verify User Intent with AskUserQuestion **Clarify brainstorming constraints:** ```python # NOTE: AskUserQuestion caps each question at 4 options (CC schema: minItems 2, # maxItems 4). Use plain `label` + `description` only — the schema permits a # `preview` field, but on current CC it forces a side-by-side picker layout with # dead up/down keyboard nav (confirmed 2026-05-28), so skills no longer use it # (`markdown` was never valid). The 6 legacy # modes are split across 3 valid questions: Q1 = exploration flow, Q2 folds the # old "Constrained design" mode into constraints, Q3 carries the orthogonal # "Plan first" preamble (it composes with any Q1 mode — it was never mutually # exclusive). "Quick ideation" + STEP 0c /effort=low overlap; both downscale. AskUserQuestion( questions=[ { "question": "What type of design exploration?", "header": "Mode", "options": [ {"label": "Open exploration (Recommended)", "description": "Generate 10+ ideas, evaluate all, synthesize top 3"}, {"label": "Comparison", "description": "Compare 2-3 specific approaches I have in mind"}, {"label": "Quick ideation", "description": "Generate ideas fast, skip deep evaluation"}, {"label": "Iterative optimization", "description": "Try, measure, keep/discard, repeat (autoresearch-style)"} ], "multiSelect": false }, { "question": "Any preferences or constraints?", "header": "Constraints", "options": [ {"label": "None", "description": "Explore all possibilities"}, {"label": "Use existing patterns", "description": "Prefer patterns already in codebase"}, {"label": "Minimize complexity", "description": "Favor simpler solutions"}, {"label": "Fixed requirements (constrained)", "description": "Hard requirements to work within — skip divergent phase, focus on feasibility (old 'Constrained design' mode)"} ], "multiSelect": false }, { "question": "Research before ideating?", "header": "Plan-first", "options": [ {"label": "No — dive straight in (Recommended)", "description": "Go directly to ideation"}, {"label": "Yes — plan first", "description": "Read-only research (EnterPlanMode): scan codebase, map the solution space, then ExitPlanMode for approval before Phase 1 (old 'Plan first' mode)"} ], "multiSelect": false } ] ) ``` **If Q3 = 'Yes — plan first' (composes with any Q1 mode):** ```python # 1. Enter read-only plan mode EnterPlanMode("Brainstorm exploration: $TOPIC") # 2. Research phase — Read/Grep/Glob ONLY, no Write/Edit # - Scan existing codebase for related patterns # - Search for prior decisions on this topic (memory graph) # - Identify constraints, dependencies, and trade-offs # 3. Produce structured exploration plan: # - Key questions to answer # - Dimensions to explore # - Agents to spawn and their focus areas # - Evaluation criteria # 4. Exit plan mode — returns plan for user approval ExitPlanMode() # 5. User reviews. If approved → continue to Phase 1 with plan as input. ``` **Based on answers, adjust workflow:** - **Open exploration** (Q1): Full 7-phase process with all agents - **Comparison** (Q1): Skip ideation, jump to evaluation phase - **Quick ideation** (Q1): Generate ideas, skip deep evaluation - **Iterative optimization** (Q1): Skip phases 2-6, enter autoresearch-style loop (see below) - **Constrained design** (Q2 = "Fixed requirements"): Skip divergent phase, focus on feasibility within the stated requirements — composes with any Q1 mode **If 'Iterative optimization' selected:** skip Phases 2-6 and enter the autoresearch-style metric-driven loop. Full sub-flow (metric question, baseline, loop body): `Read("references/iterative-optimization-mode.md")` --- ## STEP 0b: Select Orchestration Mode (skip for Tier 1-2) Choose **Agent Teams** (mesh, agents debate and challenge ideas) or **Agent tool** (star, all report to lead): 1. Agent Teams mode (GA since CC 2.1.33) → **recommended for 3+ agents** (real-time debate produces better ideas) 2. Agent tool mode → **for quick ideation** 3. `ORCHESTKIT_FORCE_TASK_TOOL=1` → **Agent tool** (override) | Aspect | Agent Tool | Agent Teams | |--------|-----------|-------------| | Idea generation | Each agent generates independently | Agents riff on each other's ideas | | Devil's advocate | Lead challenges after all complete | Agents challenge each other in real-time | | Cost | ~150K tokens | ~400K tokens | | Best for | Quick ideation, constrained design | Open exploration, deep evaluation | > **Fallback:** If Agent Teams encounters issues, fall back to Agent tool for remaining phases. --- ## STEP 0c: Effort-Aware Phase Scaling (CC 2.1.76; `xhigh` added in 2.1.111) Read the `/effort` setting and scale brainstorm depth — `low` runs phases 0/2/5 only, `high` (default) runs all 7, `xhigh` adds extra devil's-advocate and synthesis rounds. Explicit user choice in STEP 0a always overrides downscaling. Full level table + detection rules: `Read("references/effort-scaling.md")` --- **Finish line.** Done means: the top approaches are scored on all seven dimensions and the trade-offs are presented for the user to choose. Follow `Read("../../shared/rules/long-run-protocol.md")`: keep going when a step needs no input from the user, stop and ask only when you can't continue without them or before anything destructive, check each subagent's evidence before accepting it, and mark anything you couldn't confirm with where you looked. ## 🚨 CRITICAL: Task Management is MANDATORY (CC 2.1.16) ```python # 1. Create main task IMMEDIATELY TaskCreate( subject="Brainstorm: {topic}", description="Design exploration with parallel agent research", activeForm="Brainstorming {topic}" ) # 2. Create subtasks for each phase TaskCreate(subject="Analyze topic and select agents", activeForm="Analyzing topic") # id=2 TaskCreate(subject="Search memory for past decisions", activeForm="Searching knowledge graph") # id=3 TaskCreate(subject="Generate divergent ideas (10+)", activeForm="Generating ideas") # id=4 TaskCreate(subject="Feasibility fast-check", activeForm="Checking feasibility") # id=5 TaskCreate(subject="Evaluate with devil's advocate", activeForm="Evaluating ideas") # id=6 TaskCreate(subject="Synthesize top approaches", activeForm="Synthesizing approaches") # id=7 TaskCreate(subject="Present design options", activeForm="Presenting options") # id=8 # 3. Set dependencies (sequential chain: 2→3→4→5→6→7→8) for i in range(3, 9): TaskUpdate(taskId=str(i), addBlockedBy=[str(i-1)]) # 4. Update status as you progress TaskUpdate(taskId="2", status="in_progress") # When starting TaskUpdate(taskId="2", status="completed") # When done — repeat for each subtask ``` --- ## 🔄 The Seven-Phase Process | Phase | Activities | Output | |-------|------------|--------| | **0. Topic Analysis** | Classify keywords, select 3-5 agents | Agent list | | **1. Memory + Context** | Search graph, check codebase, read experiment journal | Prior patterns | | **2. Divergent Exploration** | Generate 10+ ideas WITHOUT filtering | Idea pool | | **3. Keep/Discard Gate** | Binary viability: keep, discard, or crash (10s per idea) | Survivors only | | **4. Evaluation & Rating** | Rate 0-10 (7 dimensions incl. **simplicity**), devil's advocate | Ranked ideas | | **5. Synthesis** | Filter to top 2-3, trade-off table, **test strategy per approach** | Options | | **6. Design Presentation** | Present in 200-300 word sections, log to experiment journal | Validated design | | **6.4. Living Plan Playground** (optional, on request or multi-wave plan) | Emit an updatable LPP playground via `visualize-plan`'s living-plan path | `<slug>.html` (living) | | **6.5. Audio Podcast** (signal-fired, optional) | Auto-emit `brainstorm-podcast.m4a` when composite≥8.0 + approaches≥4 | `.m4a` file | ### Phase 6.4 — Living Plan Playground (optional) When the user asked for a playground output, OR the synthesis produced a **multi-wave plan** (2+ execution waves with verifiable items), emit the design as a **living plan playground** instead of a one-shot render: waves from Phase 5 synthesis, 7-dimension scores from Phase 4, discarded ideas with reasons from Phase 3, one item per work unit with a "done when" evidence check. Route through `visualize-plan`'s living-plan path (exemplar `living-plan.template.html`, update-mode contract in its `references/format-dispatch.md` §Living-plan update mode). The artifact then tracks its own execution: later sessions flip item statuses in the embedded `lpp-state` JSON and append to its changelog — one plan = one file, never fork. ### Phase 6.5 — Post-synthesis audio podcast (signal-fired, optional) After Phase 6 lands, optionally invoke `scripts/post_synth_podcast.py <session-dir>` to auto-emit an audio podcast summarizing the top approaches + trade-offs. Self-skips on every non-happy-path so it never breaks the brainstorm: ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/post_synth_podcast.py "$CLAUDE_JOB_DIR" ``` Auto-skip conditions (all exit 0, all WARN-logged): | Skip reason | Trigger | |-------------|---------| | `signal absent` | `composite[recommended] < 8.0` OR `len(approaches) < 4` | | `design-doc.md not found` | Phase 6 didn't write a design doc to the session dir | | `yg-mcp-core not importable` | `yg-mcp-core>=0.3.0` not installed (orchestkit is public; yg-mcp-core lives on private `pypi.yonyon.ai` — HQ-only) | | `hq-content MCP unreachable` | MCP server down OR `.mcp.json` doesn't define `hq-content` | Session dir must contain `brainstorm-output.json` (with `recommended`, `composite`, `approaches`) + `design-doc.md`. Handoff JSON at `<session-dir>/brainstorm-podcast.json` records `status` (`fired` / `skipped`) and `m4a_path` on success. Mirrors `Yonatan-HQ/hq-ext-plugin#194` (audio_podcast handler for `/hq-ext:decide`). ### Progressive Output (CC 2.1.76) Output results **incrementally** after each phase — don't batch everything until the end: | After Phase | Show User |