Codex Research Workflow

A rigorous, reproducible research-orchestration Skill for OpenAI Codex.

English | 简体中文

Overview

codex-research-workflow is a public Codex Skill for rigorous, reproducible research orchestration.

It turns consequential research requests into bounded task contracts, routes work to available specialist Skills, coordinates multiple Codex tasks through explicit project state and immutable handoffs, and enforces evidence, empirical-integrity, citation, and completion gates.

The project is designed for research workflows in which correctness, traceability, reproducibility, and clear task boundaries matter more than one-shot generation.

What it can do

The workflow can route and coordinate research tasks involving:

• research-question formulation;
• literature review;
• scientometrics;
• data audit;
• empirical analysis;
• research code;
• visualization;
• manuscript development and review;
• journal fit;
• citation finalization.

It supports four role types:

1. Controller — owns the authoritative project state and task contract.
2. Prompt workbenches — optionally compile reusable or role-specific prompts.
3. Executors — perform bounded research work packages.
4. Auditors — independently check evidence, empirical integrity, citations, and completion.

How it works

Research request
      ↓
Task contract
      ↓
Controller
      ↓
Specialist Skill / Executor
      ↓
Immutable handoff
      ↓
Independent audit
      ↓
Evidence + integrity + citation + completion gates
      ↓
Accepted research artifact

For long-running projects, the Skill can create a compact .codex-research/ control layer. This layer stores project-control metadata and artifact locators without moving the user's existing research materials.

Core design principles

• Bounded tasks — important work is converted into explicit task contracts.
• Explicit authority — the controller owns authoritative project state.
• Source of truth — research claims should be tied to identifiable evidence.
• Empirical integrity — analysis should not silently exceed what the design or data support.
• Immutable handoffs — executor outputs are handed off explicitly rather than silently rewritten.
• Independent audit — important outputs can be checked separately from the executor that produced them.
• Fresh verification — time-sensitive or externally verifiable claims can be required to be rechecked.
• Deterministic validation — contracts, state, handoffs, and generated prompts can be validated programmatically.

Repository layout

codex-research-workflow/
├── skill/
│   └── codex-research-workflow/   # installable Codex Skill
├── evals/                          # deterministic regression tests
├── tools/                          # security, privacy, and evaluation tools
├── README.md                       # English documentation
├── README.zh-CN.md                 # 简体中文文档
├── LICENSE
└── VERSION

Installation

Copy the complete:

skill/codex-research-workflow/

directory to your personal Codex Skills directory so that the installed path ends with:

<codex-home>/skills/codex-research-workflow/

Then refresh or restart Codex.

Quick start

Invoke the Skill explicitly:

$codex-research-workflow

Design an auditable empirical analysis of whether participation by public-sector organizations is associated with later policy-document citation. Do not assume a causal effect. First establish the task contract and identify unresolved definitions.

The Skill can also compile prompts without performing the research task itself:

$codex-research-workflow

target_role=prompt
prompt_mode=standalone

Generate an audit-level prompt for a literature-review executor. Generate the prompt only; do not perform the review.

Long-running research projects

For a long-running project, initialize the non-invasive control layer:

python <skill-path>/scripts/init_research_project.py <project-root> --project-id <project-id> --dry-run
python <skill-path>/scripts/init_research_project.py <project-root> --project-id <project-id>
python <skill-path>/scripts/validate_project_control.py <project-root>

The initializer creates:

.codex-research/

inside the project and does not move existing research materials.

A useful pattern is:

Research project
├── existing data / code / manuscript
└── .codex-research/
    └── project-control metadata and artifact locators

Typical use cases

Research design

Use the workflow to establish a bounded research question, definitions, assumptions, evidence requirements, and unresolved decisions before analysis begins.

Literature review

Route literature-search, evidence-extraction, synthesis, and audit tasks to appropriate specialist Skills while keeping evidence provenance explicit.

Scientometrics and empirical research

Separate data audit, variable construction, empirical analysis, code execution, interpretation, and independent methodological review.

Manuscript and journal workflow

Coordinate manuscript review, journal-fit analysis, citation verification, and final completion checks without treating any single generated draft as authoritative by default.

Validation

From the repository root:

python -m unittest discover -s evals -p "test_*.py" -q
python tools/security_audit.py
python tools/privacy_audit.py

To validate only the installable Skill with the official Codex validator:

python <skill-creator-path>/scripts/quick_validate.py skill/codex-research-workflow

Personalization

Customize:

skill/codex-research-workflow/references/profile-and-preferences.md

locally, or provide stronger project-specific instructions in:

AGENTS.md

Do not commit confidential information as part of personalization.

Privacy

The public distribution contains no personal profile, institutional identity, local research path, raw chat history, unpublished manuscript, credential, or private dataset.

Project state stores compact metadata and artifact locators rather than copying research materials.

Before publishing a customized fork, run:

python tools/privacy_audit.py

and review the complete Git diff and repository history.

Contributing and adaptation

You can fork the repository and adapt the Skill for your own research workflow. Keep private profiles, credentials, unpublished materials, and local paths out of the public repository.

If you change task contracts, handoff formats, project-state rules, or validation behavior, run the regression, security, and privacy checks before publishing.

License

Released under the MIT License. See LICENSE.