magi-researchers

Research Brainstorm Skill

Description

Generates and cross-validates research ideas using Gemini and Codex in parallel, then synthesizes results with Claude.

Usage

/research-brainstorm "research topic" [--domain physics|ai_ml|statistics|mathematics|paper] [--weights '{"novelty":0.4,...}'|adaptive] [--depth low|medium|high|max|auto] [--personas N] [--claude-only] [--substitute "Gemini -> Opus"]

Arguments

• $ARGUMENTS — The research topic and optional flags:
• --domain — Research domain (physics, ai_ml, statistics, mathematics, paper). Auto-inferred if omitted.
• --weights — Scoring mode for finding ranking:
• Omitted (default — holistic mode): Claude ranks findings based on its own expert judgment, with detailed rationale for each ranking position. No numeric dimension weights are used.
• JSON object (e.g., '{"novelty":0.4,"feasibility":0.2,"impact":0.2,"rigor":0.1,"scalability":0.1}'): Weighted scoring — dimensions novelty, feasibility, impact, rigor, scalability with values summing to 1.0.
• adaptive: Claude analyzes the prompt, adjusts domain defaults, and asks for user confirmation before scoring (see Step 0c).
• --depth — Controls review depth (default: medium):
• low — Skip cross-review, go directly to synthesis
• medium — Standard one-shot cross-review (current behavior)
• high — Cross-review + evidence anchoring + adversarial debate round
• max — Hierarchical MAGI-in-MAGI: N persona subagents run parallel mini-MAGI pipelines, then meta-review + evidence anchoring + adversarial debate across all perspectives
• auto — Adaptive depth: starts as medium, auto-escalates to high or deep based on cross-review disagreement signals (see T12)
• --personas N|auto — Number of domain-specialist subagents for --depth max (default: auto, range: 2-4). When auto, Claude analyzes the topic to determine the optimal persona count. Ignored for other depth levels.
• --claude-only — Replace all Gemini/Codex MCP calls with Claude Agent subagents. Use when external model endpoints are unavailable or for a Claude-only workflow. Two subagents with distinct cognitive styles (Creative-Divergent and Analytical-Convergent) ensure perspective diversity.
• --substitute "Agent -> Opus" — Replace a specific MAGI agent with a Claude (Opus) subagent. Accepted forms: "Gemini -> Opus", "Codex -> Opus". Can be specified multiple times. Use when a specific model hits rate limits but other models are still available. The substituted agent uses the same cognitive style mapping as --claude-only mode. If both agents are substituted, functionally equivalent to --claude-only. Mutually exclusive with --claude-only (if both provided, --claude-only takes precedence).

Instructions

MCP Tool Rules

• Gemini: Use the following model fallback chain. Try each model in order; if a call fails (error, timeout, or model-not-found), retry with the next model:
• model: "gemini-3.1-pro-preview" (preferred)
• model: "gemini-2.5-pro" (fallback)
• Claude Opus subagent (last resort — skip Gemini MCP tool, spawn an Agent subagent with T1-CD cognitive style, same as --substitute "Gemini -> Opus")
• Codex: Use model: "gpt-5.4" for all Codex MCP calls. Use mcp__codex-cli__brainstorm for ideation, mcp__codex-cli__ask-codex for analysis/review. If Codex fails 2+ times, fall back to a Claude Opus subagent with T1-AC cognitive style (same as --substitute "Codex -> Opus").
• File References: Use @filepath in the prompt parameter to pass saved artifacts (e.g., @brainstorm/codex_ideas.md)

instead of pasting file content inline. The CLI tools read files directly, preventing context truncation.

• Web Search: Use web search freely whenever factual verification, recent developments, or literature context would strengthen the discussion:
• Claude: Use the WebSearch tool directly
• Gemini: Add search: true to mcp__gemini-cli__ask-gemini or mcp__gemini-cli__brainstorm calls
• Codex: Add search: true to mcp__codex-cli__ask-codex or mcp__codex-cli__brainstorm calls
• When to search: prior work verification, methodological precedents, dataset/library availability, related approaches, fact-checking quantitative claims
• Claude-only mode: Claude Agent subagents cannot use WebSearch. The main Claude agent should search beforehand and include findings in the subagent prompt.

Claude-Only Mode

When --claude-only is active, all Gemini/Codex MCP tool calls are replaced with Claude Agent subagents (subagent_type: general-purpose). The table below maps each original call to its replacement:

| Original Call | Replacement | Cognitive Style | |---|---|---| | mcp__gemini-cli__brainstorm | Agent subagent A | Creative-Divergent: unconventional connections, "What if?" scenarios, wide exploration, questioning assumptions | | mcp__codex-cli__brainstorm | Agent subagent B | Analytical-Convergent: step-by-step feasibility, established methodologies, deep evaluation, practical constraints, risk assessment | | mcp__gemini-cli__ask-gemini | Agent subagent A | Same Creative-Divergent style | | mcp__codex-cli__ask-codex | Agent subagent B | Same Analytical-Convergent style |

Key rules for claude-only mode:

1. File access: Subagents use the Read tool to access files (no @filepath syntax).
2. Output filenames: Keep original names (gemini_ideas.md, codex_ideas.md, etc.) — add a header > Source: Claude Agent subagent (claude-only mode, {style}) to each output file.
3. Independence: Both subagents are spawned simultaneously so neither can see the other's output.
4. --depth max internal subagents: Within each persona's mini-MAGI pipeline, use Expansive Explorer (replaces Gemini) and Grounded Builder (replaces Codex) cognitive styles to maintain internal diversity.

Agent Substitution (--substitute)

When --substitute is used, only the specified agent's MCP calls are replaced with Claude Agent subagents. The replacement uses the same cognitive style and prompt structure as --claude-only mode:

| Substituted Agent | Replacement Cognitive Style | |---|---| | Gemini → Opus | Creative-Divergent (same as claude-only Gemini replacement) | | Codex → Opus | Analytical-Convergent (same as claude-only Codex replacement) |

Key differences from --claude-only:

• Only the substituted agent's calls change; the other agent continues using its MCP tool normally.
• Both substituted (Claude subagent) and non-substituted (MCP) calls can still execute in parallel.
• File naming is unchanged (gemini_ideas.md, codex_ideas.md, etc.). Add header > Source: Claude Agent subagent (substituted for {Agent}, {CognitiveStyle}) to files written by substituted agents.
• For --depth max internal subagents: the substituted agent uses Expansive Explorer (if Gemini) or Grounded Builder (if Codex).

Substitution shorthand: Throughout this document, every > If \--claude-only\: block also applies when the relevant agent is substituted via --substitute. When only one agent is substituted, apply the replacement only to that agent's call — the other agent's call remains unchanged as an MCP tool call. Both can still execute in parallel.

Reusable Templates

Templates T1–T13 are defined in references/templates.md. Read that file when you need template definitions. Quick reference:

| ID | Name | Purpose | |---|---|---| | T1 | Cognitive Styles | CD, AC, EE, GB style directives | | T2 | Review Instructions | T2-Science, T2-Feasibility review format with AGREE/DISAGREE/INSUFFICIENT verdicts | | T3 | DCR Debate Framework | Defend/Concede/Revise + Concession Tax + Hybrid Tribunal | | T4 | Mechanism Requirement | 1-2 sentence mechanism for each idea | | T5 | Subagent Output Convention | File naming and header format | | T6 | Subagent Prompt Str