---
name: academic-research-suite
description: >
  ARS-Codex workflows for research, academic writing, manuscript review,
  research-to-paper pipelines, and experiment planning. Use when the user asks for deep research, literature
  review, systematic review, meta-analysis, research question refinement,
  academic paper drafting, paper revision, citation or integrity checks,
  reviewer simulation, peer review, editorial decision letters, research-to-paper
  workflows, experiment execution planning, statistical interpretation, or human
  study protocol support. Korean triggers: 논문 심사, 논문 수정, 초록 작성,
  체계적 문헌고찰, 연구부터 논문까지. Also use for Claude-style ARS command aliases such as
  /ars-plan, ars-plan, /ars-outline, /ars-abstract, /ars-lit-review,
  /ars-citation-check, /ars-disclosure, /ars-format-convert, /ars-3w,
  /ars-revision-coach, /ars-revision, /ars-reviewer, /ars-mark-read,
  /ars-unmark-read, /ars-cache-invalidate, /ars-rebuttal-audit, and /ars-full. This skill vendors ARS role prompts,
  references, templates, and shared handoff schemas under ars/.
metadata:
  version: "0.1.28"
  upstream_suite: "academic-research-skills"
  codex_adapter: true
allowed-tools: Read, Glob, Grep, WebSearch, Bash(uv *), Bash(python *), Bash(python3 *)
---

# ARS-Codex

This is a Codex adapter for the ARS suite. The vendored ARS content lives under
`ars/`; keep it as source material and route through this file first.

## Versioning

This Codex package is version `0.1.28`. The repo-root `VERSION`, this
`SKILL.md` metadata version, and `manifest.json` `adapter_version` must match.
Vendored ARS suite versions are tracked separately by source repository commit
in `manifest.json`.

## First Rule

Do not load the whole suite by default. Select one workflow, read that workflow's
`WORKFLOW.md`, then load only the agent, reference, template, or shared files needed
for the user's current stage.

The internal workflow entry files are named `WORKFLOW.md`, not `SKILL.md`, so
Codex registers only this root router skill instead of exposing every vendored
upstream workflow as a separate skill.

## Workflow Router

Choose the workflow by intent:

| User intent | Read first |
|---|---|
| Deep research, literature review, systematic review, meta-analysis, fact-checking, research question refinement | `ars/deep-research/WORKFLOW.md` |
| Academic paper writing, paper outline, abstract, revision, citation formatting, AI disclosure, LaTeX/DOCX/PDF formatting guidance | `ars/academic-paper/WORKFLOW.md` |
| Paper review, peer review simulation, editorial decision, reviewer calibration, re-review after revision | `ars/academic-paper-reviewer/WORKFLOW.md` |
| End-to-end research-to-paper pipeline, integrity gate, staged review/revision/finalization workflow | `ars/academic-pipeline/WORKFLOW.md` |
| Experiment planning, code experiment execution plan, human study protocol, statistical interpretation, reproducibility validation | `ars/experiment-agent/WORKFLOW.md` |

If the request spans multiple workflows, start with `ars/academic-pipeline/WORKFLOW.md`
unless the user clearly asked for a single phase.

### Paper Topic Scoping Override

Apply this override before the general paper/pipeline routing rule and before the Claude-Style Alias Router below.
The override applies regardless of whether the user invokes ARS via natural
language or via an `ars-*` alias.

If the user says they want to write a paper, thesis, proposal, article, journal
article, or manuscript, but they only provide a broad topic, tentative title,
research interest, or "題目/主題/方向" and do **not** provide a clear,
answerable research question, route to `ars/deep-research/WORKFLOW.md` in
`socratic` mode first. This matches the upstream ARS experience where vague
paper-topic requests start with SCR/Socratic narrowing instead of immediate
outline or drafting.

Treat these as Socratic triggers even when the wording contains paper-writing
intent:

- "I want to write a paper on ..."
- "I have a paper topic/title ..."
- "我想做一篇論文，題目是..."
- "我有一個研究方向/主題，但還不確定問題"
- "幫我想論文題目/收斂研究問題"
- "논문을 쓰고 싶은데 연구 질문이 아직 명확하지 않아"
- "논문 주제/연구 방향은 있지만 무엇을 연구할지 모르겠어"

First response in this path:

1. State that the request is being routed to `deep-research` `socratic` mode
   because the research question is not yet precise.
2. Ask 3-5 Socratic narrowing questions using `socratic_mentor_agent` and
   `research_question_agent` guidance.
3. Do not produce an outline, draft, literature review, or full pipeline
   dashboard until the user has converged on at least one candidate RQ.

Route directly to `ars/academic-paper/WORKFLOW.md` only when the user already
has a clear RQ, approved study frame, data/results, literature matrix, draft,
or explicitly asks to skip scoping and proceed to outline/drafting. Route to
`ars/academic-pipeline/WORKFLOW.md` only when the user explicitly asks for the
full research-to-paper pipeline or says to continue after Socratic scoping.

## Claude-Style Alias Router

Codex does not install Claude slash commands, but this package emulates their
intent. If the user's request starts with a slash alias (`/ars-plan`) or a plain
alias (`ars-plan`), treat it as a mode shortcut, strip the alias token from the
task text, read the matching `ars/commands/ars-*.md` prompt recipe, then route
to the workflow `WORKFLOW.md` below.

The `model:` field in command frontmatter is a Claude routing hint only. Codex
uses the current model unless the user explicitly requests another model.

| Alias | Read command recipe | Then route to |
|---|---|---|
| `/ars-plan`, `ars-plan` | `ars/commands/ars-plan.md` | `ars/academic-paper/WORKFLOW.md` in `plan` mode |
| `/ars-outline`, `ars-outline` | `ars/commands/ars-outline.md` | `ars/academic-paper/WORKFLOW.md` in `outline-only` mode |
| `/ars-abstract`, `ars-abstract` | `ars/commands/ars-abstract.md` | `ars/academic-paper/WORKFLOW.md` in `abstract-only` mode |
| `/ars-lit-review`, `ars-lit-review` | `ars/commands/ars-lit-review.md` | `ars/academic-paper/WORKFLOW.md` in `lit-review` mode; if the user wants source discovery and synthesis instead, route to `ars/deep-research/WORKFLOW.md` in `lit-review` mode |
| `/ars-3w`, `ars-3w` | `ars/commands/ars-3w.md` | `ars/deep-research/WORKFLOW.md` in `three-way-scan` mode |
| `/ars-citation-check`, `ars-citation-check` | `ars/commands/ars-citation-check.md` | `ars/academic-paper/WORKFLOW.md` in `citation-check` mode |
| `/ars-disclosure`, `ars-disclosure` | `ars/commands/ars-disclosure.md` | `ars/academic-paper/WORKFLOW.md` in `disclosure` mode |
| `/ars-format-convert`, `ars-format-convert` | `ars/commands/ars-format-convert.md` | `ars/academic-paper/WORKFLOW.md` in `format-convert` mode |
| `/ars-revision-coach`, `ars-revision-coach` | `ars/commands/ars-revision-coach.md` | `ars/academic-paper/WORKFLOW.md` in `revision-coach` mode |
| `/ars-revision`, `ars-revision` | `ars/commands/ars-revision.md` | `ars/academic-paper/WORKFLOW.md` in `revision` mode |
| `/ars-rebuttal-audit`, `ars-rebuttal-audit` | `ars/commands/ars-rebuttal-audit.md` | `ars/academic-paper/WORKFLOW.md` in `rebuttal-audit` mode; requires both reviewer comments and an existing response draft |
| `/ars-reviewer`, `ars-reviewer` | `ars/commands/ars-reviewer.md` | `ars/academic-paper-reviewer/WORKFLOW.md` in `full` mode unless another reviewer mode is explicit |
| `/ars-mark-read`, `ars-mark-read` | `ars/commands/ars-mark-read.md` | Record a user-attested read declaration against the active Material Passport; every new mark requires a user-owned `read_scope`, with locators allowed only for `sections` scope |
| `/ars-unmark-read`, `ars-unmark-read` | `ars/commands/ars-unmark-read.md` | Rescind a prior human-read mark against the active Material Passport |
| `/ars-cache-invalidate`, `ars-cache-invalidate` | `ars/commands/ars-cache-invalidate.md` | Invalidate cached verification entries for one citation key |
| `/ars-full`, `ars-full` | `ars/commands/ars-full.md` | `ars/academic-pipeline/WORKFLOW.md` |

