Codex Long Session Governance

Codex Long Session Governance

Purpose

Use this as a cross-repo Context Budget Governor for long Codex sessions. It limits how Codex retrieves, compresses, reads, outputs, and hands off context.

This Skill does not replace project AGENTS.md, repo-specific workflow docs, or business/domain Skills. It governs context handling and repo workflow discipline so those local rules can be read narrowly and followed reliably.

When to use

Use this Skill when any of the following apply:

• long Codex or /goal session;
• staged repo workflow or multi-PR workflow;
• large repo or unfamiliar repo;
• long logs, long Markdown docs, generated reports, checkpoint docs, large CSV, JSON, parquet, or text dumps;
• Codex has shown or may show stale memory, hallucination, context truncation, repeated broad reads, excessive token use, or workflow drift;
• the next action must be derived from repo evidence rather than chat memory;
• the user asks to reduce token burn, manage context, avoid truncation, or create a durable handoff.
• the user asks to shorten an oversized /goal or split detailed instructions into repo docs, handoff, controller docs, or task-specific Skills.

When not to use

Do not use this Skill for:

• one-off small answers;
• tiny edits to one known file;
• tasks where the user explicitly says not to use Skills;
• tasks with no long-context, repo-governance, log-reading, data-reading, PR-gate, or token-budget concern;
• purely creative writing or translation tasks unrelated to repo workflow.

Desired outcome

The session stays evidence-first, bounded, and resumable. Codex should choose the next action from current repo evidence, cap unknown output, pre-compact raw data and logs, update or propose a living handoff when needed, advance one PR-sized stage at a time, and stop at gates instead of drifting.

For long /goal sessions, the launch prompt should stay short and index-like. Detailed requirements should live in the right repo document or Skill, with /goal pointing to those sources instead of repeating them.

Success criteria

• Current repo state is checked before implementation.
• Level 0 and Level 1 context are used before broad reads.
• Unknown or potentially large command output is capped.
• Long files are searched or sampled before any full read.
• Raw data and generated reports are pre-compacted into a needle map before analysis.
• Handoff state is updated or proposed before context becomes stale or oversized.
• Oversized /goal prompts are compressed into an index-style controller without dropping hard requirements.
• Detailed stage specs, current state, permanent rules, and historical logs are placed in the right document type.
• Repo work advances one small PR-sized stage at a time.
• PR gates, dirty worktrees, truncation, destructive operations, and high-risk ambiguity stop the workflow.
• Final reports are concise and do not paste full logs, full generated reports, or raw data.

Inputs and context to collect

Collect only the smallest useful set first:

• repo root, current branch, dirty worktree state, remotes, and recent commits;
• explicit user scope, forbidden paths, and allowed write paths;
• nearest AGENTS.md and first-pass handoff or repo-map docs if present;
• current PR gate state if gh is available and authorized;
• active stage, target files, expected checks, and stop conditions.

Do not inspect secrets, .env content, credentials, SSH keys, API keys, config.toml, or unrelated local configuration files.

Operating principle

Use these invariants:

• Evidence over memory.
• Pre-compact before reading raw data.
• Narrow search before broad read.
• Byte-cap unknown output.
• Summarize; do not paste.
• One PR-sized stage at a time.
• Stop at merge gates.
• Paused External PR Gate State: An open or not-verified-merged PR gate is an

external wait state. After reporting it once, Codex must pause the active goal and wait for explicit user resume. Automatic continuation without a user-stated merge/resume/inspect instruction must not query GitHub again, must not repeat gate reports, must not mark the goal complete, and must not mark the goal blocked merely because the same external PR is still pending.

• If the interface forces a response during the paused external PR gate state,

return only: Waiting for PR #X to merge; no checks run.

• Never merge PRs.
• Do not rely on truncated output.
• Keep /goal short; place durable instructions in the right source of truth.
• Update handoff before context becomes stale or oversized.
• Do not create permanent helper files unless the repo scope allows it.

Prompt Compression And Instruction Placement Policy

Long /goal should not be a full specification. Treat /goal as an index-style controller containing only the goal, current context, scope, constraints, done-when criteria, validation, stop gates, and final report format.

When practical, target about 2,000-3,500 characters for /goal. If the prompt is approaching 4,000 characters, split instructions into repo docs and make /goal reference them.

Detailed specs should move into repo docs when allowed. Do not paste complete stage specs into /goal if they can live in docs/STAGE_PLAN.md, docs/current_handoff.md, a controller doc, or a task-specific Skill.

Never silently drop hard requirements during compression. Move them to the correct document or mark them as omitted or unknown.

Instruction Placement Matrix

