codex-research-workflow

name

codex-research-workflow

description

Initialize, migrate, audit, execute, review, and resume single-root governed research projects based on AGENTS.md, docs/PROJECT_CORE.md, and docs/CURRENT_STAGE.md. Use for every research-controller-issued Codex Goal in a governed project, and for project setup, root validation, durable direction changes, decision-complete evidence, optional implementation inspection, formal promotion, state conflicts, or explicit handoff. Keep ordinary implementation, smoke, and exploration execution-first; invoke research-artifact-cleanup only for historical or batch cleanup.

Codex Research Workflow

Treat the Codex-opened project root and exact Git root as the same directory. --repo always names that project root. Do not support a parent workspace with a nested project repository; stop and require a user-approved root migration.

Treat Git and checked-in evidence as authoritative. Use:

• AGENTS.md for stable operating, permission, Git, review, storage, and claim rules.
• docs/PROJECT_CORE.md for durable research direction, innovations, components, direction decisions, evidence position, and claim ceiling.
• docs/CURRENT_STAGE.md for the current Gate, reviewed identity, material findings, and one next action.

Conversation summaries are entry pointers, not repository authority.

A research controller or reviewer decides and issues a Goal; Codex executes an already-issued Goal. When acting as the executor, do not adopt the controller role, issue the next Goal, or use the controller response format.

Restore State

At an ordinary new Goal, read the authorities and controlling material needed for that Goal, then perform a lightweight local precheck: exact Git root, branch, HEAD against the expected base, and conflicting index or worktree changes. Do not repeat the controller's remote review or run a full audit merely because a Goal started. Fetch and check the tracking ref, then run workflow.py audit, before commit or push, formal promotion, authority updates, explicit handoff, or when local state conflicts with the Goal. Inspect protected paths only when the Goal reads or changes data, results, or cleanup state. Do not load chronological ledgers or old reports unless current authorities point to them, state conflicts, or historical tracing requires them.

Use the read-only SessionStart Hook only as a compact pointer. A Hook failure is fail-open; an explicit workflow.py audit is fail-closed for material authority or Git conflicts.

Execute Research

Default to the shortest credible empirical loop:

minimal implementation -> real-data run -> metrics -> diagnosis -> direction adjustment -> paper evidence

Prefer restartable end-to-end Goals that reach scientific metrics. Local, recoverable, no-cost work using authorized data may combine implementation, relevant checks, real-data execution, metrics, diagnosis, and adjustment without a new Gate. A separate smoke is exceptional and should test only the smallest representative case justified by a genuinely untested interface or an action that is paid, sensitive, irreversible, externally consequential, or likely to consume a substantial share of the experiment budget if it fails.

Within an issued Goal, reversible evidence-driven adjustments may proceed and be recorded when they do not materially change the core method, research objective, main baseline, final held-out boundary, paper claim, or meaningful cost or risk. Otherwise pause, present facts, uncertainty, two or three routes, costs and information gain, a recommendation, and one clear choice. Do not continue until the user chooses.

Stop when the Goal acceptance criteria pass or the result is sufficient for the next decision. Do not investigate adjacent issues merely for completeness.

Research Reasoning And Communication

When analyzing, interpreting, deciding, reviewing, or writing, follow the assigned task, available evidence, intended audience, and existing claim boundary.

Lead with the best-supported judgment or recommendation, then explain the reasoning and evidence. Add uncertainty, alternatives, limitations, and boundaries only when they could materially change the conclusion, action, scientific validity, reproducibility, or claim.

Do not invent objections, risks, reviewer demands, failure scenarios, experiments, or balancing language merely to appear cautious or comprehensive. Do not dilute an evidence-supported conclusion by giving equal weight to unsupported possibilities. Preserve material uncertainty and negative evidence, but do not distribute defensive qualifications across every analytical step or paragraph.

When a genuine decision has multiple credible routes, explain their material differences, costs, and information value and request the required choice. Otherwise provide the clearest supported conclusion and proceed within the assigned scope.

When reviewing research or prose, report actual factual, methodological, evidential, logical, or material expression problems. Distinguish them from stylistic preferences, hypothetical objections, and requirements unrelated to the active research question or claim.

Validate Proportionately

Default to semantic checks, declared numerical tolerances, material invariants, and existing Git identity. Add a content hash only when exact bytes outside Git materially affect reproducibility or a known integrity failure is not covered by those checks. Do not duplicate commit-bound identities with file, payload, or manifest hashes merely for completeness, and do not use floating-output hashes as numerical acceptance criteria. Preserve an explicit frozen identity contract.

Manage Experiments

Use one experiment root inside the project root, default experiments/; a project may override it only in AGENTS.md. Create it and its subdirectories only when needed. New persistent artifacts must not create ad hoc top-level output roots.

• Keep reusable method code in normal source directories.
• Keep experiment entrypoints/configuration under scripts/ and configs/ in the experiment root when they are needed.
• Keep persistent local runs under runs/<experiment-id>/<run-id>/ with minimal provenance; keep raw and external datasets outside the experiment root.
• Keep dedicated decision-complete evidence under evidence/<experiment-id>/<candidate-id>/ and track it in Git.
• Keep large runs, temporary files, and cleanup plans ignored by Git.
• Delete only temporary files created by the current run when they were marked temporary in advance, the run succeeded, and no reference remains.

