with one click
brainstorm
// Full execution protocol for MODE: BRAINSTORM -- structured discovery dialogue, approach selection, spec drafting, QA gate selection, and transition handling.
// Full execution protocol for MODE: BRAINSTORM -- structured discovery dialogue, approach selection, spec drafting, QA gate selection, and transition handling.
Guidelines for safe subprocess calls in opencode-swarm. Load before adding, modifying, or reviewing any file that calls spawn, spawnSync, bunSpawn, or child_process. Covers the six required properties, Windows portability, _internals DI seam pattern, and verification grep.
Guidelines for writing, organizing, and maintaining tests in the opencode-swarm repository. Covers framework rules (bun:test), mock isolation, CI pipeline structure, file placement, and anti-patterns that break cross-platform CI. Load this skill before writing or modifying any test file.
Apply when converting test files from mock.module('node:child_process') to _internals DI seam pattern. Guides the complete migration: adding spawnSync/_internals to source files, converting test files, adding proper beforeEach/afterEach save/restore lifecycle, mockReset() cleanup, and temp directory cleanup. Prevents mock.module leaks across Bun's shared test-runner process.
Full execution protocol for MODE: PLAN -- plan creation, external plan ingestion, QA gate persistence, task granularity, and traceability checks.
Full execution protocol for MODE: CLARIFY -- structured clarification funnel with critic review before surfacing user decisions.
Full execution protocol for MODE: CLARIFY-SPEC -- resolving spec clarification markers and maintaining spec/planning alignment.
| name | brainstorm |
| description | Full execution protocol for MODE: BRAINSTORM -- structured discovery dialogue, approach selection, spec drafting, QA gate selection, and transition handling. |
This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
Activates when: user invokes /swarm brainstorm; OR uses phrases like "brainstorm", "let's think through", "think this through with me", "workshop this idea"; OR the problem is fuzzy/exploratory and the user has not yet written (or does not want to directly dictate) a spec.
Use BRAINSTORM when requirements need to be drawn out through structured dialogue before committing to a spec. Use SPECIFY when the user has already articulated clear requirements.
MODE: BRAINSTORM runs seven phases in strict order. Do not skip phases. Do not collapse phases. Each phase has a clear entry signal and a clear exit signal.
Phase 1: CONTEXT SCAN (architect + explorer, parallel).
the active swarm's explorer agent to map the relevant portion of the codebase. Scope the explorer to the area most likely affected by the topic..swarm/spec.md, .swarm/plan.md, and .swarm/knowledge.jsonl entries that are relevant.Phase 2: DIALOGUE (architect ↔ user).
Phase 3: APPROACHES (architect, optionally with SME).
the active swarm's sme agent for domain research first.Phase 4: DESIGN SECTIONS (architect).
Phase 5: SPEC WRITE + SELF-REVIEW (architect + reviewer).
- Generate .swarm/spec.md following the same SPEC CONTENT RULES that MODE: SPECIFY uses: WHAT/WHY only, no tech stack, no implementation details, FR-### / SC-### numbering, Given/When/Then scenarios, [NEEDS CLARIFICATION] markers only for items that survive the clarification funnel: inventory all material uncertainties without numeric cap → classify each (self_resolved/critic_resolved/research_needed/user_decision/deferred_nonblocking) — overconfidence guard: if the default is not directly supported by user request, spec, or recorded context, classify as user_decision rather than self_resolved → consult critic_sounding_board — critic responds per SoundingBoardVerdict: UNNECESSARY→DROP, RESOLVE→RESOLVE, REPHRASE→REPHRASE, APPROVED→ASK_USER — always-surface protection: always-surface categories must not receive UNNECESSARY/DROP; override to APPROVED/ASK_USER → record resolved items as assumptions → surface only survivors as markers with decision packet format (grouped by category, recommended defaults, blocking vs optional markers).
the active swarm's reviewer agent for an independent review of the draft spec. Reviewer must flag: requirements that encode HOW, untestable requirements, missing edge cases, silent assumptions..swarm/spec.md.Phase 6: QA GATE SELECTION (architect, dialogue only). Now ask the user which QA gates to enable for this plan -- do not select on their behalf.
Present the eleven gates with their defaults (DEFAULT_QA_GATES) as a single user-facing question. Offer the user a one-shot choice: accept defaults, or customize. The eleven gates are:
critic, reviewer, sme, test_engineer, explorer) at project scope, collects CouncilMemberVerdict objects, and calls write_final_council_evidence. This is not General Council mode and does not require council.general.enabled.One question, one message, defaults pre-stated. Wait for the user's answer.
If the user answered the gate question, immediately follow up with ONE more question: "How many coders should run in parallel? (default: 1, range: 1-4)" -- if the user says a number > 1, also write a ## Pending Parallelization Config section to .swarm/context.md alongside the gate selection:
## Pending Parallelization Config
- parallelization_enabled: true
- max_concurrent_tasks: <user's number>
- council_parallel: false
- locked: true
- recorded_at: <ISO timestamp>
If the user accepts the default (1), skip writing this section entirely -- serial execution is the default and needs no config.
After asking the parallelization question (regardless of whether the user chose serial or parallel), immediately follow up with ONE more question: "Commit frequency for completed tasks? (default: phase-level only; optional per-task checkpoint commit after each task completion)".
If the user chooses per-task commits, write this section to .swarm/context.md:
## Task Completion Commit Policy
- commit_after_each_completed_task: true
- recorded_at: <ISO timestamp>
If the user keeps the default phase-level behavior, do not write this section.
GATE SELECTION IS MANDATORY — these thoughts are WRONG and must be ignored: ✗ "I'll use the defaults — they're probably fine" → WRONG: defaults are not the user's decision. The user must be asked every time. ✗ "The user didn't mention gates, so defaults are fine" → WRONG: silence is not consent. The gate dialogue is not optional. ✗ "I'll handle it in MODE: PLAN after the spec is done" → WRONG: ## Pending QA Gate Selection must exist in context.md BEFORE save_plan is called. save_plan will reject with QA_GATE_SELECTION_REQUIRED if this section is absent. ✗ "This feature is simple — gates are obvious" → WRONG: complexity does not exempt this step. Gate selection is mandatory for ALL plans. ✗ "I already know which gates are right for this project" → WRONG: the architect does not configure gates. The user configures gates. Always ask. ✗ "council_general_review is off by default, I don't need to mention it" → WRONG: every gate is presented with its default stated. The user opts in or accepts the default explicitly.
MANDATORY PAUSE: Do NOT write the spec summary (step 7). Do NOT suggest next steps. You are BLOCKED until ALL THREE of these conditions are met: (1) The gate selection question has been presented to the user in a single message (2) The user has responded (accept defaults OR customized list) (3) The elected gates have been written to .swarm/context.md under "## Pending QA Gate Selection"
Do NOT call set_qa_gates yet — plan.json does not exist at this point. Once the user answers, write the elected gates to .swarm/context.md under a new section:
## Pending QA Gate Selection
- reviewer: <true|false>
- test_engineer: <true|false>
- sme_enabled: <true|false>
- critic_pre_plan: <true|false>
- sast_enabled: <true|false>
- council_mode: <true|false>
- hallucination_guard: <true|false>
- mutation_test: <true|false>
- council_general_review: <true|false>
- drift_check: <true|false>
- final_council: <true|false>
- recorded_at: <ISO timestamp>
MODE: PLAN applies these after save_plan succeeds via set_qa_gates.
.swarm/context.md (NOT yet persisted to plan.json).Phase 7: TRANSITION.
[NEEDS CLARIFICATION] markers.PLAN (go to MODE: PLAN and write plan.md) or CLARIFY-SPEC (resolve remaining markers first).BRAINSTORM RULES:
save_plan succeeds and are ratchet-tighter from that point — once persisted you cannot undo them later in the session.