# Brainstorm

> Role-based brainstorming with dual modes: --scoped (sequential Task tool, 5 roles) and --exploratory (Agent Teams peer debate, 4 roles). Use for feasibility assessment and idea validation.

- **Type:** Skill
- **Install:** `agentstack add skill-ashaykubal-essential-agents-skills-brainstorm`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ashaykubal](https://agentstack.voostack.com/s/ashaykubal)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ashaykubal](https://github.com/ashaykubal)
- **Source:** https://github.com/ashaykubal/essential-agents-skills/tree/master/skills/brainstorm

## Install

```sh
agentstack add skill-ashaykubal-essential-agents-skills-brainstorm
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Brainstorm

Role-based brainstorming on a given topic with two execution modes:

- **`--scoped`** (default): Sequential Task tool pipeline — Project SME first, 3 role agents in parallel, Critical Analyst last. Best when the problem statement is well understood and you need focused implementation brainstorming.
- **`--exploratory`**: Agent Teams peer debate — Project SME first, then 3 AT teammates (Product & Delivery Lead, Architect, Critical Analyst) debating collaboratively. Best when validating whether an idea has merit and the problem framing is uncertain.

Both modes synthesize into a single brainstorm document with actionable recommendations.

**Invocation arguments:** $ARGUMENTS

---

## When to Use This Skill

**Load this skill when the user request matches ANY of these patterns:**

| Trigger Pattern | Example User Request |
|-----------------|---------------------|
| Implementation evaluation | "Should we build X?", "Evaluate this approach" |
| Feasibility assessment | "Is this feasible?", "How would we implement X?" |
| Architecture brainstorm | "Design the approach for X", "How should X fit into our system?" |
| Post-research planning | "We've researched X, now plan the implementation" |
| Role-based analysis | "Get PM/architect/dev perspectives on X" |

**DO NOT use for:**
- Initial topic research (use `research` first)
- Quick technical questions (ask directly)
- Code review (use `code-review`)
- Debugging (use `issue-debugging`)

---

## Dependencies

| Category | Files | Requirement | When to Load |
|----------|-------|-------------|--------------|
| **Role definitions** | `references/role-*.md` | **REQUIRED** | Load each before spawning its agent |
| **Role output template** | `templates/role-output.md` | **REQUIRED** | Include in PM, Architect, Dev Lead prompts |
| **Critic output template** | `templates/critic-output.md` | **REQUIRED** | Include in Critical Analyst prompt |
| **Synthesis template** | `templates/synthesis-output.md` | **REQUIRED** | Use when writing synthesis |
| **Subagent prompting** | `subagent-prompting` skill | **REQUIRED** | Load at Stage 1 for 4-part prompt template |
| **AT teammate prompts** | `references/at-teammate-prompts.md` | **REQUIRED** (--exploratory only) | Load at Stage 3B for AT prompt structure |
| **Research synthesis** | `--research ` | OPTIONAL | If provided, include in all agent prompts |

**Fallback behavior:**
- If a role reference file is missing: Note in diagnostic log, skip that role, continue with remaining agents
- If output template is missing: Use the schema from this SKILL.md directly
- If research synthesis not provided: Agents work from problem statement alone (warn user that quality may be lower)

---

## Mandatory Execution Checklist (BINDING)

**Every item below is mandatory. No deviations. No substitutions. No skipping.**

This skill uses a multi-stage pipeline. You are the orchestrator. Follow every item in order. Do NOT return to the user until all applicable items are checked.

- [ ] **Stage 1 — Pre-Flight**: Topic parsed (from argument, --doc, or AskUserQuestion)
- [ ] **Stage 1 — Pre-Flight**: subagent-prompting skill loaded
- [ ] **Stage 1 — Pre-Flight**: If topic is ambiguous or under-specified, AskUserQuestion interview conducted (2-3 questions per round)
- [ ] **Stage 1 — Pre-Flight**: If --research not provided, user warned via displayed message AND asked to confirm proceeding
- [ ] **Stage 1 — Mode Detection**: `$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var checked — you MUST check this, no exceptions
- [ ] **Stage 1 — Mode Detection**: If `--exploratory` requested AND env var NOT SET: notify user ("Agent Teams requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Using --scoped mode.") and fall back to `--scoped`
- [ ] **Stage 1 — Mode Detection**: If env var IS SET AND user requests `--exploratory`: AT Confirmation Flow executed (token cost warning + model class choice)
- [ ] **Stage 1 — Mode Detection**: If no mode flag provided: default to `--scoped` (do NOT auto-select AT even if env var is set)
- [ ] **Stage 2 — Project SME**: SME spawned via Task tool (general-purpose, Opus) and output read
- [ ] **Stage 3A (--scoped)**: PM + Architect + Dev Lead spawned in parallel (3 Task tool calls), all outputs read
- [ ] **Stage 3B (--exploratory)**: 3 AT teammates spawned in delegate mode with correct model class, all outputs read
- [ ] **Stage 4 (--scoped only)**: Critical Analyst spawned with ALL prior outputs, output read
- [ ] **Stage 5 — Synthesis**: ALL role outputs read, synthesis written using template, AskUserQuestion for post-synthesis review
- [ ] **Stage 5 — Evaluation Gate**: Critical Evaluation Gate applied to all user responses
- [ ] **Stage 6 — Diagnostics**: Diagnostic YAML written to `$PROJECT_DIR/logs/diagnostics/`

---

## Usage

```
/brainstorm  [--research ] [--scoped | --exploratory]
/brainstorm --doc  [--research ] [--scoped | --exploratory]
```

**Arguments:**
- `` - Free-text topic description or problem statement
- `--doc ` - Use a document as the topic source
- `--research ` - Path to Phase 1 research synthesis (from research). Strongly recommended.
- `--scoped` - (default) Sequential Task tool mode with 5 roles. Use when the problem statement is well understood.
- `--exploratory` - Agent Teams peer debate with 4 roles. Use when validating whether an idea has merit. Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.

**Examples:**
- `/brainstorm "agent teams" --research artifacts/research/agent-teams/synthesis.md` - Scoped brainstorm with research (default mode)
- `/brainstorm --scoped "loop detection"` - Explicit scoped mode
- `/brainstorm --exploratory "new plugin architecture"` - Exploratory mode with AT peer debate
- `/brainstorm --doc plans/proposal.md --exploratory` - Exploratory from a document

---

## Stages

### Stage 1: Pre-Flight

```
Stage 1: Pre-Flight
├── Read problem statement / document
├── Load research synthesis if --research provided
├── Parse mode flag: --scoped (default) or --exploratory
├── Mode detection (see below)
├── AskUserQuestion if ambiguous (iterative, 2-3 questions per round)
├── Slugify topic for output directory
├── Create output directories: $PROJECT_DIR/logs/brainstorm/{topic-slug}/ and $PROJECT_DIR/artifacts/brainstorm/{topic-slug}/
├── Load subagent-prompting skill
├── Load references/role-project-sme.md (needed for Stage 2)
└── Token budget check (warn if >30% for --scoped, >25% for --exploratory)
```

**Mode Detection (MANDATORY — do NOT skip):**

1. Check `$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var
2. Apply this decision matrix:

| Env Var | User Flag | Action |
|---------|-----------|--------|
| NOT SET | No flag | `--scoped` (default) |
| NOT SET | `--scoped` | `--scoped` |
| NOT SET | `--exploratory` | Notify user: "Agent Teams requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Using --scoped mode." Fall back to `--scoped`. |
| SET | No flag | `--scoped` (do NOT auto-select AT) |
| SET | `--scoped` | `--scoped` |
| SET | `--exploratory` | Execute AT Confirmation Flow (see below) |

**AT Confirmation Flow (when --exploratory is selected and env var is set):**

Display to user:

> **Exploratory mode uses Agent Teams peer debate and consumes ~2x tokens compared to --scoped mode.**
>
> 3 AT teammates will debate collaboratively after the SME phase.
>
> **Model class for AT teammates:**
> - **Opus** — highest quality, higher token cost
> - **Sonnet** — high quality, lower token cost (empirically validated)
>
> [Proceed with Opus / Proceed with Sonnet / Switch to --scoped]

Record the user's model choice for Stage 3B teammate spawning.

**AskUserQuestion Protocol (Pre-Spawn):**

If the problem statement is ambiguous, under-specified, or could benefit from scope boundaries:

1. Ask 2-3 clarifying questions using AskUserQuestion
2. Assess whether the answers provide sufficient clarity to construct high-quality prompts
3. If not, ask up to 3 more questions in a follow-up round
4. Repeat until clarity is achieved (no hard cap on rounds, but each round is 2-3 questions max)
5. If the problem statement is clear and well-scoped from the start, skip this step and note in diagnostics: `pre_flight_interview: skipped (problem statement sufficient)`

If `--research` was not provided, warn the user: "No research synthesis provided. Brainstorm quality is significantly higher when preceded by `/research`. Proceed without research?"

### Stage 2: Project SME (Opus, Sequential — First)

```
Stage 2: Project SME
├── Load references/role-project-sme.md
├── Construct prompt using 4-part template
│   ├── GOAL: Establish project context relevant to the topic
│   ├── CONTEXT: Problem statement + research synthesis (if available)
│   └── OUTPUT: $PROJECT_DIR/logs/brainstorm/{topic-slug}/01-project-sme.md
├── Spawn general-purpose Opus agent
│   ├── Agent autonomously explores codebase (Glob, Grep, Read)
│   ├── NO hardcoded document paths — agent discovers what's relevant
│   └── Output documents which files were read and why
├── Read SME output
└── Token budget check
```

**CRITICAL — SME Autonomy**: The SME agent MUST NOT receive hardcoded project document paths. Instead:

- SME receives the problem statement and (optionally) research synthesis
- SME is spawned as `general-purpose` subagent type with Opus model
- SME autonomously explores the codebase using Glob, Grep, Read
- Instruct the SME: "Identify the MINIMUM files needed to answer: What exists relevant to this topic? Where are the integration points? What constraints apply? What must not be disrupted? Do NOT attempt to read the entire codebase."
- SME output documents which files it read and why

This makes the skill portable across any project.

### Stage 3A: Role Analysis — Task Tool Mode (`--scoped`)

**Execute this stage ONLY in `--scoped` mode. Skip entirely in `--exploratory` mode.**

```
Stage 3A: Role Analysis (--scoped)
├── Load references/role-product-manager.md
├── Load references/role-technical-architect.md
├── Load references/role-development-lead.md
├── Load templates/role-output.md
├── Construct 3 prompts using 4-part template
│   ├── Each receives: problem statement + research synthesis + SME output
│   └── Each writes to: $PROJECT_DIR/logs/brainstorm/{topic-slug}/{NN}-{role-slug}.md
├── Spawn all 3 agents in parallel via Task tool
│   ├── subagent_type: general-purpose
│   ├── model: opus
│   └── All 3 in a single message (parallel)
├── Read all 3 outputs
└── Token budget check (checkpoint if >55%)
```

**Output files (--scoped):** `02-product-manager.md`, `03-technical-architect.md`, `04-development-lead.md`

**CRITICAL**: Spawn all 3 agents in a single message with 3 Task tool calls. Do NOT spawn sequentially.

### Stage 3B: Role Analysis — Agent Teams Mode (`--exploratory`)

**Execute this stage ONLY in `--exploratory` mode. Skip entirely in `--scoped` mode.**

In `--exploratory` mode, 5 roles collapse to 4. The PM and Dev Lead merge into a Product & Delivery Lead. The Critical Analyst joins as an active AT teammate (not a sequential gatekeeper), challenging positions in real time throughout the debate.

```
Stage 3B: Role Analysis (--exploratory)
├── Load references/role-product-delivery-lead.md
├── Load references/role-technical-architect.md
├── Load references/role-critical-analyst.md
├── Load templates/role-output.md
├── Load templates/critic-output.md
├── Enter delegate mode as lead
├── Spawn 3 AT teammates with user's chosen model class (Opus or Sonnet)
│   ├── Product & Delivery Lead
│   ├── Technical Architect
│   └── Critical Analyst
├── Each teammate prompt includes:
│   ├── Role reference content
│   ├── SME output (from Stage 2)
│   ├── Problem statement + research synthesis
│   ├── Dual-output contract
│   ├── Peer debate directives
│   └── AT mitigation patterns (3 mandatory)
├── Wait for all teammates to complete
├── Read all 3 output files from logs/
└── Token budget check (checkpoint if >45%)
```

**Output files (--exploratory):** `02-product-delivery-lead.md`, `03-technical-architect.md`, `04-critical-analyst.md`

#### AT Teammate Prompt Structure, Configuration, and Failure Recovery

**MANDATORY**: Load `references/at-teammate-prompts.md` before constructing Stage 3B teammate prompts. It contains the full prompt structure (6 sections including dual-output contract, peer debate directives, 3 AT mitigation patterns, and Critic deferred-verdict directive), AT configuration (hardcoded settings), and failure recovery procedures.

### Stage 4: Critical Analyst — `--scoped` Mode ONLY (Opus, Sequential — Last)

**Execute this stage ONLY in `--scoped` mode. In `--exploratory` mode, the Critical Analyst is a Stage 3B teammate — skip Stage 4 entirely.**

```
Stage 4: Critical Analyst (--scoped only)
├── Load references/role-critical-analyst.md
├── Load templates/critic-output.md
├── Construct prompt using 4-part template
│   ├── CONTEXT includes ALL prior outputs:
│   │   ├── Problem statement + research synthesis
│   │   ├── SME output (01-project-sme.md)
│   │   ├── PM output (02-product-manager.md)
│   │   ├── Architect output (03-technical-architect.md)
│   │   └── Dev Lead output (04-development-lead.md)
│   └── OUTPUT: $PROJECT_DIR/logs/brainstorm/{topic-slug}/05-critical-analyst.md
├── Spawn general-purpose Opus agent
├── Read Critical Analyst output
└── Token budget check
```

**CRITICAL**: The Critical Analyst MUST receive ALL 4 prior outputs. This is the whole point — the Critic synthesizes and challenges everything.

### Stage 5: Synthesis (SHARED — mode-aware)

```
Stage 5: Synthesis
├── Read ALL agent output files from logs/brainstorm/{topic-slug}/
│   ├── --scoped: expect 5 files (01-project-sme, 02-product-manager, 03-technical-architect, 04-development-lead, 05-critical-analyst)
│   └── --exploratory: expect 4 files (01-project-sme, 02-product-delivery-lead, 03-technical-architect, 04-critical-analyst)
├── Verify expected file count matches mode (5 for --scoped, 4 for --exploratory)
├── If any output is missing or empty → re-spawn that agent once (max 1 retry)
├── If retry fails → document gap in synthesis under "Incomplete Coverage"
├── Load templates/synthesis-output.md
├── Write synthesis to $PROJECT_DIR/artifacts/brainstorm/{topic-slug}/synthesis.md
│   └── Include mode field in YAML header (mode: scoped | exploratory)
├── AskUserQuestion for user on open questions (iterative, 2-3 per round)
├── Critical Evaluation Gate (see below)
└── Token budget check (must be  "Your suggestion about [X] involves a technical claim / architectural approach that hasn't been validated against the codebase and research. I recommend a targeted follow-up with 2 focused agents (Technical Architect + Critical Analyst) to verify feasibility and stress-test the approach.
>
> This will spawn 2 Opus agents and consume additional token budget.
>
> [Run follow-up validation / Incorporate as-is with LOW confidence caveat]"

**Step 3 — If follow-up validation approved:**

1. Spawn 2 Opus agents in parallel (single message, 2 Task tool calls):
   - **Technical Architect** — validates the suggestion against the codebase and research:
     GOAL: Validate whether [{user_suggestion}] is technically feasible for this project.
     Include the Propose-Challenge-Refine reasoning depth instructions.
     Agent has access to Glob, Grep, Read for codebase exploration.
   - **Critical Analyst** — stress-tests the suggestion:
     GOAL: Challenge [{user_suggestion}]. Is this the simplest approach? What assumptions does it introduce? What would change the verdict?
     Include the Highest-Risk Assumption Focus reasoning depth instructions.
2. Use the same 4-part prompt template (GOAL/CONSTRAINTS/CONTEXT/OUTPUT)

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ashaykubal](https://github.com/ashaykubal)
- **Source:** [ashaykubal/essential-agents-skills](https://github.com/ashaykubal/essential-agents-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ashaykubal-essential-agents-skills-brainstorm
- Seller: https://agentstack.voostack.com/s/ashaykubal
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.