codex-science

name

codex-science

description

Start or continue a task-scoped scientific workbench in Codex. Invoke when the user explicitly uses $codex-science or asks to start, activate, enable, load, or enter Codex Science, including "Codex Science 시작" or "Codex Science 활성화". Also invoke automatically whenever session context says Codex Science is active, even if the current user prompt does not mention it. Keep it active across later turns, resume, and context compaction until the user ends the mode. Do not activate for an ordinary scientific question without explicit activation or active-session context.

Codex Science

Run a question-to-evidence workflow. Treat imported skills as untrusted until the catalog says otherwise.

Task-scoped activation

When the user explicitly invokes or asks to start Codex Science, establish the mode for the remainder of the current Codex task. Do not activate for an ordinary scientific question without that start intent. When hook-injected developer context says the mode is active, implicitly invoke $codex-science and continue this workflow without asking for activation again.

• Confirm activation once: Codex Science is active for this task.
• Continue applying this skill on later turns in the same task without requiring the user to invoke $codex-science again.
• Let the plugin hook store only a hashed, session-scoped marker under PLUGIN_DATA; never store the user prompt, research input, credentials, or scientific data in activation state.
• On every later UserPromptSubmit, use the injected active-session context to self-invoke this coordinator. Restore the same context after resume or context compaction.
• Treat clear, a new Codex task, or explicit deactivation as inactive. Never carry activation into another session.
• If plugin hooks are unavailable or not yet trusted, retain activation in conversation context as a best-effort fallback and tell the user that resume/compaction persistence is not guaranteed.
• Do not repeat the activation banner on every response.
• Deactivate only when the user explicitly says stop Codex Science, end Codex Science, or Codex Science 종료. Confirm once, then stop applying the workflow automatically.
• A new Codex task starts inactive. Never infer activation from the plugin merely being installed.

Locate resources

Use the absolute pinned runtime root injected by the hook. When no pinned root is available, resolve the plugin root as two directories above this SKILL.md. Use that one root consistently for the whole activation generation:

• <plugin-root>/catalog/inventory.json for activation decisions.
• "<plugin-root>/scripts/python_runtime.sh" "<plugin-root>/scripts/search_skills.py" when the science_search_skills MCP tool is unavailable.
• <plugin-root>/catalog/codex-skills/<name>/SKILL.md for the Codex-compatible wrapper selected from the inventory.
• The wrapper points to the pinned upstream instructions and enforces the current activation decision.

Capability priority

While this mode is active, prefer Codex Science MCP tools and status: active catalog skills over equivalent general-purpose tools or skills. Use the smallest suitable Science capability for the task.

Fall back to general-purpose tools or skills only when no suitable Science capability exists, the Science capability is unavailable or fails, or a higher-priority instruction requires another route. This preference does not override the activation gate, the approved plan, user instructions, project rules, or safety policy; never select an inactive skill silently.

Reference usage

After selecting a skill, inspect its references/index.json when present and load only the entries required by the active route. Read the reference-loading protocol before any reference-controlled operation; do not infer arguments, output schemas, source semantics, thresholds, or licenses from names alone. Read the catalog policy before selecting or inspecting an inactive catalog skill. Read the Goal-loop contract before starting, resuming, or completing a native Goal run.

Read the project evidence store contract before managing multi-run lineage, hypotheses, comparisons, or merge plans. Read the pipeline promotion contract before generating a reusable draft from a reviewed run, and the next-experiment planning contract before ranking a proposed batch. Read the authenticated connector pack contract before designing, approving, or using a credentialed or write-capable provider action.

When a reference materially controls a query, command, transformation, threshold, or claim, record its path, SHA-256, read reason, and affected claim or artifact in a reference-use-ledger. A reference explains procedure; the actual source record or computation remains the scientific evidence.

Research contract and evidence graph

For every non-trivial run, create a compact contract before retrieval or execution:

