magi-researchers

Research Implement Skill

Description

Implements research code based on an existing research plan. Requires a research_plan.md to be present in the active research output directory.

Usage

/research-implement [path/to/research_plan.md]

Arguments

• $ARGUMENTS — Optional path to the research plan. If not provided, searches for the most recent outputs/*/plan/research_plan.md.

Instructions

Shared rules: Read ${CLAUDE_PLUGIN_ROOT}/shared/rules.md before starting. §MCP, §Claude-Only 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. Use @filepath for MCP file refs; subagents use Read tool.

Claude-Only Mode

See §Claude-Only in shared rules.

MCP Tool Rules

See §MCP in shared rules. Additionally:

• Context7: Primary tool for library documentation lookups during implementation.
• When to search: library API changes, implementation examples, algorithm details, dependency compatibility, debugging known issues

Step 0: Locate Research Plan

1. If a path is provided in $ARGUMENTS, use it directly.
2. Otherwise, find the most recent research plan:
3. Glob for outputs/*/plan/research_plan.md
4. Select the most recently modified one.
5. If no plan is found, inform the user and suggest running /magi-researchers:research-brainstorm first, or creating a plan manually.
6. Read the research plan and identify:
7. The output base directory (parent of plan/)
8. Required algorithms/models to implement
9. Programming language and framework choices (from frontmatter languages/ecosystem fields)
10. Expected inputs and outputs
11. Dependencies needed
12. Parse mode flags from $ARGUMENTS: If invoked standalone (not from the /research pipeline), check $ARGUMENTS for --claude-only and --substitute flags. When present, all Gemini/Codex MCP calls in this skill are replaced per the Claude-Only Mode rules above.
13. Resolve output directory: If .workspace.json exists at the output directory root, read output_dir from it and use as the base for all file operations. If absent (standalone invocation), derive the absolute output path from the location of research_plan.md.

Step 1: Workspace Detection & Environment Setup

1. Check if src/ already has code (Glob src/**/*):
2. If files exist, read them to understand the current ecosystem before adding anything new.
3. If src/ is empty or absent, proceed with initialization.

1. Determine language and ecosystem using the following priority:

| Priority | Source | How | |:---------|:-------|:----| | 1st | Existing src/ files | Detect package managers (Cargo.toml, pyproject.toml, Project.toml, DESCRIPTION) and dominant file extensions | | 2nd | research_plan.md frontmatter | Read languages and ecosystem fields | | 3rd | Domain + topic inference | Autonomous selection based on research domain and algorithms |

If 1st and 2nd conflict (e.g., plan says Python but src/ has Rust code), the actual files win. Announce the discrepancy and proceed with the detected ecosystem.

1. Initialize the ecosystem (only if src/ is empty):
2. Run the appropriate setup commands for the chosen language:
3. Python: uv init (if no pyproject.toml exists) or uv add {deps}
4. Rust: If src/ already exists (pre-created by the pipeline), run cargo init in the output directory root (not inside src/) to avoid double-nesting (src/src/). The resulting src/main.rs is the correct layout.
5. R: create DESCRIPTION and R/ subdirectory
6. Julia: julia --project=src/ -e 'import Pkg; Pkg.init()'
7. C/C++: create CMakeLists.txt or Makefile
8. If the chosen language/tool is not available on the host system, inform the user with the

install command and stop. Do NOT attempt to install system-level tools without user approval.

1. Language selection principles (when choosing freely):
2. Match the dominant language of the research domain and algorithms
3. Prefer languages/libraries the research plan explicitly mentions
4. Python + uv is the safe fallback when no other preference is clear
5. The implementation must be runnable on a standard Ubuntu Linux system via a scripted command

(no interactive install steps, no GUI-only tools, no proprietary licenses required)

Step 2: Implementation

1. Follow the research plan's implementation section strictly.
2. Write modular, well-structured code in src/:
3. Follow the ecosystem's idiomatic project layout (e.g., src/main.py for Python, src/main.rs
4. src/lib.rs for Rust, R/ for R packages)
5. Separate modules for distinct components (data loading, model, utilities, etc.)
6. Implement a dry-run / fast-mode flag in the main entry point:
7. The flag should reduce runtime to seconds (e.g., 1 epoch, 10 samples, minimal iterations)
8. This is used by Phase 3.5 (/research-execute) for a quick sanity check before the full run
9. Examples: --dry-run, --fast, --epochs 1 --samples 10
10. Use Context7 (mcp__plugin_context7_context7__query-docs) to look up library APIs when needed.
11. Include docstrings/comments for all public functions explaining purpose, parameters, return values.

Step 3: Update research_plan.md Frontmatter

After implementation, update the YAML frontmatter in plan/research_plan.md to reflect the actual execution commands. This information is consumed by Phase 3.5 (/research-execute).

Read the current frontmatter and update or add these fields:

---
title: "..."
domain: "..."
languages: ["rust", "python"]        # actual languages used in src/
ecosystem: ["cargo", "uv"]           # actual package managers
execution_cmd: "bash run_all.sh"     # command to run the full pipeline
dry_run_cmd: "bash run_all.sh --dry-run"  # fast sanity-check command (seconds)
expected_outputs:                    # key files that should appear in results/
  - "results/metrics.csv"
  - "results/model.pt"
estimated_runtime: "~30 minutes"     # rough estimate for user awareness
---

If a run_all.sh (or equivalent) script does not yet exist, create it in the output directory root (not inside src/). The cwd field in execution_manifest.json should be set accordingly. Always verify that execution_cmd can be run from the directory specified by cwd.

Step 3b: Emit Execution Manifest

After updating the YAML frontmatter, also emit a structured execution_manifest.json in the output directory root. This file is the machine-readable execution contract consumed by Phase 3.5 (/research-execute).

{
  "schema_version": "1.0.0",
  "languages": ["rust", "python"],
  "ecosystem": ["cargo", "uv"],
  "execution_cmd": "bash run_all.sh",
  "dry_run_cmd": "bash run_all.sh --dry-run",
  "expected_outputs": [
    {"path": "results/metrics.csv", "required": true},
    {"path": "results/model.pt", "required": false}
  ],
  "estimated_runtime": "~30 minutes",
  "cwd": "."
}

Fields:

• schema_version: Always "1.0.0" for this release
• languages, ecosystem: Actual languages/tools used in src/
• execution_cmd: Single command to run the full pipeline
• dry_run_cmd: Fast sanity-check command (seconds, not minutes)
• expected_outputs: Files that should appear in results/ after execution. required: true means the pipeline should warn if absent; required: false means optional.
• estimated_runtime: Rough estimate for user awareness
• cwd: Working directory relative to the output directory (optional, defaults to output directory root)

The YAML frontmatter in research_plan.md is retained for backward compatibility and human readability, but execution_manifest.json is the authoritative machine contract.

Pre-validation: Before proceeding to Step 4, verify that the file or command referenced by execution_cmd e