Brainstorm Sessions

A brainstorm session is a structured, multi-persona collaboration on a shared working document. One persona acts as the lead and owns the draft; the other participating personas review each round from their own perspective (architecture, security, QA, UX, …), challenge assumptions, raise risks, and approve sections. The session runs in rounds until the group converges, a budget limit is hit, or you end it manually. The output is a finished document (typically a PRD) attached to the project.

Brainstorms are driven by your running agent sessions: review and update prompts are delivered to the same agent sessions you see on the Teams Chat page, and the agents reply through their normal prompt loop.

Lifecycle at a glance

setup → seeding → active → (converging) → done
                                    └────→ cancelled

• setup / seeding — the session and its working draft are created; the lead receives a seeding prompt to flesh out the template.
• active — numbered rounds run: participants review, the lead integrates feedback.
• done — finalized; a clean final document is generated from the working draft.
• cancelled — ended without generating a final document.

Only one active brainstorm per project is allowed; starting a second one fails until the first reaches a terminal state.

Starting a brainstorm

From the UI, use the Brainstorm panel on the project's Teams Chat page.

Via the API:

POST /rest/v1/vibeflow/brainstorms

curl -X POST "$AXIOMCLOUD_URL/rest/v1/vibeflow/brainstorms" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=$AXIOMCLOUD_SESSION" \
  -d '{
    "project_id": 66,
    "topic": "Notifications revamp PRD",
    "lead_persona_key": "product_manager",
    "participating_personas": ["architect", "security_lead", "qa_lead"],
    "max_rounds": 5,
    "token_budget": 500000
  }'

On start, the system:

1. Creates the working draft (document type brainstorming) — either from the built-in template (Overview, Problem Statement, Requirements, Open Questions, Assumptions, Risks & Mitigations, Scope Boundaries, Decision Log) or as a copy of existing_document_id.
2. Advances to round 1 and fans out review prompts to the participating personas.
3. Sends the lead a seeding prompt to flesh out the initial sections.

Fan-out only reaches personas with a live agent session: the session must have a recent heartbeat, belong to the same project, and (when the initiator session has a branch) be on the same git branch. If several sessions exist for one persona, the one with the freshest heartbeat wins. Personas without a live session simply don't receive that round's prompt.

Persona roles and typed prompts

Agents receive brainstorm work as typed prompts (the message_type field tells the agent which contract to follow):

Reviewers tag every feedback item: [CHALLENGE], [RISK], [QUESTION], [SCOPE], [APPROVED], [ESCALATE], or [NEEDS_INPUT: @<persona_key>]. Follow-up answers use [ANSWER]; the lead flags unresolved disagreements with [DISAGREE: reason]. Tags are parsed server-side into tracked response items.

Review submissions are validated: the session must be active, belong to your organization, and each submission is capped at 10 KB. Document content embedded in prompts is sanitized (HTML comments stripped, wrapped as untrusted input), and persona feedback is reformatted into neutral structured items before reaching the lead — a compromised or prompt-injected response cannot smuggle directives into another persona's context.

Round lifecycle

Each round:

1. A snapshot of the draft is recorded and review prompts fan out to participants.
2. Participants submit tagged responses; directed questions become handoffs (at most 5 dispatched per round, deduplicated per target/section, chain depth capped at 2 — deeper chains auto-escalate to the human).
3. The lead receives the aggregated feedback (brainstorm_update), updates the draft, and logs decisions.
4. The controller evaluates convergence and either advances to the next round, escalates, or finishes.

Mechanics:

• Rounds advance automatically; there is a minimum 10-second gap between rounds and a hard cap of 10 rounds.
• Convergence score = resolved actionable items ÷ total actionable items (1.0 when nothing actionable). A session converges when there are no open items, every non-lead participant has [APPROVED] in the current round, no directed questions are pending, and (when the scope guard is on) the latest round has no active scope warnings.
• Open items (challenges, risks, questions, scope concerns) are tracked across rounds with resolution states (open, addressed, deferred, rejected).
• Dead-loop detection: if for 3 consecutive rounds items are raised at least as fast as they are resolved, the session is flagged as looping instead of grinding on.
• Conflicts (one persona [CHALLENGE]s a section another [APPROVED]s in the same round) are detected and surfaced.
• If a brainstorm stalls (e.g. a participant never responds), the force_advance_round MCP tool creates the next round record and re-fans-out review prompts.

Token budget

The session tracks output-token usage against token_budget:

• At 80% usage the session auto-pauses for human review.
• At 100% the controller force-converges instead of starting new rounds.

Scope guard

Enabled by default (scope_guard_enabled: false at start to disable). After each round the working draft is compared against the seed:

• Growth cap — more than 20 KB of growth in a round pauses the session.
• New sections — sections that were not in the original template are flagged.
• Requirements growth — a Requirements section growing more than 50% over the seed is flagged.
• Scope-creep language — phrases like "also", "while we're at it", "nice to have", "stretch goal" newly added to Requirements are flagged.
• Boundary violations — requirement bullets that overlap items listed under Out of Scope are flagged.

Warnings are recorded on the round, streamed as SSE events, and block convergence until the round is clean.

Ending a brainstorm

POST /rest/v1/vibeflow/brainstorms/{id}/end with:

• {"cancel": false, "output_type": "prd"} — finalize: the session transitions to done and a clean final document is generated from the working draft (output_type: prd (default) or general).
• {"cancel": true} — cancel: the session transitions to cancelled; no final document is generated.

Either way, the session's still-pending review/follow-up prompts are expired so they stop appearing in agents' work queues. Agents can equivalently call the end_brainstorm MCP tool.

curl -X POST "$AXIOMCLOUD_URL/rest/v1/vibeflow/brainstorms/12/end" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=$AXIOMCLOUD_SESSION" \
  -d '{"cancel": false, "output_type": "prd"}'

Real-time updates and observability

The UI subscribes to the project SSE stream (GET /rest/v1/vibeflow/projects/{id}/events, org-wide variant at /rest/v1/vibeflow/events) and renders brainstorm progress live. Brainstorm event types include state changes, round transitions, per-persona responses, document updates, scope warnings, convergence, token milestones, pause/resume, escalations, and handoffs.

The brainstorm detail response (GET /rest/v1/vibeflow/brainstorms/{id}) carries a progress block: who has responded this round, who is pending, who is up next, elapsed time, and — when an agenda was provided — per-topic progress.

Structured log events (brainstorm_round_complete, brainstorm_escalation, brainstorm_scope_warning, brainstorm_token_usage, brainstorm_convergence, brainstorm_lifecycle) are emitted for log-based metrics dashboards.

Adaptive polling cadence

The Teams Chat page keeps its background traffic low: brainstorm-detection polling backs off from 10s to 60s when no brainstorm is active and skips hidden browser tabs entirely; per-persona prompt tails load in one batched request; and the sessions poller only runs while the chat surface is actually visible (with an immediate refresh when you return to the tab). Live round-by-round updates come from the SSE stream, not from polling.

Limitations

• One active brainstorm per project.
• Prompts fan out only to heartbeat-verified agent sessions (and only those on the initiator's git branch when one is set) — personas without a live session are silently skipped for that round; restart their session and the next round will include them.
• Hard cap of 10 rounds; minimum 10 seconds between rounds.
• Review submissions are capped at 10 KB each.
• The lead and controller own the working draft — reviewers never edit documents directly, and agents must not create new documents during a brainstorm.