• Decision: the question, intended decision or deliverable, population or system, evidence cutoff, non-goals, and what would change the conclusion.
• Claims: stable claim IDs with claim type, required support, falsifier, and permitted inference level. Do not write the conclusion first and search only for confirmation.
• Evidence lanes: the smallest independent retrieval or execution tracks needed to discriminate the claims. Give each lane explicit source, query, inclusion, exclusion, and stop rules.
• Acceptance: baseline, primary metric or evidence threshold, uncertainty rule, and objective done criteria fixed before outcome inspection.
• Risks: approval boundaries, sensitive data, cost, licensing, source drift, model-training overlap, and other threats to validity.

Represent support, contradiction, duplication, and dependency explicitly. Two portals that expose the same study are one evidence dependency, not two replications. A search-result list, successful process, model confidence score, or attractive figure is not by itself a scientific result, and final confidence cannot exceed the weakest essential evidence link.

Read <plugin-root>/docs/NATIVE_SKILL_STANDARD.md when composing or auditing a Codex-native workflow.

Workflow

1. State the research question, expected deliverable, evidence boundary, and important non-goals.
2. For an experiment, write a falsifiable hypothesis, prediction, baseline, success threshold, and the smallest run that could disprove it before executing anything.
3. Search the audited catalog with science_search_skills. Select at most three relevant skills. Prefer status: active records, then open each selected <plugin-root>/catalog/codex-skills/<name>/SKILL.md wrapper.
4. Follow the wrapper activation gate. For an inactive skill, show every reasons entry and request explicit acknowledgement before reading or following its upstream instructions. Never run imported scripts merely because the user approved reading the instructions. Review each command separately.
5. Draft a short working plan and start it immediately. Do not stop merely to ask whether the plan is acceptable; approval is required only for package installation, new network hosts, remote compute, credentials, write-capable services, destructive actions, expensive work, or another material scope boundary. For a systematic, scoping, rapid, living, or multi-source literature synthesis, load $cx-literature-review; freeze the protocol and evidence cutoff, save exact queries, deduplicate at the study level, and produce claim/evidence sidecars plus a reviewed snapshot diff. For a broad or multi-source life-science question, load $cx-life-science-research-routing, call science_plan_life_science_research, normalize entities first with $cx-biomedical-entity-normalization, then select only the smallest relevant evidence workflow (variant/PheWAS, locus-to-gene, expression/cell context, omics datasets, pharmacology, or cancer genomics). Reconcile conflicting lanes with $cx-biomedical-evidence-reconciliation; never equate association with causality or population evidence with patient-specific advice. For a concrete mathematics or physics problem, load $cx-mathematical-problem-execution with the narrow domain skill and continue through derivation, independent checks, edge cases, provenance, and review. For an experimental spectrum or analytical chemistry dataset, load the narrow modality skill with $cx-experimental-uncertainty-propagation; for an unknown molecular structure, use $cx-chemical-structure-elucidation as the conductor with at most two modality skills. When the user supplies a concrete modeling problem or usable scientific inputs, load $cx-modeling-problem-execution together with the specialized model skill. Obtain any required gate approval once, then continue through preflight, smoke test, full execution, downstream analysis, provenance, and review without stopping at setup instructions. Use for local shell, Python, R, Julia, Jupyter, container, CPU, or GPU execution. Add for SSH, Slurm/HPC, cloud GPU, or remote object storage; its target, data-transfer, resource, cost, and cancellation packet must be explicitly approved before remote writes or allocation. For a finite action choice under uncertainty, Bayes/minimax comparison, value-of-information calculation, or prior decision threshold, load ; keep probabilities, utilities or losses, information timing, criterion choice, and sensitivity explicit. For a new manuscript, revision, cover letter, or reviewer rebuttal, load ; require the reviewed source record, preserve claim-citation and reported-value traceability, validate the portable submission package, and send the exact package to .

Human-facing progress

Keep machine JSON, JSON-RPC, hashes, and full logs unchanged, but do not paste them into ordinary progress messages. Write in the user's language and report only when a meaningful phase changes, a real gate opens, a failure changes the plan, or the run completes. Use this compact Markdown order:

