---
name: revise-agents-md
description: Capture durable learnings from the current Codex session into AGENTS.md or AGENTS.override.md. Use when the user asks to revise AGENTS.md, update Codex project instructions from this session, capture session learnings, or keep AGENTS.md current at the end of work.
---

# Revise AGENTS.md

Review this session for durable learnings about working with Codex in this codebase. Propose concise updates to `AGENTS.md` or `AGENTS.override.md` that would help future Codex sessions be more effective.

Always show proposed changes before editing. Only apply changes after user approval unless the user provided an exact patch to apply.

## Step 1: Reflect

Identify context that was missing or newly confirmed:

- Commands that were used or discovered.
- Code style patterns followed.
- Testing approaches that worked.
- Environment or configuration quirks.
- Warnings, gotchas, or failure modes encountered.
- Codex-specific workflow notes, such as hooks, plugins, skill locations, or project instruction precedence.

Do not add transient details, personal commentary, or one-off fixes.

## Step 2: Find Instruction Files

Find project instruction files:

```powershell
rg --files -g 'AGENTS.md' -g 'AGENTS.override.md'
```

Choose the right target:

- `AGENTS.md` - Normal shared guidance for the repo or a directory.
- `AGENTS.override.md` - Stronger guidance that should override sibling `AGENTS.md` in the same directory.
- `~/.codex/AGENTS.md` - User-wide Codex defaults, only when the learning is not repo-specific.
- `~/.codex/AGENTS.override.md` - User-wide hard override, use sparingly.

If no project `AGENTS.md` exists and the user wants persistent repo guidance, propose creating one at the project root.

## Step 3: Draft Additions

Keep additions concise. One line per concept is usually enough.

Preferred format:

```markdown
`<command or path>` - <brief durable note>
```

or, for rules:

```markdown
- <specific recurring rule or gotcha>
```

Avoid:

- Verbose explanations.
- Obvious information.
- Generic best practices.
- One-off fixes unlikely to recur.
- Duplicating content already present in a clearer form.

## Step 4: Show Proposed Changes

For each addition:

```markdown
### Update: ./AGENTS.md

**Why:** <one-line reason>

```diff
+<the addition - keep it brief>
```
```

If multiple files could receive the update, explain why the selected target has the right scope.

## Step 5: Apply with Approval

Ask whether the user wants to apply the changes. If approved:

- Edit only the approved files.
- Preserve existing section order where possible.
- Add a new section only when the content does not fit an existing one.
- Keep wording terse and actionable.

## Final Check

Before final response:

- Confirm the final file still reads cleanly.
- Confirm no stale or contradictory guidance was introduced.
- Mention which file changed and what category of learning was captured.