Imbad0202/academic-research-skills-codex

ARS-Codex

Languages: English · 简体中文 · 繁體中文 · 日本語

ARS-Codex is the Codex-native sibling of Academic Research Skills (ARS) for Claude Code. It is a separate Codex distribution with its own plugin identity, packaging, and runtime adapter. Its release number follows the vendored ARS suite.

This repository vendors the ARS workflow content as a single Codex skill:

skills/academic-research-suite/
  SKILL.md
  manifest.json
  agents/openai.yaml
  codex/
    full-runtime-manifest.json
    agents/
    hooks/
    scripts/
  ars/
    deep-research/
    academic-paper/
    academic-paper-reviewer/
    academic-pipeline/
    experiment-agent/
    commands/
    hooks/
    docs/
    tests/
    shared/

The original Claude Code ARS checkout is not modified. Upstream content is copied from fresh GitHub clones and adapted through the Codex router in skills/academic-research-suite/SKILL.md.

Relationship to Claude Code ARS

This repository is ARS-Codex. For the original Claude Code ARS distribution, use Imbad0202/academic-research-skills.

Use the Claude Code repo when you want the native Claude Code skill layout, Claude-specific agent-team behavior, or the original ARS development history. Use this repo when you want the Codex-native single-suite skill.

Versioning

This ARS-Codex package is version 3.22.0. The repo-root VERSION file, skills/academic-research-suite/SKILL.md metadata version, and skills/academic-research-suite/manifest.json adapter_version track the Codex package version in step with the vendored ARS suite, starting at 3.22.0. Earlier 0.1.x release numbers remain historical. The exact upstream version, tag, and commit are recorded in manifest.source_repositories[].

Package-level changes are summarized in CHANGELOG.md.

The vendored ARS source tracks v3.22.0 at Imbad0202/academic-research-skills@3c546bc08c56f79e0068f1ea4f0acedf5bf69b5e. This release adds the output-language-pair contract, Spanish intent routing, reviewer-calibration and plugin evaluation fixtures, and Windows file-lock repairs. It adopts upstream model-transport and audit-provenance fixes while preserving the Codex runtime and consent contracts. The output-language-pair registry currently supports only zh-tw-en; Spanish triggers do not install a Spanish output-locale pack. Claude plugin eval suites are reference material, not evidence of measured Codex performance. Nested upstream .github/ workflows and root agents/ mirrors are preserved for traceability and self-tests, but are not repo-level CI or Codex entrypoints; Claude/plugin loader files under .claude/ and .claude-plugin/ remain intentionally excluded.

Models and execution

This checkout's project configuration selects gpt-6-astra with xhigh reasoning for new trusted Codex sessions. Installing the skill does not copy that project setting or change an already-running session. The planner suggests medium for routine work and xhigh for complex work; these are starting policies, not measured optimal settings. ultra is optional in Codex for explicitly chosen demanding work and is rejected by the contained citation transport.

Native adaptive execution is the default: use bounded subagents for independent work when useful and let the lead continue with other work. The fixed full-runtime topology and hooks remain opt-in. Read the model runtime policy and system-card alignment audit.

Install ARS-Codex Plugin

Add the GitHub marketplace and install ARS-Codex with Codex CLI:

codex plugin marketplace add Imbad0202/academic-research-skills-codex --ref main
codex plugin add ars-codex@ars-codex

To update a plugin install later:

codex plugin marketplace upgrade ars-codex
codex plugin add ars-codex@ars-codex

In Codex Desktop, you can alternatively add the repository from Plugins and then install ARS-Codex:

Marketplace source: https://github.com/Imbad0202/academic-research-skills-codex.git
Branch/ref: main
Plugin: ars-codex

The plugin root is plugins/ars-codex/. Its skills/ directory contains a materialized copy of academic-research-suite, not a symlink. This keeps Codex Desktop installs portable on Windows, where plugin caches may materialize symlinks as plain text files and skip bundled skill registration.