| Location | Belongs there | Keep it concise by | | --- | --- | --- | | Global AGENTS.md | Permanent cross-project behavior rules, Skill-first routing, broad-read avoidance, secret safety, small PR preference | Keeping only stable rules | | Project AGENTS.md | Repo-specific permanent discipline, test commands, safety rules, repo conventions | Avoiding active-stage details | | docs/current_handoff.md or HANDOFF.md | Current state, branch or PR state, last completed checkpoint, known blockers, next action, do-not-reread list | Keeping it actionable and current | | docs/STAGE_PLAN.md or equivalent | Full stage or task specification, deliverables, detailed requirements, optional items, acceptance criteria | Removing state already in handoff | | Controller doc | Stop conditions, PR gates, context budget, logging rules, long-running workflow discipline | Keeping reusable workflow rules only | | Logs | Historical record only, such as engineering, decision, or troubleshooting history | Reading by targeted search or tail, not first-pass | | Task-specific Skill | Reusable workflow rules for one class of tasks | Excluding one-off stage details unless generalized | | /goal | Short launch index: what to do now, docs to read first, scope, validation, stop gates, final report format | Referencing docs instead of restating them |

How to shorten an oversized /goal

Keep in /goal:

• task objective;
• current known state, limited to 1-3 lines;
• first-pass docs to read;
• scope and deliverables;
• hard safety boundaries;
• validation commands;
• stop gates;
• final report format.

Move to STAGE_PLAN.md:

• detailed class, function, or file-level notes;
• long rationale;
• detailed optional extensions;
• extensive examples;
• full acceptance criteria;
• edge-case matrices.

Move to current_handoff.md:

• latest branch, commit, or PR state;
• what was completed;
• current blocker;
• next recommended action;
• do-not-reread list.

Move to a controller doc:

• general stop conditions;
• context ladder;
• output caps;
• logging discipline;
• PR gate behavior.

Delete from /goal:

• repeated explanations;
• motivational text;
• duplicated safety rules;
• optional features that expand scope;
• long background paragraphs;
• stale context;
• project-specific narrative not needed to execute the checkpoint.

Stage Plan Split Policy

When a task prompt is too large, first create or update a detailed stage plan doc if repo rules and user scope allow doc changes. Then replace the long /goal with a compact reference to that doc.

If modifying repo docs is not allowed, ask the user to store the detailed spec externally or provide a shortened task index. Preserve hard requirements by moving them, not deleting them.

Context Budget And Retrieval Policy

Use the lowest level that can answer the current question. Escalate only when the prior level is insufficient.

Level 0: repo state only

Use low-output commands first:

• git status --porcelain
• git branch --show-current
• git remote -v
• git log --oneline -15
• git diff --name-only
• git diff --stat
• gh pr status or gh pr list only if available and authorized

Level 1: first-pass docs only

Read only the smallest source-of-truth docs:

• AGENTS.md
• README.md summary or headings only if long
• HANDOFF.md if present
• docs/current_handoff.md if present
• docs/repo_map.md if present
• project-specific controller doc only if explicitly identified

Level 2: active-stage docs only

Read only docs directly relevant to the current stage:

• active roadmap, design, or spec doc;
• relevant test or command docs;
• nearest directory-specific AGENTS.md if applicable.

Level 3: targeted long-log search

For long logs, docs, and reports, use:

• Select-String with an explicit pattern;
• rg with an explicit pattern if available;
• Get-Content -Tail N;
• Get-Content -TotalCount N;
• small explicit line ranges;
• headings-only scans;
• filename and diff-stat summaries.

Level 4: full-file read

Full-file read is allowed only if absolutely required. Before doing it, Codex must state:

• why targeted search is insufficient;
• why this specific file is needed;
• how output will be capped;
• what will be done if output is too large.

Long-file definition

Treat these as long or risky unless proven small:

