/brainstorm Feature Proposal

Status: 📋 Plan complete — execution pending Target version: v0.24.0 (minor — new user-facing feature) Source slug: i-want-to-ea3316Generated by: /feature adversarial workflow run on agents-fleet itself (dogfooding)

This directory contains the full design plan for the /brainstorm pre-feature workflow — a parallel, adversarial, multi-agent grilling loop that helps users surface unknown assumptions before a /feature run.

Read in order

#	File	Purpose	Size
1	01-brainstorming.md	Concept + design space exploration	16 KB
2	02-requirements.md	FR-1..20, IR-1..10, NFR-1..19, OOS, RES-1..6	21 KB
3	03-research.md	4 parallel explorers + critic → DEC-1..DEC-8 + FR-21..25 amendments	28 KB
4	04-technical-design.md	3 designers + critic → DEC-9..DEC-18 chosen hybrid	37 KB
5	05-tasks.md	44 atomic tasks, 3-PR breakdown, ~40h critical path	52 KB
6	06-definition-of-done.md	Checkable DoD covering every FR/IR/NFR/risk	22 KB
7	07-decisions.md	FINAL ledger — single source of truth	24 KB

If you only have time for one file, read 07-decisions.md — it consolidates the entire plan into one document with citations back to the others.

The TL;DR

Ship /brainstorm "<topic>" as a single-file command (~380 LOC) that:

• Spawns 3 explorer-class inquisitor workers (inquisitor-ux, inquisitor-technical, inquisitor-edge-cases) in parallel via the coordinator.
• Harvests their JSON partial_result payloads via a second MessageBus.subscribe('coordinator', handler) (verified multi-handler support).
• Grills the user one question at a time via the T-153 askUser path.
• Runs N rounds (default 2, range 1-10) with a "summarize / keep grilling" termination gate.
• Writes a dual artifact (00-brainstorming.md narrative + 00-brainstorming.context.md structured YAML) plus .brainstorm-complete sentinel — all atomic with mode: 0o644.
• --agents <n> flag (0-3) provides a single-coordinator escape hatch satisfying OOS-14 multi-agent ROI A/B with day-1 telemetry.
• --deep-brainstorm runs brainstorm INLINE as /feature Phase 1 (writes 01-brainstorming.md in feature slug). No sibling-slug chain.
• --from-brainstorm <slug> reads a standalone brainstorm into a fresh /feature Phase 2.
• Bonus security wins that ship with PR-1 (independently shippable): SEC-3 path-traversal fix backported to /feature --resume, and FR-21 fix for the askUser unattended-hang latent bug.

Execution plan

The plan ships as 3 PRs (~70-90h total, ~40h critical path):

1. PR-1 (Foundation, ~25-30h): tolerantJson + projectContext extract + planDir hardening (SEC-3 fix) + FR-21 fix + 3 role files + workflow + brainstormContext util. Independently shippable as security/infrastructure improvements.
2. PR-2 (Core + integration, ~25-35h): brainstormCommand itself + --from-brainstorm + --deep-brainstorm inline.
3. PR-3 (Tests + docs + release, ~20-25h): integration tests + telemetry + CHANGELOG + release.

How this plan was produced

The plan was produced by running /feature on agents-fleet itself (dogfooding), starting from the topic "I want to extend /feature so we can iterate before with the user via multiple agents that grill the user with questions until we have a robust description and understanding to proceed". The 7-stage workflow ran on top of v0.23.3 — the same release that fixed the T-153 parser bug whose absence had been making /feature Phase 1 feel non-deterministic. Stages 3 (Research) and 4 (Design) used parallel adversarial workers + a critic to surface contradictions that single-agent grilling would have missed (which is also the case the feature itself makes).