Open a new Codex conversation after installation, then invoke $academic-research-suite or describe an academic research task that matches the bundled workflow.

Direct Skill Install Or Update

As an alternative to the plugin, install the skill directly from this repo path. Use --method git so public and credentialed GitHub access both work consistently:

python3 "$HOME/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo Imbad0202/academic-research-skills-codex \
  --ref main \
  --path skills/academic-research-suite \
  --method git

On macOS and many Linux systems, Python 3 is exposed as python3 rather than python. If your system only has a python command and it is Python 3, use python in the commands instead.

To update an existing install:

rm -rf "$HOME/.codex/skills/academic-research-suite"
python3 "$HOME/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo Imbad0202/academic-research-skills-codex \
  --ref main \
  --path skills/academic-research-suite \
  --method git

Open a new Codex conversation after installation. Existing Codex sessions may keep their old skill cache; you do not need to close unrelated Claude or Codex sessions.

Verify with /skills: you should see one ARS-Codex entry, academic-research-suite or ARS-Codex. You should not see separate academic-paper, academic-pipeline, deep-research, or academic-paper-reviewer skills from this package. If you do, reinstall with the update command above and open a new Codex conversation.

Codex Docs

• Codex setup covers

installation, ars-* aliases, optional tools, Material Passport adapters, and unsupported Claude plugin features.

• Codex architecture

explains the logical ARS pipeline with the Codex runtime overlay.

• Optional full-runtime adapter documents the

disabled-by-default planner, Codex agent-team templates, and hook pack.

Usage

Invoke the suite explicitly with $academic-research-suite (singular), then describe the research task and provide any source files, notes, draft text, reviewer comments, or output constraints.

Use $academic-research-suite to help me plan a systematic literature review on
AI adoption in higher education quality assurance.

The Codex adapter routes the request to one of five ARS workflows:

| Workflow | Use when you need | Example prompt | |---|---|---| | deep-research | Research question refinement, literature review, systematic review, meta-analysis, fact-checking | Use $academic-research-suite to build a systematic review protocol for AI in higher education QA. | | academic-paper | Paper outline, drafting, abstract, revision, citation formatting, AI disclosure | Use $academic-research-suite to turn these notes into an IMRaD paper outline and drafting plan. | | academic-paper-reviewer | Manuscript review, simulated peer review, editorial decision, re-review | Use $academic-research-suite to review this manuscript and produce a journal-style decision letter. | | academic-pipeline | End-to-end research-to-paper workflow with integrity gates, review, revision, and final checks | Use $academic-research-suite to run an end-to-end research-to-paper pipeline from topic to revised manuscript. | | experiment-agent | Code experiment planning, human study protocol, statistical interpretation, reproducibility validation | Use $academic-research-suite to plan a code experiment and define reproducibility checks. |

Claude-Style Aliases

Claude Code v3.7 installs /ars-* slash commands. Codex does not have the same plugin command registry, so this package emulates the command intent inside the single $academic-research-suite skill. Use either form:

Use $academic-research-suite: ars-plan my paper on AI governance in universities.

or, when your Codex client passes slash-prefixed text through as a normal user message:

/ars-plan my paper on AI governance in universities.

If slash input is intercepted by the client, use the plain alias form:

ars-plan my paper on AI governance in universities.

| Claude command | Codex alias | Routed workflow | |---|---|---| | /ars-plan | ars-plan | academic-paper plan mode | | /ars-outline | ars-outline | academic-paper outline-only mode | | /ars-abstract | ars-abstract | academic-paper abstract-only mode | | /ars-lit-review | ars-lit-review | academic-paper lit-review mode | | /ars-citation-check | ars-citation-check | academic-paper citation-check mode | | /ars-disclosure | ars-disclosure | academic-paper disclosure mode | | /ars-format-convert | ars-format-convert | academic-paper format-convert mode | | /ars-revision-coach | ars-revision-coach | academic-paper revision-coach mode | | /ars-revision | ars-revision | academic-paper revision mode | | /ars-reviewer | ars-reviewer | academic-paper-reviewer full mode | | /ars-mark-read | ars-mark-read | Human-read signal for citation keys in the active Material Passport | | /ars-unmark-read | ars-unmark-read | Rescind a prior human-read signal | | /ars-cache-invalidate | ars-cache-invalidate | Invalidate cached verification entries for one citation key | | /ars-full | ars-full | academic-pipeline full workflow |

