Brainstorm

Agent Teams Alternative: Brainstorming Team

In Agent Teams mode, form a brainstorming team where agents debate ideas in real-time. Dynamically select teammates based on topic analysis (Phase 0):

# CC 2.1.178+: one implicit team per session — no TeamCreate.
# Spawn teammates directly via Agent(name=...). Requires
# CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (set in ork.settings.json).

# Always include the system design lead
Agent(subagent_type="ork:workflow-architect", name="system-designer",
     team_name="brainstorm-{topic-slug}",
     prompt="""You are the system design lead for brainstorming: {topic}
     DIVERGENT MODE: Generate 3-4 architectural approaches.
     When other teammates share ideas, build on them or propose alternatives.
     Challenge ideas that seem over-engineered — advocate for simplicity.
     After divergent phase, help synthesize the top approaches.""")

# Domain-specific teammates (select 2-3 based on topic keywords)
Agent(subagent_type="ork:backend-system-architect", name="backend-thinker",
     team_name="brainstorm-{topic-slug}",
     prompt="""Brainstorm backend approaches for: {topic}
     DIVERGENT MODE: Generate 3-4 backend-specific ideas.
     When system-designer shares architectural ideas, propose concrete API designs.
     Challenge ideas from other teammates with implementation reality checks.
     Play devil's advocate on complexity vs simplicity trade-offs.""")

Agent(subagent_type="ork:frontend-ui-developer", name="frontend-thinker",
     team_name="brainstorm-{topic-slug}",
     prompt="""Brainstorm frontend approaches for: {topic}
     DIVERGENT MODE: Generate 3-4 UI/UX ideas.
     When backend-thinker proposes APIs, suggest frontend patterns that match.
     Challenge backend proposals that create poor user experiences.
     Advocate for progressive disclosure and accessibility.""")

# Always include: testability assessor
Agent(subagent_type="ork:test-generator", name="testability-assessor",
     team_name="brainstorm-{topic-slug}",
     prompt="""Assess testability for each brainstormed approach: {topic}
     For every idea shared by teammates, evaluate:
     - Can core logic be unit tested without external services?
     - What's the mock/stub surface area?
     - Can it be integration-tested with docker-compose/testcontainers?
     Score testability 0-10 per the evaluation rubric.
     Challenge designs that score below 5 on testability.
     Propose test strategies for the top approaches in synthesis phase.""")

# Optional: Add security-auditor, llm-integrator based on topic

Key advantage: Agents riff on each other's ideas and play devil's advocate in real-time, rather than generating ideas in isolation.

