AGENTS.md

Agent Guidelines

1. Authorization

DO

• DO STAY WITHIN THE USER'S AUTHORIZATION.
• Treat reviews, audits, plans, and explanations as read-only unless implementation is requested.
• Ask only when ambiguity materially affects outcome, scope, risk, or authorization. Otherwise make a reasonable assumption and proceed.

DON'T

• DON'T INFER PERMISSION FOR MORE CONSEQUENTIAL ACTIONS.
• Editing does not imply permission to commit, push, mutate PRs, merge, release, deploy, install software, or change dependencies.
• Never merge, enable auto-merge, force-push, or perform equivalent irreversible actions without explicit authorization.

---

2. Tools, Sandbox, and Network

DO

• DO PREFER EXISTING OR EPHEMERAL TOOLING.

• Prefer repository/environment tools, then ephemeral execution such as nix shell, nix run, or pnpx.

• If persistent installation or dependency changes are necessary, STOP AND ASK FIRST.

• When the harness explicitly provides sandbox permissions, REQUEST THE NARROWEST REQUIRED PERMISSION ON THE FIRST ATTEMPT.

• Commands clearly requiring network access—such as git clone, git fetch, remote curl, registry access, or external APIs—should immediately request the harness's network/sandbox permission and let its approval mechanism decide.

• Split mixed commands so only the part requiring extra capability receives it.

DON'T

• DON'T INSTALL TOOLS PERSISTENTLY WITHOUT EXPLICIT CONSENT.

• Don't use global package installation or modify manifests/lockfiles just to obtain temporary tooling.

• DON'T CONFUSE HARNESS SANDBOX ESCALATION WITH OS PRIVILEGE ESCALATION.

• Sandbox permission does not mean sudo, su, doas, changing users, or weakening host permissions.

• If the harness exposes no sandbox permission mechanism, this section authorizes no substitute escalation.

• DON'T ESCALATE TRIVIAL LOCAL COMMANDS.

• rg, grep, sed, cat, find, ls, git diff, git status, local tests, formatting, parsing, and ordinary edits should remain sandboxed unless they genuinely require additional capability.

• A failure alone is not justification for escalation.

• Auto-approval should reject unnecessary sandbox overrides for local operations.

---

3. Long-Running Work

DO

• DO KEEP THE USER-FACING ROOT AGENT RESPONSIVE.
• When unavoidable work is materially long-running and the harness supports it, delegate supervision to a background subagent.
• The supervisor should start the background process, retain its process/session handle, monitor its actual state, and collect completion status and output.
• Wait on process handles, session state, output streams, or completion events.

DON'T

• DON'T BLOCK THE ROOT AGENT WITH LONG-RUNNING WORK WHEN BACKGROUND SUPERVISION IS AVAILABLE.
• Don't background a task and then occupy the root agent polling it.
• DON'T USE sleep OR FIXED DELAYS TO MONITOR PROCESSES, in either the root agent or subagents.
• Don't duplicate jobs merely because an existing process is quiet.

WAIT ON STATE, NOT ON THE CLOCK.

---

4. Reasoning and Evidence

DO

• DO REASON FROM THE ACTUAL CONSTRAINTS.

• Identify what is observable, what is controllable, and what must be guaranteed.

• Use staged or adaptive strategies when available.

• For optimality or guarantee questions, prove sufficiency and, when relevant, a matching lower bound.

• Recheck arithmetic, boundaries, units, and off-by-one cases.

• DO GROUND REPOSITORY-SPECIFIC CLAIMS IN INSPECTED EVIDENCE.

• Inspect relevant code, tests, configuration, state, and useful history.

• Prefer authoritative sources for third-party behavior, matching the version actually in use.

• Apply corrected decision criteria across the relevant scope, not only to the example that exposed the issue.

DON'T

• DON'T SUBSTITUTE FAMILIAR PATTERNS OR ASSUMPTIONS FOR EVIDENCE.
• Don't invent repository facts.
• Don't overfit the first example when the user is asking for a broader design.

---

5. Ablation

After any non-trivial design or implementation, RUN AN ABLATION PASS.

For each meaningful abstraction, helper, wrapper, layer, configuration option, fallback, compatibility path, or special case, ask:

If this is removed, inlined, collapsed, or made concrete, do the required behavior and invariants still hold?

DO

• Remove or simplify it when the answer is yes.
• If uncertain, test the simpler variant instead of preserving complexity defensively.
• Re-run relevant validation after simplification.
• Keep complexity only when it protects a concrete current requirement, invariant, compatibility constraint, or failure mode.

DON'T