If the request body after the alias is a vague topic, tentative title, research
direction, or "題目/主題/方向" without a clear research question, defer to the Paper Topic Scoping Override above before routing to the alias's target mode.
This applies to `ars-plan`, `ars-outline`, `ars-abstract`, `ars-lit-review`,
and `ars-full`.

If the Codex client reserves slash-prefixed input before it reaches the model,
tell the user to use the plain alias form, for example `ars-plan my topic`.

## Codex Runtime Mapping

The upstream ARS files were written for Claude Code. Apply these mappings when
using them in Codex:

| Upstream wording | Codex behavior |
|---|---|
| Agent Team, agent, dispatch, handoff | Read the referenced `agents/*.md` file as a role or phase prompt and perform that phase inline. |
| Agent tool, Task tool, subagent | Do not spawn agents automatically. Only use Codex subagents when the user explicitly asks for delegation or parallel agents. If the optional full-runtime profile is enabled, use `codex/full-runtime-manifest.json` and `codex/agents/*.md` as the adapter contract. |
| AskUserQuestion | Ask concise clarification questions, or use Codex's structured user-input tool when available in the active mode. |
| WebSearch | Use Codex web browsing for current facts, source verification, citation checks, and external evidence. Provide source links. |
| Bash, Write, Edit | Treat as capability descriptions, not required tool names. Follow Codex safety rules and the user's filesystem constraints. |
| Agent frontmatter `tools: Read, Write, Edit, Grep, Glob` | Preserve this as a least-privilege role boundary. The three protected top-level agent roles do not receive Bash or network transport when dispatched separately; inline execution must not use those roles to widen the current task's authority. |
| Claude, Claude Code, model-specific wording | Interpret as "the current Codex agent" unless the text is part of a disclosure template or historical example. |
| `ARS_MODEL_TIERING=economy|quality-boost` | Unset remains the default and preserves current-model behavior. The upstream relative Opus/Sonnet tier names are not hard-mapped to Codex model ids. Apply tiering only when the active Codex runtime supports an explicit per-dispatch model override; otherwise announce a one-line no-op and keep every role on the active model. Use `ars/shared/model_tiering.md` and `ars/scripts/model_tiering_manifest.json` as the classification contract. |
| `ARS_CROSS_MODEL`, `ARS_CROSS_MODEL_REASONING_EFFORT`, `ARS_OPENAI_COMPAT_BASE_URL`, `ARS_OPENAI_COMPAT_API_KEY` | Treat upstream secondary-model dispatch instructions as no-op unless the user explicitly asks for cross-model review. When explicitly enabled in this Codex package, follow `ars/shared/cross_model_verification.md`: identify the provider/model/id status/content class, obtain explicit user consent before any external upload, preserve risk-stratified sampling and blind-disagreement checkpoint rules, and call only the configured provider API. A dispatched owner emits the canonical `[CROSS-MODEL-HANDOFF v1]` envelope; the dispatching Codex context validates it, sends only the payload, applies the mechanical result routing, and returns judgment work to the owner. In reviewer `full` mode, the consented cross-model track swaps the existing Reviewer 2 seat rather than adding a reviewer; re-review runs the independent Priority-1 judge pass and records the Judge Record. Disclose single-family or fallback execution and never simulate either track through the active Codex model. |
| `ARS_CROSS_MODEL_TRANSPORT=codex`, `scripts/cross_model_codex_transport.py` | This explicit selector is limited to contained, one-reference citation checks at Stage 2.5 / 4.5 through a ChatGPT-subscription Codex app-server. Require Codex CLI 0.147.0 or newer, `ARS_CROSS_MODEL`, the exact `Logged in using ChatGPT` attestation on stdout or stderr, and the normal provider/content/cost consent gate; do not accept caller-authored prompts or paths, widen the selector to reviewer/DA/calibration/re-review/handoff calls, or fall back automatically to an API. The provider schema omits unsupported `uniqueItems`, but local validation still rejects duplicate sources. Keep `code_mode` disabled while allowing the bounded search host required by the standalone search tool; the closed event allowlist remains authoritative. A result is accepted only after `turn/completed`, clean process exit, and stdout/stderr EOF; late forbidden or malformed events, drain timeout, nonzero exit, reader failure, or stderr overflow fail visibly. |
| `S2_API_KEY`, `OPENALEX_API_KEY`, `OPENALEX_POLITE_EMAIL`, `CROSSREF_POLITE_EMAIL` | These are optional upstream bibliographic lookup settings. Use them only when the user explicitly runs contamination-signal migration or programmatic reference verification; normal Codex routing does not require them. Never log credential-bearing query strings, and do not use browser retrieval to bypass API rate limits. |
| `ARS_VERIFICATION_CACHE_PATH`, `ARS_CACHE_STALE_ADVISORY_DAYS`, `ARS_CACHE_REVALIDATE` | These configure the local SQLite citation-verification cache, the advisory-only stale-row threshold (default 30 days; `0` disables), and opt-in live re-validation. Preserve cached-by-default behavior when the programmatic citation gate is run. Live re-validation may call external bibliographic services, so use it only within the user's verification task and normal network/credential boundaries; an advisory never becomes a gate failure. |
| Local PDF page anchors, `scripts/pdf_read_preflight.py` | Before trusting a `page` anchor from a locally read PDF, run the structural preflight once and carry its sidecar by `ref_slug`. Treat `FAIL` as positive read-integrity evidence against the page anchor and `UNAVAILABLE` as an explicit advisory; never convert a missing dependency, encrypted file, parser repair, or absent sidecar into `PASS`. The v3.20 `--classify-content` extension is opt-in and process-isolated, depends on the separately pinned `requirements-pdf-content-classifier.txt`, and emits only a `TEXT_AVAILABLE` / `OCR_RECOMMENDED` / `unavailable` advisory while the verdict scope remains `STRUCTURE_ONLY`; never turn it into an automatic OCR or anchor-acceptance gate. |
| `scripts/research_workflow_profile.py` | Treat research-workflow profiles as a deterministic, default-off substrate, not an automatic router. Use only an explicit selection or the visible `field_general` fallback; never infer a research family from the manuscript. Corrections append receipts and mark prior-profile outputs stale without rewriting scholar-owned artifacts. |
| `ARS_INQUIRY_LEDGER=1`, `scripts/inquiry_branch_ledger.py` | The inquiry branch ledger is an opt-in local alpha. When explicitly active, preserve author-owned append events, bounded summaries, project/path identity, locking, recovery, and individually visible stale causes. The flag authorizes no external model, API, or search call and yields no novelty, correctness, value, or usability claim. |
| `scripts/check_promotion_bakeoff_preregistration.py` | Preserve the sealed commitment/reveal contracts and use the hermetic unit tests in this package. Do not run direct `verify-tree` against the re-rooted vendored subtree: it intentionally lacks the complete canonical upstream Git history required by that release-discipline check. A real future bakeoff must run from the upstream repository and still requires explicit consent for every live model call and cost. |
| `fresh Claude Code session`, `Claude Code session` | Read as "a new Codex conversation". Material Passport reset semantics still apply; only the runtime changes. This rule covers `ars/academic-pipeline/WORKFLOW.md`, `ars/academic-pipeline/agents/pipeline_orchestrator_agent.md`, `ars/academic-pipeline/references/passport_as_reset_boundary.md`, `ars/experiment-agent/README.md`, `ars/experiment-agent/README.zh-TW.md`, and `ars/docs/PERFORMANCE.md`. |
| `/ars-*` slash command, Claude plugin command | Treat `ars/commands/ars-*.md` as optional prompt recipes. Codex does not register slash commands from this package. |
| SessionStart hook, SubagentStop hook, `hooks/hooks.json`, `scripts/ars_update_check.sh` | Treat as upstream Claude Code hook metadata only. The v3.18 update checker is vendored for traceability and tests but is not installed or executed by Codex; Codex package updates remain manual unless the user explicitly asks to port hook behavior. |

