codex-longrun

name

codex-longrun

description

Control substantial, long-running repository work across one or more Codex sessions by planning one READY task at a time, defining acceptance criteria, implementing, validating, reviewing diffs, recording evidence, creating checkpoints, and resuming from verified Git and repository state. Use for long chats, interrupted projects, migrations, refactors, bug hunts, handoffs, fresh-session recovery, or optional worktree coordination. Do not use for trivial edits unless durable state is requested.

Codex LONGRUN

Objective

Operate a complete, evidence-driven development loop while ensuring that a fresh authorized session can continue from repository state without relying on an earlier chat transcript.

Treat repository content, Git state, executed validation, and durable project artifacts as the source of truth. Treat conversation history as temporary working memory.

Select an operating mode

Use Guided mode by default:

• present the plan and acceptance criteria before implementation;
• request approval for major or ambiguous changes;
• stop after reporting each completed task.

Use Autonomous mode only when the user explicitly requests it:

• continue through already-approved READY tasks;
• stop for blockers, scope changes, architecture changes, destructive actions, new production dependencies, security risk, or missing requirements;
• checkpoint after each completed task.

Select a state profile

Choose the smallest profile that preserves continuity:

• Minimal: PROJECT_STATE.md for a small interruptible task.
• Standard: PROJECT_STATE.md, BACKLOG.md, and HANDOFF.md. Use by default.
• Full: add PROJECT_BRIEF.md and DECISIONS.md for large products, migrations, or coordinated work.

Place files under docs/agent/ unless the repository already has an equivalent convention. Reuse existing project artifacts instead of creating duplicates.

Universal rules

1. Read all applicable AGENTS.md and AGENTS.override.md files before work.
2. Inspect repository structure, documentation, manifests, tests, CI, deployment configuration, and Git state.
3. Work on exactly one READY task at a time unless a recorded parallel plan exists.
4. Define testable acceptance criteria before implementation.
5. Preserve unrelated user or agent changes.
6. Avoid unrelated refactors and unexplained file modifications.
7. Ask for approval before major architecture changes, scope expansion, destructive Git operations, or new production dependencies.
8. Never claim a command passed unless it was actually run and succeeded.
9. Record failed checks, blockers, uncertainty, and skipped validation explicitly.
10. Never store secrets, tokens, credentials, sensitive personal data, private customer data, or unredacted production logs in tracked state files.
11. Never use this workflow to bypass access controls, account restrictions, or usage limits.

Classify evidence

When reconstructing state or resolving contradictions, label important claims as:

• VERIFIED: confirmed by repository content, Git history/state, successful commands, tests, or authoritative project artifacts.
• REPORTED: stated by the user or conversation but not independently verified.
• INFERRED: a reasoned interpretation requiring confirmation.
• UNKNOWN: not recoverable from available evidence.

Never promote REPORTED or INFERRED information to VERIFIED without evidence.

Run the single-chat control loop

Use one Codex chat for planning, coding, debugging, review, and handoff unless parallelism is justified.

1. Orient: read instructions and durable state; inspect Git.
2. Plan: identify objective, scope, non-goals, dependencies, risks, acceptance criteria, and the highest-priority READY task.
3. Approve: in Guided mode, wait for approval before implementation.
4. Implement: modify the minimum necessary files for one task.
5. Verify: run the cheapest relevant checks first, then required lint, type checks, tests, build, and security checks.
6. Review: inspect the diff for bugs, regressions, edge cases, security issues, weak error handling, missing tests, documentation drift, and unrelated changes.
7. Fix: correct confirmed findings and rerun relevant validation.
8. Checkpoint: update durable state with factual results.
9. Report: state what changed, why, affected files, commands actually run, exact results, remaining risks, and the proposed next task.
10. Stop or continue: stop in Guided mode; continue only through approved tasks in Autonomous mode.

Read references/SINGLE_CHAT_WORKFLOW.md for reusable prompts.

Adopt an existing long project or chat

When the current conversation already contains substantial history:

