feat(ai-research-workflows): add /brainstorm command for codebase-aware feature ideation

[lsetiawan]

Summary

Add a /brainstorm command to the ai-research-workflows plugin that sits before /plan in the workflow. It takes a fuzzy idea and a codebase, explores the codebase for constraints + prior art, proposes 2–3 concrete framings with trade-offs, and lands a short feature-concept doc at .agents/brainstorm-<slug>.md that /plan can consume as input.

Motivation — gap in today's workflow

The current commands assume you already know what you want to build:

Command	Assumes
/research	You want to document existing code (strict documentarian rule: "document what IS, not what SHOULD BE")
/plan	You already have a defined feature direction
/experiment	You already have 2–3 candidate approaches
/prototype (v0.2.0 #89)	You already have one candidate approach to prove out end-to-end
/iterate-plan	A plan already exists

There is no command for the ideation step — turning "I have a vague idea, help me shape it into something plannable against this codebase" into a concrete feature concept. Users today either stretch /research (which breaks its documentarian identity) or ideate outside the workflow and dead-end when they return.

Proposed design

Command interface

• /brainstorm <fuzzy idea> — e.g., "/brainstorm something to track RSE contributor onboarding"
• /brainstorm <idea> @research-*.md — seed with existing research docs

Behavior

1. Codebase reconnaissance (parallel subagents, read-only):
   • Constraints: language(s), frameworks, dependency surface, test infrastructure
   • Prior art: related modules, similar features, extension points
   • Conventions: patterns the idea must fit
2. Interactive shaping (one question at a time, prefers multiple-choice):
   • Scope (MVP vs. full), users, success signals, explicit non-goals
3. Propose 2–3 framings with trade-offs, recommend one:
   • Each framing names the entry points (file:line), rough phase shape, main risk
4. Produce the artifact: .agents/brainstorm-<slug>.md using a new template with sections:
   • Idea (one sentence)
   • Codebase Context (constraints + prior art found, with file:line refs)
   • Framings Considered (2–3, with pros/cons)
   • Recommended Framing + reasoning
   • Explicit non-goals / out-of-scope
   • Suggested next command (almost always /plan <framing> or /experiment if genuine approach uncertainty surfaced)

Retreat paths

If this happens	Go to
Idea is too vague to frame	Ask user for a narrower problem statement; do not produce a doc
Codebase has no natural home for the idea	Report honestly; suggest the idea may belong in a new repo or as a plugin
Brainstorming surfaces genuine approach uncertainty	/experiment <approach A vs B> before /plan
Brainstorming surfaces a missing-context gap	/research <topic> first, then re-run /brainstorm

Relationship to other workflow phases

• Before /brainstorm: optionally /research if the codebase is unfamiliar
• After /brainstorm: usually /plan <recommended framing>; occasionally /experiment or /prototype when the framing itself has unknowns
• The /handoff and orchestrator state-discovery need to learn about brainstorm-*.md artifacts

Acceptance criteria

• commands/brainstorm.md exists with CSO ## When to use and # Retreat Paths sections per v0.2.0 conventions
• skills/research-workflow-management/assets/brainstorm-template.md exists and is registered in SKILL.md
• Running /brainstorm <idea> on a fresh repo:
  • Produces .agents/brainstorm-<slug>.md using the template
  • Includes file:line references to the codebase reconnaissance
  • Lists 2–3 framings with trade-offs
  • Names a recommended framing and the next command to run
• commands/plan.md accepts a @brainstorm-*.md reference the same way it accepts @research-*.md today, and pulls the recommended framing + non-goals into the plan's "Implementation Approach" and "What We're NOT Doing" sections
• Orchestrator's .agents/ state discovery recognizes brainstorm-*.md and suggests /plan as the natural next step when a brainstorm exists but no plan does
• Handoff template (handoff-template.md) includes a Brainstorm Docs artifact section
• README and SKILL.md quick-reference updated so the workflow is: Research → Brainstorm → Plan → (Experiment | Prototype) → Iterate-Plan → Implement → Validate → Optimize

Out of scope (explicitly)

• Auto-running /brainstorm when /plan is invoked without a clear direction — keep human-gated
• Ideation against non-code artifacts (Figma, PRDs, etc.)
• Multi-idea comparison in one run — one idea per brainstorm doc (file more if you want to compare)
• Any form of "creative writing" mode that does not ground in the codebase — brainstorm must read code

Dependencies & sequencing

• Targets v0.3.0, not the current v0.2.0 release
• Depends on v0.2.0 landing first (issues feat(ai-research-workflows): core infrastructure — workflow model, profiles, retreat paths #87, feat(ai-research-workflows): experiment redesign — worktree isolation #88, feat(ai-research-workflows): add prototype phase #89, feat(ai-research-workflows): validate redesign — empirical validation #90, feat(ai-research-workflows): make iterate-plan a floating utility #91, feat(ai-research-workflows): optimize phase, plan template, and docs #92, chore(ai-research-workflows): v0.2.0 prep — command triggers, retreat paths, private skill #93): reuses the CSO trigger convention, retreat-path convention, and /prototype distinction that v0.2.0 introduces
• Can begin brainstorming design (the meta-irony is noted) once feat(ai-research-workflows): core infrastructure — workflow model, profiles, retreat paths #87 (orchestrator refactor) is merged, since that PR establishes the thin-orchestrator pattern this command plugs into

Open questions to resolve during brainstorming of this issue

• Does /brainstorm dispatch codebase recon as parallel subagents from day 1, or synchronously read-then-propose? (Parallel is faster but introduces state-tracking needs.)
• Is the "feature concept" doc mutable via /iterate-plan, or is it immutable once the user moves to /plan? Current lean: immutable — treat it as a snapshot of the decision point.
• Should /brainstorm be available in the Standard Development profile, or only Full Research? Current lean: both — ideation applies at all complexity levels.

References

• v0.2.0 spec (local): .agents/spec-ai-research-workflows-v0.2.0.md
• Architect's recommendations (local): .agents/recommendations-ai-research-workflows-v0.2.0.md
• Related: feat(ai-research-workflows): core infrastructure — workflow model, profiles, retreat paths #87 (orchestrator refactor — blocker), feat(ai-research-workflows): add prototype phase #89 (/prototype — sibling phase), feat(ai-research-workflows): make iterate-plan a floating utility #91 (/iterate-plan floating — precedent for phase-agnostic commands)

[xsuryanshx]

Hi @lsetiawan — im interested in picking this up. Wanted to sanity-check the dependency chain and approach before opening PRs.

Proposed staging (3 PRs):

1. chore(ai-research-workflows): v0.2.0 prep — command triggers, retreat paths, private skill #93 — extract CSO ## When to use + add # Retreat Paths to existing commands. The orchestrator refactor in feat(ai-research-workflows): core infrastructure — workflow model, profiles, retreat paths #87 depends on this extraction, so it has to land first.
2. feat(ai-research-workflows): core infrastructure — workflow model, profiles, retreat paths #87 — rewrite orchestrator + SKILL.md around the 8-phase model, two profiles, and retreat-path table. Bumps plugin.json to 0.2.0.
3. feat(ai-research-workflows): add /brainstorm command for codebase-aware feature ideation #97 (this issue) — add /brainstorm command + brainstorm-template.md, wire plan.md to consume @brainstorm-*.md, update orchestrator state discovery, handoff template, and README ordering.

Design choices for /brainstorm (resolving the open questions in the issue):

• Synchronous reconnaissance for v1 — defer parallel subagents to v0.3.1 to avoid the state-tracking burden you flagged.
• Adapt patterns from the existing superpowers:brainstorming (https://github.com/obra/superpowers/tree/main/skills/brainstorming) skill (dialogue loop, 2–3 framings with trade-offs, hard approval gate) rather than take a runtime dependency on it — keeps the plugin standalone.
• Brainstorm doc is immutable once user moves to /plan (matches your current lean).
• Available in both profiles (Standard Development + Full Research).

Before I start: is anyone already in flight on #93 or #87? Happy to coordinate or split if so.