### Bibliographic Network Routing

The upstream prompt contracts, Python resolver clients, and v3.21
claim-standing adapters are distinct execution paths. Apply this table before
following any vendored instruction that says a lookup happens automatically:

| Path | Default ARS-Codex behavior | Dedicated client trigger |
|---|---|---|
| Ordinary topic or candidate discovery | Use Codex browsing and authoritative web sources. | Never launches the Semantic Scholar, OpenAlex, Crossref, or arXiv Python resolver clients. |
| Agent-side ingest, deduplication, and source verification | In the default inline route, translate prompt-level `WebSearch` or index lookups into Codex browsing or official metadata pages. | Upstream prompt wording such as “automatic S2 lookup” does not itself launch a Python client in Codex. |
| Script-backed citation-existence gate | Do not infer this from an `ars-full` request alone. Stage 2.5 and 4.5 remain mandatory integrity checkpoints, but default Codex routing performs their source work through browsing unless the user also requests programmatic verification. | An explicit request to run `verify_passport.py`, `verification_gate`, or equivalent programmatic reference verification. Once invoked, cache misses may call Crossref, OpenAlex, and Semantic Scholar for non-manual references; arXiv runs only when `arxiv_id` is present. Manual references skip all four. |
| Claim-standing discovery | Offer only after an eligible Claim Registry row at Stage 2.5 or 4.5. It is advisory and separate from citation verification. | A separate user request plus affirmative, plan-bound consent. It uses the v3.21 keyword-discovery adapters, not the four single-reference resolver clients; absent, cancelled, invalidated, or stale consent means no call. |
| Contamination backfill or migration | No automatic migration. | Only the explicitly selected migration CLI and its documented indexes. |

