magi-researchers

Research Workflow — Full Pipeline

Description

Runs the complete research pipeline: Brainstorming → Planning → Implementation → Testing & Visualization → Reporting. Orchestrates all phases with user checkpoints between each.

Usage

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

Arguments

• $ARGUMENTS — The research topic (required) and optional flags:
• --domain — Research domain (physics, ai_ml, statistics, mathematics, paper). Auto-inferred if omitted.
• --weights — Scoring mode for direction ranking:
• Omitted (default): Holistic ranking — Claude ranks directions by expert judgment with detailed rationale. No numeric weights.
• JSON object: Weighted scoring with dimension weights summing to 1.0.
• adaptive: Claude analyzes the prompt and recommends weights for user confirmation.

See /research-brainstorm for full details.

• --depth — Controls brainstorm review depth (default: medium):
• low — Skip cross-review, go directly to synthesis (fastest, lowest cost)
• medium — Standard one-shot cross-review (default)
• high — Cross-review + adversarial debate (most thorough, highest cost)
• max — Hierarchical MAGI-in-MAGI: N persona subagents run parallel mini-MAGI pipelines, then meta-review + adversarial debate across all perspectives (deepest, highest cost)
• --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 across all phases. Use when external model endpoints are unavailable. Forwarded to all sub-skills automatically.
• --substitute "Agent -> Opus" — Replace a specific MAGI agent with Claude (Opus). Accepted: "Gemini -> Opus", "Codex -> Opus". Can be specified multiple times. Forwarded to all sub-skills. If both agents are substituted, equivalent to --claude-only. Mutually exclusive with --claude-only (--claude-only takes precedence).
• --resume <output_dir> — Resume an interrupted pipeline from a previous output directory. See Resume Protocol below.

Instructions

Shared rules: Read ${CLAUDE_PLUGIN_ROOT}/shared/rules.md before starting. §MCP, §Visualization, §LaTeX, §PhaseGate, §Substitute apply to this skill.

Inline fallback (if shared rules unavailable): Gemini models: gemini-3.1-pro-preview → gemini-2.5-pro → Claude. Codex: gpt-5.4. All math in LaTeX only (no Unicode). scienceplots ['science','nature'], 300dpi PNG+PDF, Nature widths (3.5/7.2in). Use @filepath for MCP file refs; subagents use Read tool.

MCP Tool Rules

See §MCP, §Visualization, §LaTeX in shared rules. Additionally:

• Codex: Use mcp__codex-cli__brainstorm for ideation, mcp__codex-cli__ask-codex for analysis/review.
• Context7: Use during implementation phase for library documentation lookups.
• When to search: prior work verification, methodological precedents, dataset/library availability, related approaches, fact-checking quantitative claims

Path Safety Rule

ALL artifacts MUST be written under {output_dir}/. Never write files directly to the project root or any path outside outputs/.

• {output_dir} is the absolute path stored in .workspace.json at the output directory root.
• Before writing any file: if {output_dir} is uncertain (e.g., after context compression), recover it:
• Glob for outputs/*/.workspace.json, select the most recently modified match.
• Read the file and extract output_dir.
• Subagent prompts and sub-skill invocations: always include the absolute {output_dir} path.

When this skill is invoked, execute the full research pipeline below. Always pause for user confirmation between phases.

Phase Gate Protocol

See §PhaseGate in shared rules. Phase-specific checklists:

| Phase | Checklist Items | |:------|:----------------| | Plan | Completeness (all objectives addressed), methodology soundness, resource feasibility, risk identification | | Implement | Code correctness, alignment with plan, error handling, dependency management | | Execute | Exit code 0, results/ populated (or EXISTING/PARTIAL with user acknowledgment), pre_execution_status.json written | | Test | Tier 1 unit test coverage, edge case handling, Common Restrictions fulfilled (plot_manifest.json, dual format, dependency spec), result reproducibility |

Resume Protocol

When --resume <output_dir> is provided, the pipeline skips initialization and infers the current phase from the presence of key artifact files in the output directory. This avoids requiring the LLM to maintain a separate state file — the artifacts themselves serve as checkpoints.

Unified semantics: --resume always accepts the workspace root directory (e.g., outputs/topic_20260309_v1/). Whether resuming a research pipeline or a write sub-pipeline, the same root path is used. The system infers the correct sub-context internally.

Phase inference rules (evaluated top-down; first match wins):

| Condition | Inference | Action | |:----------|:----------|:-------| | report.md exists | Pipeline complete | Inform user; offer to re-run specific phases | | plots/plot_manifest.json exists | Test phase complete | Resume from the Report phase | | results/pre_execution_status.json exists (or pre_execution_status.md for legacy v0.8.x) | Execute phase complete | Resume from the Test phase | | src/ contains at least one source file | Implement phase complete | Resume from the Execute phase | | plan/research_plan.md exists | Plan phase complete | Resume from the Implement phase | | brainstorm/synthesis.md exists | Brainstorm phase complete | Resume from the Plan phase | | None of the above | No phase complete | Start from the Brainstorm phase |

Checkpoint hash validation (when checkpoint files exist): After determining the resume phase from artifact presence, check if a checkpoint file exists for the detected completed phase (e.g., plan/plan_checkpoint.json). If found:

1. Read the input_hashes field
2. Recompute hashes of the referenced input files
3. If hashes match: proceed with resume (inputs unchanged)
4. If hashes differ: warn the user that upstream artifacts have changed since this phase completed. Ask: "(a) Re-run this phase with updated inputs, or (b) Proceed anyway with existing outputs?"

Checkpoint validation is additive — if no checkpoint file exists (e.g., from a pre-v0.9.0 run), fall back to the existing artifact-presence inference.

Resume procedure:

1. Read {output_dir}/.workspace.json to restore the absolute output path and metadata.
2. Use the Glob tool to check for each artifact in the order above.
3. Read the first few lines of the matched artifact to confirm it is non-empty.
4. Announce to the user: detected phase, output directory, and which phase will be resumed.
5. Read the domain template if brainstorm/personas.md or brainstorm/weights.json exist (to restore context).
6. Continue the pipeline from the inferred phase, skipping all prior phases.

Important: On resume, do NOT re-create the output directory or overwrite existing artifacts. Append or create only the artifacts for the resumed phase and beyond.

Artifact Contract Protocol

Before starting each phase (2 through 5), verify that the required predecessor artifacts exist and are non-empty. Use the Glob and Read tools for deterministic, tool-based validation — do not rely on memory or assumptions.

Required artifacts per phase:

| Phase | Required Artifacts | Validation Method | |:------|:-------------------|:---