Skip to content

AGENT_GUIDE.md

Latest commit

 

History

History
163 lines (113 loc) · 5.92 KB

AGENT_GUIDE.md

File metadata and controls

163 lines (113 loc) · 5.92 KB
Raw

Idea-Copilot Agent Guide

Idea-Copilot is a lightweight ARIS-derived skill workflow for discussing, creating, reviewing, ranking, and concretizing scientific research ideas.

It is intentionally narrower than ARIS and keeps only the idea-stage subset:

  • Keep the strong parts: skill-based workflow, cross-model executor/reviewer collaboration, literature-grounded idea creation, brutal review, PI-style prioritization, claim-driven experiment planning.
  • Remove the heavy parts: autonomous experiment deployment, paper writing, rebuttal, poster/slides, full submission assurance.

Skill Roots

Canonical skills live under:

skills/<skill-name>/SKILL.md

The workflow is platform-neutral. Claude Code, Codex, OpenCode, Cursor, or any Markdown-skill agent can load these files directly.

Output Language

All user-facing discussion and all saved artifacts must be written in Chinese by default. Follow skills/shared-references/output-language.md.

Keep technical identifiers unchanged when appropriate, including file paths, skill names, model names, paper titles, benchmark names, code symbols, and shell commands.

Claude Code Interaction

Claude Code has two supported roles in this project.

Mode A: Claude Code as executor, Codex as reviewer

Claude Code loads /idea-copilot, discusses ideas with the user, writes artifacts, and calls Codex as the independent reviewer through Codex MCP.

Install Codex MCP into Claude Code:

claude mcp add codex -s user -- codex mcp-server

Expected flow:

User
  -> Claude Code executor loads /idea-copilot
  -> Claude Code writes LANDSCAPE / IDEA_CANDIDATES / etc.
  -> Claude Code calls Codex MCP for harsh review
  -> Claude Code revises ranking, proposal, and experiment plan

Mode B: Codex as executor, Claude Code as reviewer

Codex loads /idea-copilot and uses this project's mcp-servers/claude-review bridge to invoke the local Claude Code CLI as the independent reviewer.

Install Claude review bridge into Codex:

mkdir -p ~/.codex/mcp-servers/claude-review
cp mcp-servers/claude-review/server.py ~/.codex/mcp-servers/claude-review/server.py
codex mcp add claude-review -- python3 ~/.codex/mcp-servers/claude-review/server.py

Expected flow:

User
  -> Codex executor loads /idea-copilot
  -> Codex writes idea artifacts
  -> Codex calls claude-review MCP
  -> claude-review MCP runs `claude -p ...`
  -> Claude Code returns PI/reviewer critique
  -> Codex updates ranking, proposal, and experiment plan

Main Workflow

Use /idea-copilot as the entry point.

/idea-copilot "research direction or rough idea"

It chains:

/idea-landscape
  -> /idea-generate
  -> /idea-novelty
  -> /idea-review
  -> /idea-refine
  -> /idea-experiment-plan

Design Principles

  1. PI + harsh reviewer stance: Encourage good ideas, but attack weak assumptions early.
  2. Human-in-the-loop by default: Discuss scope and priorities with the user before locking the top idea.
  3. External reviewer separation: When available, use a different model family for critique than the executor model.
  4. Literature before confidence: No idea should be ranked high before at least a targeted novelty check.
  5. Claims before experiments: Every experiment must defend or falsify a specific claim.
  6. Negative results are useful: Eliminate weak ideas explicitly and preserve why they failed.

Reviewer Backend Contract

The skills refer to an external reviewer abstractly. Use the strongest available backend:

  • Claude Code executor + Codex MCP reviewer: use mcp__codex__codex / mcp__codex__codex-reply.
  • Codex executor + Claude reviewer: use mcp-servers/claude-review.
  • Any executor + OpenAI-compatible reviewer: use mcp-servers/llm-review as a stateless fallback.
  • OpenCode or other agents: use any MCP or CLI tool that can create a fresh independent review thread.

Reviewer calls are enabled by default and should use fresh threads for independent judgments. Same-thread follow-up is acceptable only inside one review episode. Follow skills/shared-references/external-review.md; send only minimized review packages, not raw private folders.

See mcp-servers/reviewer-contract/README.md for the expected tool interface.

Non-Goals

Idea-Copilot does not own:

  • experiment deployment or GPU job management
  • paper drafting or LaTeX compilation
  • rebuttal, poster, slide, resubmission, or camera-ready workflows
  • full submission assurance chains

When a selected idea is ready for implementation, hand it off to a separate engineering or experiment workflow rather than expanding this project.

Artifacts

The workflow writes plain Markdown artifacts:

Resolve RUN_DIR, IDEA_STAGE_DIR, and REFINE_LOG_DIR by following skills/shared-references/run-directory.md. The first legacy-compatible run may use the project root; later runs are grouped under a collision-free idea-runs/<run-id>/ directory. .idea-copilot-run.md records the active run so standalone subskills continue with the same artifacts.

${IDEA_STAGE_DIR}/
├── LANDSCAPE.md
├── RAW_IDEAS.md
├── IDEA_CANDIDATES.md
├── NOVELTY_REPORT.md
├── REVIEW_PACKAGE.md
├── REVIEW_AUTHORIZATION.md
├── REVIEW_REPORT.md
├── REVIEW_RAW.md
├── FINAL_IDEA_RANKING.md
└── SELECTED_IDEA_BRIEF.md

${REFINE_LOG_DIR}/
├── FINAL_PROPOSAL.md
├── EXPERIMENT_PLAN.md
└── EXPERIMENT_TRACKER.md

Use templates/RESEARCH_IDEA_BRIEF.md when the user wants to provide structured context.

When to Stop and Ask the User

Ask the user before proceeding when:

  • the research direction is ambiguous across multiple fields
  • compute/data constraints are unknown and affect idea feasibility
  • the top ideas imply very different project directions
  • a novelty check finds strong overlap and the agent needs a positioning choice
  • the user explicitly asks to be consulted before edits or decisions

Otherwise, keep moving and make reasonable assumptions.