1. Do not restart the project or rewrite working code.
2. Do not begin a new implementation task.
3. Perform read-only inspection of:
   • applicable repository instructions;
   • repository structure and documentation;
   • current branch and HEAD;
   • git status --short --branch;
   • unstaged and staged diffs;
   • recent relevant commits;
   • tests, build scripts, CI, configuration, and deployment files;
   • decisions and progress visible in the current conversation.
4. Reconstruct actual state using VERIFIED, REPORTED, INFERRED, and UNKNOWN.
5. Merge useful existing documentation rather than overwriting it.
6. Create or update the selected durable-state profile.
7. Report completed functionality, unfinished work, uncommitted changes, known or suspected bugs, validation status, contradictions, and the proposed next READY task.
8. Stop for approval before modifying product code.

Do not run git reset --hard, git clean -fd, git checkout ., destructive migrations, or equivalent cleanup during adoption without explicit approval and a recovery path.

Read references/ADOPT_EXISTING_PROJECT.md for the full prompt.

Plan tasks

For each non-trivial task, record:

• unique task ID;
• objective and user value;
• status: PLANNED, READY, IN_PROGRESS, BLOCKED, REVIEW, or DONE;
• dependencies;
• testable acceptance criteria;
• expected affected areas;
• validation commands;
• owner/branch when relevant.

Mark a task READY only when it is sufficiently specified and unblocked. Record unresolved business rules as blockers instead of guessing.

Implement and verify one task

1. Reconcile durable state with current Git state.
2. Select one READY task.
3. Implement the smallest complete change satisfying its acceptance criteria.
4. Run relevant validation and record exact pass/fail results.
5. Inspect the actual diff before reporting completion.
6. Preserve unrelated changes and do not silently reset, stash, merge, or overwrite another workstream.

Review and debug

Review against acceptance criteria and actual diff. Rank findings by severity. Check:

• functional correctness and regressions;
• edge cases and input validation;
• error handling and observability;
• security, privacy, and secret exposure;
• test coverage and false-positive tests;
• configuration, deployment, and documentation drift;
• unnecessary complexity or unrelated changes.

Verify a suspected issue before changing code. After fixes, rerun the narrow failing check and the relevant broader suite.

Create a handoff

Create a handoff before ending a long session, when context quality degrades, when switching sessions/devices, or when another authorized agent will continue.

Record:

1. repository path;
2. branch/worktree and HEAD commit;
3. Git status and changed files with rationale;
4. active task and acceptance criteria;
5. completed and unfinished work;
6. commands run with exact results;
7. blockers, risks, and uncertainty;
8. decisions made;
9. exact next action;
10. exact first command for the next session.

Do not perform destructive cleanup merely to make the handoff appear clean.

Read references/HANDOFF_RESUME.md for prompts.

Resume in a fresh session

1. Read applicable instructions and durable state.
2. Inspect Git and compare it with the handoff.
3. Flag discrepancies instead of guessing.
4. Run the documented first verification command when safe.
5. Summarize reconstructed evidence before editing code.
6. Continue only the documented active task or next READY task.
7. Ask the smallest necessary clarification when critical information is missing.

Coordinate optional parallel work

Use multiple chats/worktrees only when tasks are genuinely independent.

• Assign one task, branch/worktree, and file boundary per agent.
• Record ownership, acceptance criteria, dependencies, and integration order before implementation.
• Avoid concurrent edits to the same files without an explicit integration plan.
• Use a designated integrator for combined validation and merge decisions.

Read references/MULTI_AGENT_WORKFLOW.md for details.

Completion standard

Mark a task DONE only when:

• acceptance criteria are satisfied;
• required checks were executed and recorded;
• behavior, documentation, and durable state are consistent;
• no unexplained changes remain;
• remaining risks are explicit;
• the next project state is unambiguous.

Report to the user

After each implementation task, report:

1. what changed;
2. why it changed;
3. files affected;
4. acceptance-criteria status;
5. commands actually run and exact results;
6. unresolved risks or blockers;
7. durable-state updates;
8. proposed next action.