| name | scientific-reproduction |
| description | Orchestrate a complete, auditable reproduction of a scientific paper using multi-session research, experiment, computation, analysis, monitoring and Supervisor governance. Use when the user wants to reproduce a scientific paper, initialize or resume a reproduction project, plan/execute/monitor reproduction goals, or produce an auditable reproduction report. |
| allowed-tools | ["Read","Write","Edit","Bash","Glob","Grep","WebFetch"] |
Scientific Reproduction
Reproduce one scientific paper end to end — literature research, experiment
and computation execution, independent analysis, statistics, recovery, and a
machine-auditable report — under strict role governance.
Entry
Primary semantic command: /reproduce <PDF|DOI|URL>.
Governance (non-negotiable)
Load and obey the role contracts in agent-contracts/, the locked decisions
in 20-ARCHITECTURE-DECISIONS.md, and the role definitions in
.claude/agents/. Enforce the separation of duties:
- Workers report facts. Only the Supervisor makes scientific decisions.
- The Supervisor owns the project end to end; Research is the
project-persistent evidence service; the Execution Monitor owns recovery.
- Freeze acceptance criteria and primary analysis protocols before execution.
- Assess every piece of evidence as Source × Claim — never one global score.
- Role boundaries are enforced at the platform tool level too: the role
agents in
.claude/agents/ carry per-role tools: allowlists, so only
the Supervisor holds direct file-mutation and worker-dispatch tools;
other roles' state writes flow through the runtime CLI, which enforces
the role-action matrix.
Runtime operations
Delegate deterministic state, schema, lock, event and adapter operations to
the bundled runtime through the zero-install CLI wrapper (no pip install
needed; Python 3.11+ required):
python scripts/reproduce.py init <PDF|DOI|URL> --root <workspace>
The wrapper runs python -m scientific_reproduction.cli.reproduce from the
bundled src/. The command initializes the one-paper project workspace
(project.yaml plus the frozen directory tree and starter
.gitignore/.gitattributes, see templates/PROJECT-TREE.template.txt)
and records a git checkpoint commit. It refuses a non-empty root unless
--allow-non-empty-root is passed: unrelated content in the root must
never enter the scientific audit history. The workspace is the Single
Source of Truth — sessions are replaceable executors (see
14-STATE-GIT-ARTIFACTS.md).
/goals views are deterministic pure functions of the planning layer (see
docs/user/reproduce-and-goals.md): in v0.2 they are agent-authored from
that layer — the runtime ships no /goals subcommand — and platforms may
expose them through a native slash-command mechanism where available.
Pre-flight: skill update check
The skill directory is a git clone of the release branch
release/skill-v0.2.0; any push to it makes installed copies outdated.
Before initializing a new reproduction project (/reproduce), check
whether this installation is current:
python scripts/check-update.py
The check is read-only (it never mutates the working tree) and is the
only network touch of the whole skill — the reproduction path itself
stays network-free and deterministic.
- Exit 0 — up to date: proceed.
- Exit 1 — update available: the script prints the local version,
the latest available version, and the N-behind commit count. Inform
the user and apply the update only after explicit confirmation,
and only when the skill worktree is clean (
git status --porcelain
empty): git merge --ff-only origin/release/skill-v0.2.0, then gate
the result with python scripts/smoke.py — proceed only on
[smoke] PASS. If the fast-forward refuses, the checkout has
diverged: never force it, reconcile the worktree first.
- Exit 2 — cannot check (offline / not a git clone): proceed; an
uncheckable or unavailable update never blocks the deterministic
reproduction path.
Orchestration of the reproduction flow
- Initialize —
/reproduce the primary target paper (exactly one per
project) and record the primary target.
- Bootstrap research — build the complete evidence base from the main
paper, SI, and linked public data; register the primary target's
DOI/title metadata on the project record (a PDF target carries only its
path at init); collapse duplicate DOI mirrors; never treat mirrors as
independent evidence.
- Inventory — enumerate all formally reported experiments, controls,
and computations; audit for 100% coverage.
- Plan v1 — build and freeze Plan v1 (goals as Unit Processes, DAG
dependencies, resource closure) before any execution.
- Execute — delegate goals to worker sessions; record every run,
attempt, and artifact in the workspace; wet-lab work hands off through
the filesystem LabAdapter (
lab/outgoing, lab/incoming).
- Monitor and recover — the Execution Monitor reconciles long-running
runs and applies the L1–L3 recovery ladder (
08-STRICT-RECOVERY-CLOSURE.md);
each cycle it files a durable supervisor-inbox entry for every arrived
Result Package (<state_dir>/supervisor-inbox/<run_id>.json), and the
Supervisor reads the inbox on every wake-up, adjudicating each arrival
from the persisted records and surfacing HumanGate-required items to the
human user — an arrived (or failed) return is guaranteed to reach the
Supervisor's next wake-up, never left to manual inspection.
- Analyze independently — analysis is separated from execution; apply
the frozen statistics and acceptance governance
(
07-STATISTICS-AND-ACCEPTANCE.md).
- Report — render the deterministic final report PDF
(
reporting.build_pdf_report): executive summary with verdict callout
and the single most important number vs the frozen acceptance band,
target identity and scope counts, per-requirement outcomes with
evidence trails, governance exercised, and the audit trail with
checksums — plus the machine-auditable reproduction package with full
traceability. Both report files land in reports/ and are registered
in the audit package with SHA-256 checksums.
Frozen data to respect
schemas/ — frozen product schemas (project, goal, run, evidence, ...).
Validate against them; never edit them.agent-contracts/ — frozen role contracts.benchmarks/fdm201/ — the official reference case (FDM-201,
DOI 10.1039/D5TA00771B, materials chemistry domain pack).examples/fdm-201/ — example instance files.
Verification
Verify any installation with:
python scripts/smoke.py
It checks the skill structure, imports the bundled runtime, and runs a real
reproduce init for the reference DOI with output assertions.
Platform notes
- Claude Code: install by copying this directory to
~/.claude/skills/scientific-reproduction/; role agents load from
.claude/agents/.
- WorkBuddy: install by copying this directory to
~/.workbuddy/skills/scientific-reproduction/ (directory name must match
the name frontmatter).
- Codex: open this directory; Codex reads
AGENTS.md as its entry.
