open-scholar-peer: Instructions file for Codex

AGENTS.md — Open ScholarPeer

Init-style instructions for AI agents doing development on this repo. Read this first; depth lives in docs/. (This file is for agents working on OSP itself — NOT the file end users get in their project. A separate user-facing AGENTS.md is generated by the installers for tools that read project-root AGENTS.md (Copilot CLI, Codex, Kimi, Vibe, OpenCode, OpenHands), via scripts/merge_agents_md.sh from extensions/_shared/rules/osp-rules.md.)

What this project is

Open ScholarPeer (OSP) implements the paper "ScholarPeer: A Context-Aware Multi-Agent Framework for Automated Peer Review" as a portable set of skills, slash commands, and an MCP server that install into a user's project across 21 AI tools (Claude Code, Cursor, Gemini CLI, Copilot CLI, Antigravity, Antigravity CLI, Codex CLI, Qwen Code, OpenCode, Junie, Kiro, Kimi Code, Mistral Vibe, OpenHands, Pi, Oh My Pi, Grok Build, Hermes, Cline, Kilo Code, OpenClaw).

There is no runtime code. OSP is configuration-as-code. The library is the prompts and the sync infrastructure that keeps them consistent across tools.

Commands you will actually run

# After any edit under extensions/_shared/, regenerate adapters:
python3 scripts/sync_adapters.py

# Validate per-tool parity (must pass before any commit touching _shared/):
python3 scripts/test_parity.py

# Smoke-test all 21 installers in temp dirs (must pass before tagging release):
bash scripts/test_install.sh

# Syntax-check shell scripts:
for f in install.sh scripts/*.sh; do bash -n "$f" && echo "  ✓ $f" || echo "  ✗ $f"; done

# Syntax-check Python files (no formal linter configured).
# Globbed, not listed: the old fixed list left mcp-server/providers/ uncovered,
# so a syntax error in a provider was caught by nothing at all.
# compile(), not ast.parse(): ast.parse accepts things Python then refuses,
# such as reading a module global before declaring `global` in the same
# function. That exact mistake got past an ast.parse check on 2026-09-20.
python3 -c "import glob; [compile(open(f).read(), f, 'exec') for f in glob.glob('mcp-server/**/*.py',recursive=True)+glob.glob('scripts/*.py')]"

# Build the dev virtualenv at the REPO ROOT, never inside mcp-server/:
# init_mcp.sh does `cp -r mcp-server/. .open-scholar-peer/mcp/`, so a venv
# left in mcp-server/ is copied into every user's project.
python3 -m venv .venv && .venv/bin/pip install -r mcp-server/requirements.txt

# Provider checks. Nothing else in the repo loads mcp-server/providers/.
# Both need the venv above — the providers import bs4, arxiv and
# semanticscholar, so plain `python3` fails with ModuleNotFoundError.
.venv/bin/python scripts/test_providers_unit.py   # offline, ~1s, every change
.venv/bin/python scripts/test_providers.py        # live APIs, opt-in

# Run the MCP server standalone (debug mode):
cd mcp-server && PYTHONPATH=. ../.venv/bin/python osp_mcp.py