Read experiments.md before creating a persistent run. Read evidence-packets.md before preparing material for a durable controller decision or formal promotion.

Review Code And Evidence

Routine exploratory code may continue after task-relevant tests pass. A concise Codex result packet is normally enough for the controller. Request an optional implementation inspection only when tests and results cannot establish the needed correctness or the exact diff is needed to interpret evidence. It may inspect uncommitted work and does not require commit or push unless the reviewer needs GitHub access or the work is entering formal promotion. It creates no formal verdict, record-review, or CURRENT_STAGE.md update.

Use formal promotion only to accept a major implementation baseline, adopt a stable publication evaluation or key result, change the core method, or raise a claim. Pin one exact candidate commit and obtain one qualified independent review from a controller or reviewer with direct access to the exact candidate and evidence. Select that reviewer by actual evidence access, not model tier or surface, and do not duplicate a qualified review. Then create one necessary authority update. Preserve rejected candidates and negative evidence in Git history. Read formal-review.md for this lane.

Codex-reported local results can guide another reversible exploratory step. Before a durable direction change, method/result adoption, or claim change, make the evidence accessible and decision-complete. Prefer existing tracked reports, configurations, results, or registry entries when they already answer the decision question. Create a dedicated evidence packet only when those materials are insufficient or a formal promotion needs a stable bundle. Structure and accessibility validation cannot declare scientific sufficiency.

Maintain Canonical State

Update PROJECT_CORE.md only after a durable strategy, innovation, component, direction, evidence-level, or claim-boundary change. Keep one synthesized entry per core direction, including important superseded or rejected objectives and their evidence pointers. Do not append run-by-run narratives. Detailed results belong in reports, evidence packets, registries, and Git.

Update CURRENT_STAGE.md only after a material milestone, formal review, material blocker, or next-action change. Keep only current effective state; historical detail belongs in reports and Git. Do not enforce byte, line, or token budgets on either authority. Historical accumulation is a warning; conflicting current authorities are an error.

Existing codex-project-core and codex-handoff-state markers remain the compatible internal schema. A brand rename does not create a data migration.

Coordinate Cleanup

Invoke $research-artifact-cleanup only for historical or batch cleanup, not for normal run creation or current-run temporary cleanup. In governed projects, always invoke it together with this Skill.

After a committed PROJECT_CORE.md change that replaces/retires a direction or changes core components enough to obsolete prior experiments, generate a read-only cleanup plan in the same Goal and stop for user review. Text-only edits, evidence additions, and claim narrowing do not trigger cleanup.

Cleanup inventory starts at the entire project root, including ignored local artifacts; Git tracking is evidence metadata, not the scan boundary. Cleanup execution is not a formal research Gate. Use a Cleanup Plan Review, explicit user approval, and a Cleanup Execution Verification. Read cleanup-integration.md when triggered.

Commands

Use the smallest command and read its conditional reference:

py -3 scripts/workflow.py init --repo <repo>
py -3 scripts/workflow.py migrate --repo <repo>
py -3 scripts/workflow.py audit --repo <repo>
py -3 scripts/workflow.py prepare-experiment --repo <repo> ...
py -3 scripts/workflow.py prepare-evidence --repo <repo> ...
py -3 scripts/workflow.py validate-evidence --repo <repo> --path <candidate>
py -3 scripts/workflow.py record-review --repo <repo> --input <review.json>
py -3 scripts/workflow.py resume-prompt --repo <repo> --surface codex|work

Read initialization.md for init or migrate. initialize remains a compatibility alias for the former missing-file-only operation and is not used in new documentation.

Research Controller Contract

Every actionable research-controller-issued Codex Goal starts with $codex-research-workflow. A cleanup Goal also invokes $research-artifact-cleanup. Keep Goals short by pointing to checked-in authorities and reports rather than copying durable detail.

Read work-response-contract.md before generating or evaluating a controller response. Only the user may authorize changing that contract.

The Contract does not govern a Codex executor's final report. After executing a Goal, report only the actual outcome, changed paths, validation or experiment results, commit/push state, and unresolved items or blockers. Do not output the controller headings or a Codex 指令 section.

Explicit Handoff

Automatic context compaction is normal and is not itself a handoff. At an explicit handoff, finish only the safely verifiable operation, re-read current authority and Git state, distinguish pushed facts from chat-only conclusions, run audit, and generate the relevant resume-prompt. Never create CODEX_HANDOFF.md, LATEST_STATE.md, or another dynamic authority.

The installed Skill governs Codex handoff only. Browser Chat and Work do not load it; they follow their Project Instructions, visible context, and the public Work Response Contract. Codex may generate a temporary packet for the user to paste into a browser conversation.

A controller handoff is not a formal review or a reason to update repository authority. A same-conversation reviewer-to-controller switch uses a compact Controller Packet. A new controller conversation needs a temporary Handoff Packet containing the durable strategy and claim ceiling from PROJECT_CORE.md, relevant positive and negative evidence, the current Git transaction, conversation-only decisions or rejected options, and one next decision or action. A recipient with direct repository access reverifies mutable state and may perform the required review. One without it requests one bounded verification from a reviewer with the required access. Do not force a model switch or duplicate a qualified review. Keep the packet temporary unless a material decision independently belongs in repository authority.