The canonical upstream network map remains available at
`ars/docs/DATA_FLOWS.md`; this section is the Codex adapter override for when
those flows are actually launched here.

### ARS v3.21.1 Contract-Honesty Boundaries

- Phase E evidence rows are deterministic, source-bound checkpoint artifacts.
  They preserve the existing citation verdict and gate, do not mark a source as
  human-read, and must replay against explicit session-held source bytes.
- Revision roadmaps remain non-ranking proposals. Only an explicit author
  adjudication may authorize exact choices or integrity-correction targets;
  never infer, fabricate, or auto-apply author decisions. Optional cross-run
  adjudication-activity capture is local, best-effort, and advisory only.
- Review-target context must be author-confirmed, and criteria are carried by
  resolved pointers across formative, internal, and external review. Do not
  infer a missing venue/track, invent evidence, or let binding conformance alter
  integrity verdicts, editorial arithmetic, checkpoints, or author triage.
- Human-subjects authority resolution keeps review-ethics and data-protection
  axes separate and fails closed when scope, currency, or applicability is
  unresolved. Outputs remain institution-owned navigation aids, never legal
  advice, an IRB/REC determination, an authorization, or a fabricated timeline.
- Bibliographic-integrity and retraction carriers preserve observations,
  provenance, disagreement, staleness, and degradation without minting a clean
  certificate or replacing the citation finalizer's policy aut