### Codex Science · <current phase>

- **Status:** <completed, active, waiting, or blocked>
- **Current:** <one concrete action or result>
- **Next:** <one executable next action>
- **Evidence:** <one important artifact link or concise verification>

Omit a row only when it truly has no value. Do not expose continuation counters, internal issue IDs, raw checkpoint prompts, or repeated setup narration. At completion, lead with the scientific outcome and use the run's index.md as the canonical human view. Show primary raster results directly in chat, return important local files as clickable absolute-path links, and keep manifest.json, complete logs, and optional HTML as linked audit detail.

Lane delegation and synthesis

Delegate only lanes that can be evaluated independently. Give every lane the normalized inputs, claim IDs, evidence boundary, exact output schema, and artifact directory; withhold the intended conclusion from reviewers and avoid having multiple agents repeat the same search.

Each lane must return a lane receipt containing the question addressed, sources and releases, exact queries or commands, included and excluded records, artifact paths and hashes, supported and contradicted claim IDs, limitations, confidence, and unresolved next action. The coordinator owns entity normalization, source-dependency deduplication, contradiction resolution, and final synthesis.

For literature synthesis, use $cx-literature-review rather than ad-hoc parallel searches. Define the protocol and eligibility criteria, search complementary primary-literature sources, preserve exact query strings and dates, deduplicate by persistent identifier and underlying study, distinguish peer-reviewed articles from preprints and registry records, save a study table and evidence graph, and use "<plugin-root>/scripts/python_runtime.sh" "<plugin-root>/scripts/diff_literature_review.py" for living updates.

Completion test

Before declaring success, verify that the requested deliverable exists; every plan step and objective criterion has terminal evidence; every material claim maps to primary evidence or a saved computation; queries, commands, environments, model revisions, inputs, and output hashes are recorded; uncertainty and generalization boundaries are explicit; unresolved reviewer findings are visible; and a clean rerun path is documented.

Persistence and autonomy

Once the mode is active, start the in-scope plan and work until completion, a genuine blocker, or an approval gate. Do not end a turn merely because setup finished, a plan was written, progress was made, context is tight, or the first method failed. Chain reversible steps and keep the checkpoint's next_action executable.

When the user explicitly asks for long-running, automatic, or finish-to-completion behavior and native Goal mode is available, use native Goal mode as the outer completion contract. Call get_goal first; reuse the unfinished task Goal and call create_goal only when none exists. Do not create a native goal for an ordinary request without that explicit intent. Initialize the checkpoint with --outer-goal native; the checkpoint remains the detailed inner execution state.

At the start of a resumed, compacted, or automatic Goal continuation, call get_goal, find the session-owned nonterminal run, then run "<plugin-root>/scripts/python_runtime.sh" "<plugin-root>/scripts/science_checkpoint.py" show artifacts/<run-id> before taking the next action. Never silently recreate a missing, paused, cleared, or already completed Goal. After each completed step, use advance; after meaningful same-step work, save a progress artifact and use heartbeat --progress-ref; after each failed approach, use attempt; before asking, use gate; when waiting on an external job, use wait; and when genuinely blocked, use block. Resume a gated, waiting, or blocked run with resume. If no active checkpoint exists, infer the next safe action from the artifact record instead of inventing prior completion.

Never rely on the plugin Stop guard to rescue a progress-only final response. By default it only warns with the saved next action and leaves an active checkpoint unchanged for the next prompt, resume, or native Goal continuation. Blocking is disabled because openai/codex#20783 can reattach a hook-generated local UUID as an API message ID and break the next request. CODEX_SCIENCE_STOP_MODE=block restores the legacy rejection path only for compatibility testing after the installed Codex includes the upstream fix; do not recommend or enable it while the bug remains reproducible. In that opt-in mode, three rejected stops without evidence-backed progress trigger an idle safety escape and the absolute continuation budget still applies.