• docs/engineering_log.md
• docs/decision_log.md
• docs/troubleshooting_log.md
• CHANGELOG.md
• reports/*.md
• reports/experiment_logs/*.json
• generated reports
• checkpoint docs
• long design docs
• dependency lockfiles
• archived logs
• raw CSV, JSON, parquet, and data dumps
• output/private
• node_modules
• .venv, venv
• dist, build, target
• .git internals
• cache directories
• __pycache__, .pytest_cache, .mypy_cache, .ruff_cache, coverage, htmlcov

Default behavior:

• Do not read multiple long files in parallel.
• Do not print full generated reports.
• Do not recursively inspect excluded directories.
• Do not open raw data directly when a summary or needle map can answer the question.

Command Output Protection

Any command with unknown or potentially large output must be capped.

PowerShell-safe patterns:

• git status --porcelain | Select-Object -First 80
• git diff --name-only | Select-Object -First 120
• git diff --stat | Select-Object -First 120
• git log --oneline -20
• Get-Content path\to\file -TotalCount 80
• Get-Content path\to\file -Tail 80
• Select-String -Path path\to\file -Pattern "KEYWORD" | Select-Object -First 40

For commands that may explode:

• write output to a temp file first;
• inspect only head, tail, or small ranges;
• do not paste the full temp output;
• use $out = 2>&1 | Out-String, then $out.Substring(0, [Math]::Min($out.Length, 6000)).

If more context is needed, narrow the query. Do not simply increase the cap.

Default cap:

• unknown command output: 6,000 characters;
• log grep/search results: 40 matches;
• file head/tail: 80 lines;
• data sample: 20 rows max;
• final report: concise summary only.

Pre-Compact Raw Data Policy

Never feed raw data first if the task can be answered from a compact map.

For CSV, JSON, log, report, and data-heavy tasks, require a needle map before analysis:

• row counts;
• column names;
• dtypes or schema;
• missingness/null counts;
• min/max dates;
• small sample, max 20 rows;
• top N anomalies, max 50;
• relevant filtered snippets only;
• source file paths, not full content.

If the repo already has scripts such as repo_map.py, summarize_data.py, compact_logs.py, scan_errors.py, or similar, prefer them.

If no helper exists:

• use one-off PowerShell or Python commands to summarize without printing raw data;
• create a temporary summary file only when needed;
• do not commit temporary summary files unless the task explicitly asks for a durable tool;
• if creating a durable helper script, keep it small, read-only, local-only, and documented.

Living Handoff Policy

For long sessions, use a living handoff as the project brain.

Preferred files, in order:

• HANDOFF.md
• docs/current_handoff.md
• docs/handoff.md

If none exists, do not create one unless:

• the task is long-running or multi-PR;
• the user allows doc changes;
• creating it is within scope.

Handoff target size:

• under about 1,000 tokens;
• preferably under 150 lines;
• compact and actionable;
• no raw logs;
• no full command output;
• no dead ends unless they prevent repeated mistakes;
• no speculation preserved as fact;
• not a second engineering log.

Handoff must include:

• current goal;
• branch and PR gate state;
• last completed checkpoint;
• key files;
• checks run and outcomes;
• known blockers;
• do-not-reread list;
• next recommended action.

End long stages with: Compact current findings into the handoff. Strip repetitions and failed paths. Keep only actionable facts needed to continue.

Do-Not-Reread Policy

Handoff may include a Do not reread unless needed section listing:

• long logs;
• generated reports;
• archived outputs;
• prior failed paths;
• raw data files;
• dependency directories;
• files already summarized in repo maps or handoffs.

Respect this list unless the active task directly requires targeted retrieval. If retrieval is needed, search or sample narrowly and update the handoff only with verified facts.

Periodic Compaction Rule

For long sessions, compact manually before context gets stale:

• after 4-5 substantial turns;
• after opening a PR;
• after resolving a major blocker;
• after a large debugging branch;
• before switching stages;
• immediately after any truncated output.

Manual compaction means:

• update or propose update to handoff;
• summarize verified facts only;
• list unknowns explicitly;
• do not preserve speculation as fact;
• do not paste historical logs.

Output Budget Policy

Default output should be short.

Do:

• summarize command results;
• report changed files;
• report checks run;
• report blockers;
• show snippets only when needed;
• show patch summary instead of full file content.

Do not:

• paste full large files;
• paste full logs;
• paste full generated reports;
• restate long plans unless the plan changed;
• include verbose narrative in final reports.

Final reports should include only relevant items from this list:

• stage;
• branch;
• commit hash if available;
• PR link if available;
• changed files;
• checks run;
• risk classification;
• auto-merge status if a PR exists;
• issues by severity;
• assumptions;
• next recommended stage;
• confirmation that Codex did not merge PRs.

Repo Workflow Governance

Before implementation:

• check branch;
• check dirty worktree;
• check remotes;
• check the open PR gate once if tooling is available;
• if a PR gate is not verified merged, report one concise gate summary, enter

the paused external PR gate state, and do not run checks, protection queries, review queries, baseline validation, or another stage until explicit user resume;

• read Level 1 context only;
• choose one small PR-sized stage;
• state assumptions only if needed.

During implementation:

• avoid unrelated changes;
• avoid large broad reads;
• run focused checks first;
• run full relevant checks before final;
• self-review changed files and guardrails.

Stop conditions:

• dirty worktree before new stage;
• PR gate not verified merged, including open, closed-unmerged, unknown, or

otherwise unproven merge state; -

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: minqiyang
• Source: minqiyang/skills-from-scratch
• License: MIT

Install and usage instructions live in the source repository linked above.