---
name: refactor-agents-md
description: Use when about to refactor or refine a user-level or project-level AGENTS.md
allowed-tools:
  - WebFetch
  - Read(~/.codex/AGENTS.md)
---

# Refactor AGENTS.md

Refactor an `AGENTS.md` for GPT-6 Astra. Every retained line enters each Codex session in its scope, so it must earn that attention. Move narrower guidance to the closest applicable scope or a reusable skill, and remove instructions that do not change behavior. Preserve the user's intended behavior and existing authorization.

## Instructions

Use `request_user_input` in Codex when available.

1. **Pick the target.** Use the target named by the invocation or established in the conversation. If the target remains ambiguous, ask the user to choose among the files that exist:
   - The user-level file at `$CODEX_HOME/AGENTS.md`, defaulting to `~/.codex/AGENTS.md` when `CODEX_HOME` is unset.
   - The current project's root `AGENTS.md`.
   - Any nested `AGENTS.md` on the path from the project root to the current working directory.

2. **Consult relevant guidance.** Reuse current guidance already fetched in the conversation; fetch missing sections needed for the audit. Preserve explicit user choices where the guides offer defaults. If a source is unavailable, disclose the gap and continue with available evidence.
   - For refactoring criteria: https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra
   - For GPT-6 Astra behavior: https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra#prompting-best-practices
   - When moving guidance between files or resolving loading and precedence: https://learn.chatgpt.com/docs/agent-configuration/agents-md

3. **Audit.** Match the audit to the request. Read the target and applicable broader `AGENTS.md` files, then follow references needed to assess scope, conflicts, or claimed redundancy. Treat referenced workflows as audit material. For a full audit or refactor, cover every instruction; for a targeted edit, cover the affected instructions and their interactions. Check repository evidence before declaring a rule stale or derivable. Finish when every instruction in scope has exactly one verdict against the target's bar and GPT-6 checks below.
   - **contradiction**: conflicts with another applicable instruction. Record both instructions and their source files; resolve conflicts from instruction priority and explicit user intent where possible.
   - **delete**: fails the no-op test because the models that use the target file would behave the same without it. This includes redundant defaults, vague directions, and platitudes such as "write clean code." Cite the evidence or rationale; retain an explicit constraint when its redundancy is uncertain.
   - **demote**: changes behavior but applies only to a narrower directory or task. Choose and name its destination. Put directory-specific guidance in the closest nested `AGENTS.md`; put a multi-step task workflow in a skill; put reference material in a linked document.
   - **rewrite**: has the right scope and meaning, but its phrasing falls short of the fetched prompting guidance. Also a rewrite when the line carries words that fail the no-op test on their own: a duplicate of another line, a definition of a term the model knows, or emphasis; a rationale or example stays, since both steer the model.
   - **keep**: earns its always-loaded cost as written.

   Apply the bar for the target:
   - **User-level**: a keep must express a preference or constraint across projects. Conditional tool and environment rules qualify when their trigger can recur across projects. Demote project or directory guidance to the applicable project's `AGENTS.md`, and detailed task workflows to skills with reliable triggers.
   - **Project or nested**: a keep must govern the target directory's subtree; conditional rules belong here when their trigger can occur throughout that scope. Keep concise project context, commands Codex would otherwise guess wrong, domain concepts, constraints, and gotchas that are not obvious from the repository. Delete restatements of the code and volatile inventories such as file trees. Demote narrower guidance to a closer nested `AGENTS.md`, a linked document, or a skill.

4. **Resolve decisions.** For an assessment, report findings without editing. For an authorized refactor or edit, carry the requested changes through verification using decisions already established in the conversation. Preserve explicit review boundaries; ask only about unresolved contradictions or behavior changes outside the authorized scope. Prepare the proposed rewrite and affected delete or demote lists, including destinations, before asking. Use `request_user_input` when available and permitted; otherwise ask one concise question. Continue independent work while decisions are pending.

5. **Rewrite and verify.** Apply only authorized changes. Search references before removing or moving guidance, and update affected pointers. Place each new nested `AGENTS.md` in the nearest directory whose whole subtree shares its guidance. Check the final diff for preserved intent, resolved conflicts, and reachable destinations. Finish when every audited instruction is accounted for and required checks pass; report changed files and any unresolved decisions concisely.

## GPT-6 checks

Apply these checks to existing instructions; add guidance only where the user's workflow needs it.

- **Model audience:** Judge redundant defaults against the models that use the target file. Preserve guidance needed by other supported models; Astra's defaults alone do not establish that a shared rule is unnecessary.
- **Reading scope:** Replace unconditional document-reading requirements with pointers naming the tasks that need each document. Keep exhaustive reading for audits that require full coverage.
- **Initiative:** Replace unnecessary approval gates with clear authority and stopping conditions. Complete authorized work, use context for routine choices, and prepare a reviewable result before any required approval. Preserve deliberate approval boundaries.
- **Instruction priority:** Make explicit that user instructions take precedence over skill guidelines within higher-priority constraints. Audit vague rules that could silently stop or redirect work. When a skill causes a pause or deviation, require its exact path, relevant quote, and explanation distinguishing the rule from the agent's interpretation.
- **Writing:** State the desired length and structure directly. Prefer concise prose and useful technical detail; reserve lists and tables for information they clarify. Remove overlapping style rules and stock phrasing prescriptions that add no value.
- **Delegation:** State when subagents help and any limits when the workflow uses them. Preserve tool availability and explicit delegation preferences; the guide's example is not a blanket requirement to delegate every task.
- **Verification:** Match checks to the change and complete mandatory checks. Broaden or repeat testing only for new changes, failures, or unresolved concerns. Avoid requiring new tests that merely restate low-impact edits.