Working Pattern

For best results, start with the workflow goal and the current state of your materials:

Use $academic-research-suite.
Goal: write a journal article.
Current materials: I have a literature matrix and rough findings, but no outline.
Output needed now: paper architecture and missing-evidence checklist.
Constraints: English, APA 7, higher education policy audience.

If you only have a paper topic or broad research direction and do not yet have a clear research question, the Codex router should start with ARS Socratic scoping:

Use $academic-research-suite.
I want to write a paper on AI adoption in higher education quality assurance.
I do not yet have a clear research question.
Please use SCR / Socratic dialogue to help me narrow the question first; do not write an outline yet.

Expected route: deep-research socratic mode first. ARS should ask narrowing questions and should not produce an outline or draft until the research question has converged.

For review tasks, provide the manuscript or a path to the manuscript, plus the review mode you want:

Use $academic-research-suite to review this paper.
Mode: full review.
Focus: methodology, contribution, citation integrity, and likely desk-reject risks.
Output: reviewer reports plus editorial decision letter.

For staged pipelines, ask for a checkpoint instead of asking Codex to run the entire process silently:

Use $academic-research-suite to start an academic-pipeline run.
Begin with Stage 0 intake and stop after producing the pipeline dashboard.

Smoke Tests

In a new Codex conversation:

/skills

Expected: one ARS entry only.

Then test Socratic routing:

Use $academic-research-suite.
I want to write a paper on AI adoption in higher education quality assurance.
I do not yet have a clear research question.

Expected: route to deep-research socratic mode and ask narrowing questions.

CLI smoke test:

codex exec --ephemeral --sandbox read-only \
  -C /path/to/academic-research-skills-codex \
  'Use $academic-research-suite. Router smoke test only. User request to classify: I want to write a paper on AI adoption in higher education quality assurance, but I do not yet have a clear research question. According to the academic-research-suite router, classify the workflow and mode.'

Maintainer quality gates:

python3 skills/academic-research-suite/codex/scripts/ars_codex_quality_gates.py all --json

Expected: every reported gate has "ok": true.

Non-Blocking Codex Warnings

These Codex messages do not mean ARS failed to install:

• [features].codex_hooks is deprecated — update your Codex config when

convenient; ARS-Codex does not require hooks for normal use.

• hooks need review before they can run — review those hooks separately if

you use them. ARS-Codex treats vendored Claude hooks as traceability metadata and does not require them.

Codex Adapter Behavior

ARS was originally written for Claude Code. In this Codex package:

• The vendored agents/*.md files are used as role and phase prompts.
• The Codex-only codex/ directory contains an optional full-runtime adapter

profile. Its fixed topology and hook pack are opt-in; normal execution adapts native subagents to the task.

• The vendored commands/ars-*.md files are prompt recipes only. Codex does not

register them as slash commands.

• The vendored hooks/hooks.json file is preserved for upstream traceability

only. Codex does not install Claude Code hooks from this package.

• Codex may delegate bounded independent work through native subagents within

the current task and permissions, while the lead continues useful work.

• Web/source verification uses Codex browsing and must cite sources when current

or external facts matter.

• Cross-model verification is disabled by default. When explicitly requested in

this Codex package, follow the vendored provider setup in ars/shared/cross_model_verification.md, identify the provider/model/content class first, and obtain explicit user consent before any external upload. External reviewers are called through configured provider APIs, not simulated through the active Codex model.

• ARS_MODEL_TIERING is unset by default. The Codex adapter preserves the

upstream judgment/execution classification but applies economy or quality-boost only when the runtime supports an explicit per-dispatch model override; otherwise it reports a no-op and keeps the active model.

• Protected top-level agent tools: allowlists remain least-privilege role

boundaries. A dispatched checkpoint owner does not gain Bash or network transport; the dispatching Codex context owns any explicitly consented cross-model call.

• A [CROSS-MODEL-HANDOFF v1] block is a transport request, not a deliverable.

The dispatcher validates it, sends only its payload, applies the mechanical result routing, and returns judgment work to the original owner.

• In reviewer full mode, an explicitly configured and consented cross-model

run swaps the existing Reviewer 2 seat; it never adds a sixth reviewer. Re-review applies the separate Priority-1 judge pass and records provenance. Single-family execution and provider fallback are disclosed.

• ARS_CACHE_STALE_ADVISORY_DAYS controls the advisory-only cache-age threshold,

while ARS_CACHE_REVALIDATE=1 opts into live bibliographic re-validation. These settings apply when the programmatic citation gate is run; stale rows alone never fail an integrity gate.

• Locally read PDFs run the structural pdf_read_preflight.py by default before

page anchors are trusted. FAIL and UNAVAILABLE remain distinct, and a missing parser or sidecar is never treated as PASS. The v3.20 sandboxed content classifier is an explicit opt-in advisory and cannot override this structural preflight.

• ars-mark-read requires a user-declared read_scope for every new mark.

Explicit unknown and legacy scope-less records remain coverage_unknown; partial coverage stays visible and Codex never infers full-text reading.

• Revision rounds use the v3.20 evidence-bound, non-ranking roadmap and explicit

author-adjudication contract. They also preserve the v3.19-introduced claim-strength ladder and deterministic numeric, citation, marker, and protected-term conservation checks as advisory-first guards.

• The upstream v3.18 SessionStart update checker is vendored but not installed

or executed as a Codex hook. Plugin users update with codex plugin marketplace upgrade ars-codex followed by codex plugin add ars-codex@ars-codex; direct skill installs still update by reinstalling or pulling this repository.

• Upstream references to a "fresh Claude Code session" mean a new Codex

conversation in this package; Material Passport reset semantics still apply.

• If a citation, source, statistic, or journal policy cannot be verified, Codex

should mark it as unverified rather than invent support.

ARS v3.22.0 Parity

This package adapts upstream ARS v3.22.0 at 3c546bc08c56f79e0068f1ea4f0acedf5bf69b5e wherever Codex has an equivalent concept, with documented model/runtime overlays.

Bibliographic network behavior is intentionally explicit at the Codex adapter boundary:

| Research path | Default Codex behavior | Dedicated API/client trigger | |---|---|---| | Ordinary topic or candidate discovery | Codex browsing and authoritative web sources | The four Python resolver clients are not launched | | Prompt-level ingest, deduplication, or source verification | Codex browsing or official metadata pages | “Automatic” lookup wording in vendored prompts does not launch a Python client | | Script-backed citation-existence gate | Not implied by ars-full; Stage 2.5/4.5 still run as integrity checkpoints through the default Codex route | Explicit programmatic-verification request; then Crossref/OpenAlex/Semantic Scholar run for non-manual references and arXiv only when arxiv_id exists, subject to cache behavior | | Claim-standing discovery | Advisory offer after an eligible Stage 2.5/4.5 Claim Registry row | Separate user request plus affirmative plan-bound consent; uses v3.21 discovery adapters, not the single-reference resolver clients | | Contamination backfill or migration | Never automatic | Explicit migration CLI only |

| Upstream ARS feature | Codex package behavior | |---|---| | One installable plugin | Native Codex plugin ars-codex, bundling the single academic-research-suite skill | | /ars- slash commands | Emulated as ars- aliases through the skill router; not native slash commands | | Four upstream skills auto-discovered from skills/ symlinks | Single Codex router skill selects the workflow and reads the vendored workflow WORKFLOW.md files | | Plugin-shipped agents | Role/phase prompts run inline or as bounded native subagents according to task dependencies and runtime permissions | | Optional Codex full-runtime profile | Planner, agent-team templates, and hook pack live under skills/academic-research-suite/codex/; disabled by default | | Heavy commands (ars-full, ars-reviewer, ars-revision-coach) omit model:; light modes retain model: sonnet | Heavy commands inherit the current Codex session model; light-mode sonnet remains upstream Claude metadata and does not override the session model | | ARS_MODEL_TIERING=economy\|quality-boost | Classification is preserved; routing remains advisory unless Codex exposes per-dispatch model selection | | Protected agent tools: allowlists | Preserved as least-privilege role boundaries; dispatched owners do not receive Bash/network transport | | Canonical cross-model handoff envelope | Dispatcher validates the envelope, transports only the payload after consent, and follows the closed result-routing contract | | Contained Codex citation transport | Opt-in, consent-gated transport is limited to narrow citation-integrity checks; it is inactive unless explicitly configured and requested | | Evidence-bound review and revision | Durable evidence rows, confirmed review criteria, non-ranking roadmaps, author adjudication, and revision-evidence bundles are preserved | | Research-workflow profiles | Default-off deterministic selection with a visible field-general fallback; no research family is inferred from manuscript content, and corrections stale rather than rewrite prior artifacts | | Inquiry branch ledger | ARS_INQUIRY_LEDGER=1 enables the local opt-in alpha; author events, bounded summaries, path/lock/recovery safeguards, and stale causes are preserved without granting network authority | | Sealed model-promotion bakeoffs | Commitment/reveal contracts and hermetic tests are vendored; the history-dependent tree verifier remains upstream-only because the re-rooted subtree has no complete upstream Git history | | Socratic research-question authorship | Non-convergence never triggers system-authored candidate questions; explicit user request is required to leave non-generation mode | | Categorical reviewer judgement and panel provenance | Live packages remain NOT_CALIBRATED; no numeric score, weight, aggregate, ranking, or binary independence claim is fabricated | | Review criteria and human-subjects authority | Venue/criteria and ethics/data-protection authority require explicit user confirmation; Codex does not infer or simulate approval | | Optional PDF content classifier | The sandboxed classifier is an opt-in advisory dependency and cannot override structural PDF preflight results | | Cross-model Reviewer 2 and re-review judge tracks | Available only with explicit provider configuration and content consent; the fixed seat, Judge Record, single-family disclosure, and fallback disclosure are preserved | | Source-backed review-criteria proving set | Exact-profile author confirmation, source receipts, and three-consumer digest binding are preserved; one proving profile is not venue or discipline coverage | | Cache staleness advisory and live re-validation | Local cache remains the default; stale rows are advisory-only and ARS_CACHE_REVALIDATE=1 opts into live bibliographic checks | | Data-flow and capability transparency | The v3.21 network map, control-availability matrix, stage-capability matrix, risk register, and governance statement are vendored without promoting evidence labels into effectiveness or certification claims | | Claim-standing pipeline wiring | Eligibility only offers the advisory view; query-plan binding, explicit consent, freshness validation, and transmission accounting remain mandatory before any external call | | Risk-stratified claim, scope, and novelty checks | Vendored workflow prompts and schemas preserve high-impact-first sampling plus advisory-only scope and search-bounded novelty rows | | Local-PDF read-integrity preflight | The structural pypdf preflight and sidecar contract remain the default; parser unavailability or repair warnings stay explicit UNAVAILABLE advisories, while the v3.20 classifier above remains opt-in only | | Human-read scope attestation | Every new mark requires user-owned read_scope; legacy missing scope remains unknown and partial coverage stays distinguishable from full coverage | | Claim coverage and bounded evaluation substrates | Exact registered-claim coverage, drift dispositions, claim-standing stance tools,