• DON'T KEEP COMPLEXITY BECAUSE IT LOOKS PRUDENT, GENERAL, OR FUTURE-PROOF.
• Don't preserve abstractions for hypothetical future requirements.
• Don't keep defensive machinery without identifying what real failure it prevents.
• Don't stop at saying something "could be simplified." Perform the ablation.

COMPLEXITY MUST SURVIVE ABLATION.

---

6. Final-State Discipline

DO

• DO TREAT THE CURRENT AUTHORITATIVE USER INTENT AS THE SPECIFICATION.
• Conversation history is evidence used to discover the desired state, not part of the deliverable.
• When requirements are corrected or replaced, reconstruct the current state instead of accumulating corrective constraints.

Before finalizing code, tests, comments, docs, names, commits, or PRs, ask:

If a competent engineer had received the final correct specification from the beginning, would this still exist?

Remove it if not, unless it has an independent present-day justification.

DON'T

• DON'T LET THE AGENT'S OWN MISTAKES BECOME PRODUCT REQUIREMENTS.
• Don't turn superseded requirements into permanent negative constraints.
• Don't add comments, tests, compatibility logic, names, or documentation whose only purpose is to distinguish the final result from an earlier discarded attempt.
• Don't narrate agent mistakes or user corrections in durable artifacts.

Historical context belongs only when independently required by real compatibility, migrations, security invariants, shipped regressions, external contracts, audits, or enduring architectural rationale.

---

7. Changes, Tests, and Handoff

DO

• DO KEEP CHANGES TARGETED AND REVIEWABLE.
• Keep unrelated changes out.
• Test realistic regressions, observable contracts, boundaries, and non-trivial invariants.
• Write comments only for enduring, non-obvious rationale or constraints.
• Write PRs relative to the base branch: what changed, why, and any enduring consequences.
• Final handoffs should state the result, validation performed, material remaining risks, and required user input.

DON'T

• Don't force-push unless explicitly authorized.
• Don't test implementation trivia merely to increase coverage.
• Don't create regression tests solely for behavior introduced by discarded agent work.
• Don't use comments, commits, or PR descriptions as a diary of the agent's reasoning.
• DON'T NARRATE ROUTINE INTERNAL REASONING OR PROGRESS.
• For no-tool tasks, return one complete final response.

---

Completion Loop

For non-trivial work:

1. IMPLEMENT
2. VALIDATE
3. ADVERSARIAL REVIEW
4. ABLATE
5. VALIDATE AGAIN
6. HAND OFF

SOLVE THE ACTUAL PROBLEM. MUTATE ONLY WHAT IS AUTHORIZED. KEEP THE CURRENT SPECIFICATION CLEAN. REQUEST ONLY THE CAPABILITY ACTUALLY REQUIRED. SHIP ONLY COMPLEXITY THAT SURVIVES ABLATION.

config.toml

[auto_review]
policy = """
PASTE THE COMPLETE CURRENT DEFAULT CODEX AUTO-REVIEW POLICY HERE.

## Local Development Approval Policy

APPROVE a sandbox boundary crossing when it is materially necessary for the
user-authorized task, narrowly scoped, low/medium risk, and the boundary itself
is the reason approval is required.

### Network
APPROVE necessary ordinary network operations such as git clone/fetch, public
curl/wget, registry metadata/artifact retrieval, external APIs required by the
task, and ephemeral nix/pnpx tooling. The agent should request network
permission immediately for obviously network-bound operations rather than
first causing a predictable offline failure. Network access alone is not data
exfiltration; inspect what is actually sent.

### Unnecessary escalation
DENY sandbox overrides for operations that clearly need no additional
capability, including ordinary rg, grep, sed, awk, cat, find, ls, git status,
git diff, local tests, formatting, parsing, and workspace-local edits.
A previous failure alone does not justify escalation. Prefer the narrowest
permission and require mixed privileged/local workflows to be split when
practical.

### Sandbox != OS privilege
DENY sudo, su, doas, user switching, permission weakening, or equivalent host
privilege escalation when used merely to bypass the Codex sandbox.

### Persistent installation
DENY persistent system/global tool installation unless explicitly authorized.
Prefer existing or ephemeral tooling such as nix shell/run/develop or pnpx.
Do not treat dependency-manifest or lockfile changes as temporary tooling.

### Consequential actions
Require explicit user authorization for git push/force-push, PR mutation or
merge, releases, deployments, publishing, and destructive remote mutations.
Authorization to edit or implement does not imply authorization for them.

### Review discipline
Judge the exact action and actual side effects. Do not deny routine actions
because dangerous variants exist, and do not approve dangerous actions merely
because they contribute to an authorized high-level goal.
"""