agents-fleet

Appearance

01 — Brainstorming: Pre-Feature Deep Brainstorming Workflow ​

Plan slug: i-want-to-ea3316Stage: 1 of 7 — brainstorm Date: 2026-05-21

What ​

A new adversarial multi-agent brainstorming capability that produces a rich shared-understanding artifact before a feature enters the existing /feature design pipeline. Two surfaces:

  1. /brainstorm "<topic>" — standalone slash command that runs the brainstorming workflow end-to-end and writes its artifacts to .plans/<slug>/. A user can run many of these independently over days/weeks without committing to a /feature build.
  2. /feature deep brainstorm phase — when invoked without a pre-existing brainstorm artifact, Phase 1 of /feature uses the same brainstorming workflow (replacing the current 3-question preQuestions pass) for a much deeper grilling. When a brainstorm artifact does exist, /feature accepts a --from-brainstorm <slug> flag to start from that artifact and skip its own Phase 1 entirely.

The brainstorming engine itself:

  • Spawns 3 parallel adversarial "inquisitor" workers, each with a distinct angle:
    • inquisitor-ux — user-experience, intent, scope, success criteria
    • inquisitor-technical — feasibility, integration, performance, constraints
    • inquisitor-edge-cases — failure modes, security, rollback, hidden assumptions
  • Each inquisitor generates a batch of questions from its angle. The coordinator collects, deduplicates, and prioritizes them, then asks the user one at a time via the deterministic ask_user grilling pattern (the T-153 mechanism we just shipped).
  • After the first batch is answered, the coordinator runs at least N=2 rounds of grilling (the "minimum N" from the hybrid termination model). Between rounds it can either re-spawn fresh inquisitors with the new answers, or use the existing answers to formulate sharper follow-ups.
  • After the minimum rounds, the coordinator asks "Should I keep grilling or summarize?" each round. The user types summarize (or similar) to exit the loop.
  • On exit, the coordinator synthesizes everything into the two artifacts below.

Produces two artifacts:

  • .plans/<slug>/00-brainstorming.md — human-readable narrative. Vision, user stories, constraints, open questions, full Q&A transcript, per-inquisitor findings, assumptions. Reads like a design discussion summary.
  • .plans/<slug>/00-brainstorming.context.md — structured machine-readable file (YAML frontmatter or fenced YAML blocks) holding the canonical question/answer pairs, assumption ledger, and "carry-forward to Phase 2" hints. /feature reads this file to seed its requirements/research/design phases.

Why ​

Today's /feature Phase 1 asks 3 fixed preQuestions and immediately writes a brainstorm artifact. This works for clear, small features but is shallow for complex/architectural ones where the real unknowns only surface after several follow-up rounds. Two pain points:

  1. Shallow shared understanding → downstream phases (research, design, validation) hit assumptions the user never actually confirmed, producing plans that miss the mark.
  2. No standalone exploration mode → today a user can't just "talk through" an idea without committing to the full 7-phase pipeline producing 7 artifacts. People want to brainstorm freely first, then later pick a brainstorm to formalize.

The adversarial multi-agent angle is the key value-add over a single coordinator grilling — three angles in parallel surface questions a single agent would miss (UX agent asks "what does success feel like to the user?", technical asks "what's the contract with the existing TaskStore?", edge-cases asks "what happens when the worker dies mid-grill?"). Synthesis through the coordinator means the user still sees a single coherent question stream, not three competing inquisitors.

Where ​