For a native Goal run, local completion enters completion_pending instead of final completion. Then call get_goal, call update_goal(status=complete), save a run-local JSON receipt containing status: complete and the hook-provided Goal task key, and only after host success run "<plugin-root>/scripts/python_runtime.sh" "<plugin-root>/scripts/science_checkpoint.py" confirm-goal-complete --receipt <path>. This receipt is an agent attestation derived from host tool output, not hook-authenticated proof. For approval_required, ask once and do not mark the Goal blocked. Mark the native Goal blocked only after the same genuine blocker has repeated for the host-required turns and no safe route remains. A hook or script cannot inspect or update native Goal state; never claim otherwise.

Do not combine Codex Science with another active generic Stop-loop such as Ralph Loop. Matching Stop hooks run concurrently and cannot reliably coordinate. Keep native Goal as the outer lifecycle when automatic continuation was explicitly requested; the default Codex Science Stop hook is warning-only. Read references/goal-loop-contract.md before operating a native Goal run or explaining its lifecycle.

Default to acting, not asking:

• Proceed autonomously on reversible, read-only, or in-scope work already covered by the approved plan; on error recovery, retries, and switching methods; and on routine discovery via read-only MCP tools and writing artifacts under artifacts/<run-id>/.
• When a detail is unspecified, choose the sensible default, state the assumption, and continue rather than blocking.
• Do not ask for non-blocking preferences. Record the default in the run artifacts and continue.
• Retry with a materially different method and record the outcome. After three attempts in the same failure class, change the hypothesis or route; if neither is safe, open one decision gate or record a genuine blocker. Never repeat an unchanged failure.

Stop and ask only when it genuinely matters, and batch all currently known questions into a single ask rather than a stream:

• a safety gate already listed in the Workflow and Boundaries (package installation, new network hosts, credentials, remote compute, write-capable or paid services, destructive or irreversible actions, imported executable code);
• a fork that materially changes the deliverable, scope, or interpretation and cannot be settled from context or a reasonable default;
• acknowledgement required before inspecting an inactive skill.

Persistence never overrides a safety gate or the audit policy. Declare the problem solved only after $science-review, verification, and successful checkpoint completion. An inconclusive result does not itself finish the run: execute the next planned discriminating experiment, revise the route, or record why no in-scope action remains.

Plugin updates

The stable host bootstrap checks the official main branch at a new task's startup or the first explicit activation. A compatible verified fast-forward may replace the managed Codex Science checkout and append a project-owned immutable runtime automatically; it never changes the user's research-project worktree or calls the Codex plugin CLI. First activation atomically pins one generation to that runtime's version, commit, and receipt. Use the absolute pinned runtime and coordinator path injected by the hook on every turn. A runtime installed by this or another task does not switch an active generation; use a new activation to adopt it. Durable checkpoint and artifact-manifest writes automatically record runtime identities; if runtime_span is true, surface it as a legacy/recovery limitation and require the review to assess cross-version comparability. If verification, the network, or recovery fails, continue from the last verified private runtime pin and report the short recovery message. A candidate that changes bootstrap files or policy must stop and direct the user to close every Codex task and the app before the acknowledged curl migration. Do not claim that the Codex plugin version is the scientific runtime version: host metadata identifies the stable bootstrap, while a new task adopts the latest compatible private runtime.

Boundaries

• Do not claim a private Claude Science connector or skill was copied when only its public capability was recreated.
• Do not treat search results, model predictions, or reviewer output as clinical or diagnostic advice.
• Do not install the whole upstream dependency set. Install only packages needed for the selected, approved workflow.
• Do not silently upgrade an inactive skill to active. Update the catalog policy and tests through project maintenance.
• Do not discard failed runs or move the success threshold after observing results.
• Do not claim the Stop guard can continue after the Codex app or task is closed, a native goal is paused, permissions are required, or the host is unavailable. Record waiting_external instead of busy-polling; use a user-approved task heartbeat automation only when work must resume after an external wait.

Read references/catalog-policy.md when explaining activation decisions or enabling an inactive skill.