codex-autoresearch

name	codex-autoresearch
description	Research-only background queue for Codex CLI. Use when the user wants Codex to evaluate ideas from ideas/*.md, run long experiments under screen, verify results, refine attempts, and stop when the configured research target is met.

codex-autoresearch

This skill now supports one workflow: background research mode.

When Activated

1. Treat every new launch as research.
2. Load references/core-principles.md, references/structured-output-spec.md, and references/runtime-hard-invariants.md.
3. Load references/research-workflow.md, then load only the supporting references that apply: references/session-resume-protocol.md, references/interaction-wizard.md, references/results-logging.md, references/health-check-protocol.md, and references/lessons-protocol.md.
4. For a new launch, inspect the target repo before asking questions. Confirm the research goal, scope, metric direction, verify command, experiment command, ideas directory, stop condition or acceptance criteria, rollback policy, and execution policy.
5. Before launch, check python3 <skill-root>/scripts/autoresearch_hooks_ctl.py status; install or refresh hooks with python3 <skill-root>/scripts/autoresearch_hooks_ctl.py install if required.
6. Start background control with python3 <skill-root>/scripts/autoresearch_runtime_ctl.py launch --repo <primary_repo> --workspace-root <workspace_root> ....
7. For status, stop, or resume, stay on this skill and use the matching autoresearch_runtime_ctl.py or resume helper.

Required Config

• goal
• scope
• metric-name
• direction
• verify
• experiment-command
• stop-condition or acceptance-criteria

Defaults:

• ideas-dir: ideas
• max-refines-per-idea: 5
• research-poll-seconds: 200
• execution-policy: danger_full_access
• verify-format: scalar

Hard Rules

1. Research mode is background-only.
2. Ask for launch confirmation before starting a new run.
3. After launch approval, do not ask mid-run questions; apply the confirmed config and keep going until success, exhaustion, stop, or blocker.
4. Use the helper scripts for authoritative TSV, JSON state, runtime state, and research state updates.
5. Keep autoresearch-results/ artifacts uncommitted and never stage them.
6. Work only inside the declared primary repo scope and autoresearch-owned artifacts.
7. Before each original or refine attempt, create a scoped trial commit when code changes are involved.
8. Use conservative rollback by default: git revert --no-edit HEAD. Use destructive reset only when the launch confirmation explicitly approved a dedicated experiment branch or worktree.
9. Use screen -dmS for long experiments, then exit the Codex turn without waiting.
10. Preserve existing autoresearch-results/results.tsv, state.json, runtime.json, and research/state.json compatibility.
11. Treat the current ideas/*.md file as the only implementation spec for every original or refine attempt.
12. At the start of every original or refine attempt, refresh context from the current idea file, autoresearch artifacts, git status, and relevant recent trial/revert commits; do not rely on chat context alone.
13. After a valid but underperforming result, roll back the failed trial code, revise and separately commit the idea file, then reimplement the next refine from a clean worktree.
14. Do not create standalone refine-*.md specs; keep refine learning in the idea file revision notes and state/results artifacts.

Research Cycle

1. Discover idea files from ideas/*.md, sorted by filename.
2. Establish or load the baseline.
3. Refresh local context from the idea file, state/results artifacts, and relevant git history.
4. Implement the current idea file or the current refined version of that same idea file.
5. Before launch, do a lightweight alignment check: current idea requirements, matching code diff, and no unrelated changes.
6. Launch the experiment under screen with the required AUTORESEARCH_* environment variables.
7. When the screen session ends, run verify.
8. Record keep, discard, crash, or blocked with autoresearch_record_iteration.py.
9. Valid but underperforming results consume refine budget and update the idea file before the next clean implementation.
10. crash and no-op attempts without credible metrics use a separate two-try implementation retry limit and do not consume refine budget.
11. Stop on the configured target, refine within the fixed budget, abandon exhausted ideas, or mark the whole research run exhausted.

Quick Start

Invoke explicitly:

$codex-autoresearch
Use ideas/*.md to evaluate research ideas for this repo. Run each idea as a long experiment and stop when accuracy is at least 90%.

Codex should scan the repo, ask for the missing launch details, show the confirmed background handoff summary, then start the runtime.