Fork pattern (CC 2.1.89 #1227; explicit since CC 2.1.232): All brainstorm agents are fork-eligible: prompts are <500 words, no custom model, no worktree. CC shares the parent's cached API prefix across forks, reducing cost by ~60%. Do NOT add model= to agent calls. Since CC 2.1.232 forking is on by default and subagent_type: "fork" selects it explicitly, so the eligibility conditions matter only for ordinary Agent() calls. See chain-patterns/references/fork-pattern.md.

Nested delegation (CC 2.1.172+): Teammates MAY be instructed to delegate a bounded sub-question to their declared sub-agents (e.g. backend-thinker → database-engineer to sanity-check a schema idea) instead of guessing inline. Keep chains ≤ 3 levels deep; divergent ideation itself stays flat — the parallel teammates above ARE the fan-out for independent ideas. See chain-patterns Pattern 9 (CC 2.1.172+).

Team teardown after synthesis:

# After Phase 5 synthesis and design presentation
# CC 2.1.178+: no TeamDelete — teammates wind down at turn end
# (press Ctrl+F twice to stop lingering background teammates).

# Worktree cleanup (CC 2.1.72) — for Tier 3+ projects that entered a worktree
# If EnterWorktree was called during brainstorm (e.g., Plan first → worktree), exit it
ExitWorktree(action="keep")  # Keep branch for follow-up implement

Fallback: If team formation fails, load Read("references/phase-workflow.md") and use standard Phase 2 Task spawns.

Partial results (CC 2.1.76, extended 2.1.246): Background agents that are killed (timeout, context limit) return responses tagged with [PARTIAL RESULT]. Since CC 2.1.246 an agent that stops at its maxTurns limit is ALSO reported as partial: its summary reads "stopped at its N-turn limit (partial result; continue it with SendMessage to the task-id)" and its output is marked partial instead of appearing finished. When collecting Phase 2 divergent ideas, check each agent's output for either shape. If present, include the partial ideas but note them as incomplete in Phase 3 feasibility. For the turn-limit shape, SendMessage to that agent's id with "continue from where you stopped" reuses its context; a re-spawn starts from zero and pays the prompt again. Never treat a turn-limited agent as finished.

Cross-session replies land in the parent (CC 2.1.248): when a subagent sends SendMessage to another session, the reply is delivered to the parent session's conversation, never to the subagent; a subagent sends and moves on, the parent reads the answer. Cross-session SendMessage / ListAgents also work on Bedrock, Vertex and Foundry and with telemetry disabled (CC 2.1.248).

PostCompact recovery: Long brainstorm sessions may trigger context compaction. The PostCompact hook re-injects branch and task state. If compaction occurs mid-brainstorm, check .claude/chain/state.json for the last completed phase and resume from the next handoff file (see Phase Handoffs table). Reactive compaction (CC 2.1.142+) now sizes the first summarize to the actual overflow, so mid-turn stalls are rare — no need to expect a second pass.

When context fills (CC 2.1.141+): Instead of ending the session, use the rewind menu's "Summarize up to here" to compress earlier turns while keeping recent context intact — a deliberate compaction point that pairs with the improved reactive compaction above.

Session recap (CC 2.1.108+): After idle periods, use /recap to restore conversational context alongside checkpoint-resume. Enabled by default since CC 2.1.110 (even with telemetry disabled).

Push notifications (CC 2.1.110+): For long brainstorm sessions, use PushNotification to alert when synthesis is complete (requires Remote Control with "Push when Claude decides").

Lighter alternative (CC 2.1.141+): Hooks can emit desktop notifications, window titles, and bells natively via the terminalSequence field in hook JSON output — no Remote Control required, no Anthropic round-trip. Ork's notification hooks (notification/desktop, notification/sound) already emit via terminalSequence (#1847, shipped).

Manual cleanup: To stop lingering background teammates, press Ctrl+F twice (foreground/Stop). Note: /clear (CC 2.1.72+) preserves background agents — only foreground tasks are cleared.

Teammate background tasks survive turn-end (CC 2.1.183): A background task started by a teammate is no longer killed when that teammate finishes its turn. Phase-2 teammates may safely kick off a long run_in_background task (e.g. a feasibility build) and let it outlive their own turn — the result is still collectable at synthesis. Pre-2.1.183 this required the lead to own the background task.

That claim does not cover auto-backgrounded work (#3448): a foreground Bash call the harness backgrounds on timeout is a different path. Its completion notice goes to the agent that spawned it, and if that agent already ended its turn on "I'll wait", the notice lands nowhere and the output is lost with zero logged errors. Two rules follow. The lead owns any research call whose documented runtime can approach the Bash timeout (tavily-research advertises 30-120s and real queries pass 180s). And no teammate ends a turn on "I'll wait for X" without either collecting X or handing ownership of X to the lead.

Key Principles

Running unattended with /goal

Set a completion condition with /goal (CC 2.1.139+, 2.1.143+ recommended for this skill) and this skill will keep working across turns until the condition is met. Works in interactive, -p, and Remote Control. The overlay panel shows live elapsed / turns / tokens.

Why 2.1.143+: Pre-2.1.143 /goal evaluator could fire while background shells or delegated subagents were still running — racing the parallel agents this skill spawns in Phase 2. Fixed in CC 2.1.143 (changelog: "/goal evaluator firing while background shells or delegated subagents are still running").

Example completion condition for this skill:

/goal until design.options_count >= 2 AND user_chose_option, or stop after 8 turns

Stops when: 2+ ranked design options presented and the user selects one (or after Phase 6 if running unattended via -p). Compatible with claude.ai Remote Control runs.

Quality Bar

Done means all of these hold:

• Phase 2 produced >=10 distinct ideas BEFORE any filtering, each surfaced as its agent returned
• Every idea past the keep/discard gate carries a one-line keep/discard/crash verdict
• Each surviving idea scores 0-10 on all 7 dimensions (simplicity included) plus one devil's-advocate challenge
• Synthesis narrows to 2-3 approaches with a trade-off table AND a per-approach test strategy
• Output ends with ranked options the user chooses from (or Phase 6 completes when running unattended via -p)

📜 Related Skills

• ork:architecture-decision-record - Document key decisions made during brainstorming
• ork:implement - Execute the implementation plan after brainstorming completes
• ork:explore - Deep codebase exploration to understand existing patterns
• ork:assess - Rate quality 0-10 with dimension breakdown
• ork:design-to-code - Convert brainstormed UI designs into components
• ork:component-search - Find existing components before building new ones
• ork:competitive-analysis - Porter's Five Forces, SWOT for product brainstorms

Picker fallback (#1795)

The picker stall reported in orchestkit#1795 was a schema break, not a CC input bug: questions with >4 options or a markdown field (the markdown key is not valid — the schema field is preview) fail AskUserQuestion validation, so the picker never renders. All skill questions conform to the schema (2–4 options, no preview on multiSelect), enforced by tests/skills/structure/test-askuserquestion-schema.sh. Separately, although the schema permits a preview field, current CC renders any question that uses one in a side-by-side picker layout where ↑/↓ keyboard navigation is dead (confirmed 2026-05-28). So skills now standardize on plain label + description only and no longer set preview. If you still hit a stall on a future CC build, ORK_ASK_FALLBACK=text remains as a defensive opt-in: the lifecycle/ask-fallback-injector hook then tells the assistant to pose options inline as a numbered list. Hook propagates globally — no per-skill edit needed.

References

Load on demand with Read("references/<file>"):