New code:

  • src/skills/bundled/workflows/brainstorm.workflow.md — the new workflow definition with stages: spawn-inquisitors → collect-and-prioritize-questions → grill-round (looped) → decide-continue-or-summarize → synthesize-artifacts. Each stage has a sibling brainstorm/<stage>.prompt.md.
  • src/skills/bundled/workflows/brainstorm/*.prompt.md — per-stage prompt templates (5 files).
  • src/skills/bundled/roles/inquisitor-ux.role.md, inquisitor-technical.role.md, inquisitor-edge-cases.role.md — the three inquisitor roles (agent_type: explorer for read-only investigation + question generation; they report questions back via report_to_coordinator rather than writing files).
  • src/commands/brainstormCommand.ts (+ .test.ts) — the /brainstorm slash command handler. Pattern follows featureCommand.ts (workflow-driven via runWorkflowStages).

Modified code:

  • src/commands/featureCommand.ts — add --from-brainstorm <slug> flag; when set, skip Phase 1 entirely and load .plans/<slug>/00-brainstorming.context.md as Phase 2 seed input.
  • src/commands/registry.ts — register /brainstorm in the Workflows category alongside /feature and /research.
  • src/skills/bundled/workflows/feature-pipeline.workflow.md — Phase 1 (brainstorm) gains an optional "deep mode" trigger; when triggered, runs the brainstorm workflow inline instead of the 3 preQuestions. Probably surfaced via a /feature --deep-brainstorm "<topic>" flag.
  • docs/commands-manual.md — document /brainstorm + --from-brainstorm + --deep-brainstorm.

Touches lightly:

  • WorkflowStage type (src/skills/types.ts) — may need a new field if we want to express "loop this stage N times" declaratively. Alternatively the loop is implemented in the command handler (see Risks below).

How (high-level) ​

Step-by-step coordinator orchestration:

  1. Spawn inquisitors in parallel (spawn_worker × 3). Each gets the topic + project context + a role-specific system prompt (e.g., inquisitor-ux: "You only ask questions about user intent, scope, success criteria, edge user behaviors. Generate 3-5 distinct questions and return them via report_to_coordinator. Do NOT write files.").
  2. Collect questions — workers finish quickly (~30-60s each, no file writes). Coordinator harvests their partial_result payloads from the message bus.
  3. Dedupe + prioritize — coordinator scores questions for novelty/criticality (heuristics: angle diversity, dependency on unclear concepts, blocking nature). Top ~5-8 questions per round.
  4. Grill round — coordinator uses the deterministic coordinator.askUser({question}) grilling pattern (the T-153 fix path) to ask each prioritized question one at a time. Each answer is appended to a transcript buffer in FleetStateStore (or session-local memory).
  5. Check termination — if rounds < N_min (default 2), automatically continue to step 1 with new context (the inquisitors are re-spawned with the accumulated answers as context for fresher questions). If rounds ≥ N_min, the coordinator asks the user "keep grilling or summarize?" via askUser with choices: ['keep grilling', 'summarize']. On summarize, jump to step 6.
  6. Synthesize artifacts — coordinator composes 00-brainstorming.md (narrative + transcript) and 00-brainstorming.context.md (structured Q&A + assumptions + carry-forward hints). Writes both via the create tool.
  7. Done — /brainstorm finishes. If invoked from /feature --deep-brainstorm, /feature then continues to Phase 2 using the .context.md as seed.

Resumability: the artifact pair lives in .plans/<slug>/ like any other plan, so the brainstorm survives restarts. /feature --from-brainstorm <slug> is just a file existence check + load.

Risks ​

  1. Loop expressiveness in the workflow runner — the current runWorkflowStages runs each stage exactly once. A "loop this stage until user says stop" semantics isn't first-class. Mitigation: implement the loop inside brainstormCommand.ts rather than as a declarative workflow construct. The workflow file becomes more of a "stage list reference"; the handler drives the actual iteration. Trade-off: less declarative than /feature, but avoids touching the runner core.

  2. Inquisitor cost — 3 parallel explorer workers per round × N rounds × 1 brainstorm. For a 4-round session that's 12 worker spawns just for questions. Mitigation: cap inquisitors to 1 round only (round 1), and subsequent rounds use the coordinator's own follow-up questions seeded by prior answers. This makes round 1 expensive but rounds 2+ cheap.

  3. askUser hangs under --unattended — known latent bug surfaced in the T-153 explorer report: CoordinatorEngine.askUser() doesn't honor state.session.unattended, so /brainstorm --unattended would hang on the first question. Mitigation: must fix the askUser unattended self-research short-circuit before /brainstorm ships, OR /brainstorm explicitly refuses --unattended. Adding to "follow-up tasks" in Phase 7.

  4. Question fatigue — 8 questions × 3+ rounds = potentially 24+ questions before summarize. Users may quit early without summarizing properly. Mitigation: the "keep grilling or summarize?" gate appears every round after N_min, with the default answer being summarize. Also: progress bar "Round 3 of grilling — 6 questions asked". Also: allow the user to type a free-text answer to ANY question that says "this question is irrelevant" so the coordinator drops it.

  5. Artifact schema drift — 00-brainstorming.context.md is a new schema downstream phases consume. If we change the schema later, existing brainstorm artifacts break. Mitigation: include a schema_version: 1 field in the YAML; the loader in /feature --from-brainstorm checks it and warns on mismatch.

  6. Inquisitor quality — explorers without strong system prompts will generate vague/repetitive questions. Mitigation: high-quality role files for each inquisitor with concrete few-shot examples of good questions per angle. Reuse the agents-fleet-conventions skill so they ask domain-aware questions.

  7. Topology assumption — depends on hub topology (workers report only to coordinator). Under mesh, inquisitors could spam each other or the user. Mitigation: brainstorm workflow declares topology: hub in its frontmatter and the activator enforces it for the workflow's duration.

  8. Integration with existing /feature Phase 1 grilling — we already added preQuestions for Phase 1 (T-153). Deep-brainstorm would replace those, not extend them. Need to be clear in docs whether /feature without --deep-brainstorm runs the (light) preQuestions or the (heavy) brainstorm workflow by default. Mitigation: default stays as today's light grilling; --deep-brainstorm opts in. Power users can set a config flag to make deep brainstorm the default.

Assumptions ​

  • ⚠️ ASSUMPTION: N_min defaults to 2 rounds — REASON: enough to surface follow-ups based on the first batch of answers without being exhausting. User can override via --rounds <n> flag. Confirm in Phase 2 (requirements).
  • ⚠️ ASSUMPTION: Inquisitor agent_type is explorer (read-only, generates questions only, no file writes) — REASON: matches the read-only nature of question generation and avoids the worker-output-empty issue we've seen with reviewer. Could be general-purpose if we want to allow them to peek at additional files mid-question-generation.
  • ⚠️ ASSUMPTION: Artifacts live in .plans/<slug>/ with prefix 00- (not 01- like /feature Phase 1) — REASON: signals that brainstorming is "Phase 0" — pre-feature. /feature artifacts start at 01-. This keeps both standalone-brainstorm and within-feature-brainstorm artifacts in the same numbering convention.
  • ⚠️ ASSUMPTION: /feature --from-brainstorm <slug> loads <slug>/00-brainstorming.context.md and uses it as Phase 2 seed input — REASON: keeps the artifact location predictable. If the file doesn't exist, error with actionable message ("run /brainstorm first or omit --from-brainstorm").
  • ⚠️ ASSUMPTION: The --unattended issue is a follow-up, NOT a blocker — REASON: /brainstorm is inherently interactive; --unattended is non-sensical for it. We'll refuse the combination with a clear error and fix askUser unattended behavior in a separate task (already on the deferred WIP list).
  • ⚠️ ASSUMPTION: Loop is implemented in brainstormCommand.ts, not declared in the workflow file — REASON: the workflow runner doesn't have first-class loop semantics yet, and adding them is out of scope for this feature. The command-level loop is a pragmatic v1.
  • ⚠️ ASSUMPTION: No new MCP server tools are needed — REASON: inquisitors use only grep/glob/view (already part of explorer agent_type). No external integrations.
  • ⚠️ ASSUMPTION: Schema version in .context.md is enough for forward compatibility — REASON: standard pattern; downstream loaders gracefully degrade or error out cleanly on mismatch. Confirm in DoD phase.

Open Questions for Phase 2 (Requirements) ​

  • ⚠️ OPEN QUESTION: What's the exact YAML schema for 00-brainstorming.context.md? (Q/A pairs, assumptions, carry-forward hints — but specific keys?)
  • ⚠️ OPEN QUESTION: Should the /brainstorm command have its own slug-naming convention (e.g., brainstorm-<topic>-<hash>), or share the /feature slug format?
  • ⚠️ OPEN QUESTION: When /feature --deep-brainstorm runs, does it create a separate brainstorm slug then immediately consume it, or does it brainstorm inside the feature slug's plan dir?
  • ⚠️ OPEN QUESTION: Should the askUser unattended short-circuit fix be in-scope for this feature, or a strict pre-req delivered separately?
  • ⚠️ OPEN QUESTION: Should the brainstorm artifact include a "confidence score" per Q/A (e.g., user marked their answer as "guess" vs "certain")? Useful for downstream phases to flag risky assumptions.

Pre-stage user answers (from grilling) ​

Q: What exactly should this feature do? What's the expected behavior? A: I want to have workflow for brainstorming and align user and agent on what we will build by the agent asking all the questions it needs to prepare him to do the design and architecture when we start building.

Q: Which parts of the existing system do you expect this to affect? A: This should be a new workflow than then allows the /feature workflow to use the collaterals generate from it. or a new /command that continues. But this should be exhaustive brainstorming

Q: Are there any constraints or things that must NOT change? A: no

Q: How should this brainstorming feature be surfaced? A: Both — a standalone /brainstorm command AND /feature should also be able to do deep brainstorm. If a brainstorm was done standalone, I should be able to tell /feature to start from one (in case I have many brainstorms already done).

Q: When does the grilling stop? A: D — Hybrid: minimum N rounds, then agent asks "should I keep grilling or summarize?" each round until user says summarize.

Q: What 'shape' of grilling do you want? A: B — Adversarial multi-agent: 3 parallel inquisitor workers (ux, technical, edge-cases) generate questions in parallel; coordinator synthesizes and asks user one at a time.

Q: What artifact(s) should the brainstorm phase produce, and how does /feature consume them? A: B — Two files: 00-brainstorming.md (human-readable narrative) + 00-brainstorming.context.md (structured Q&A + assumptions for downstream phases to programmatically consume). /feature reads the .context.md.

Phase 1 complete. Ready for Phase 2 (requirements).