Codex AGENTS.md Safety and Verification Instructions Generator

Create a copy-ready AGENTS.md that governs how Codex may inspect, modify, verify, and report work in this repository.

Project inputs
- Project name: [Project name]
- Project purpose: [Project purpose]
- Repository map: [Repository map]
- Tech stack and package managers: [Tech stack and package managers]
- Editable paths: [Editable paths]
- Protected paths: [Protected paths]
- Coding conventions: [Coding conventions]
- Verification commands: [Verification commands]
- CI, build, deployment, and cache commands: [CI build deployment and cache commands]
- Environment and secret-handling rules: [Environment and secret-handling rules]
- Known fragile areas: [Known fragile areas]
- High-risk operations and approval rules: [High-risk operations and approval rules]
- Definition of done: [Definition of done]
- Workflow preferences: [Workflow preferences]

Input and evidence rules
1. Treat the project name, purpose, repository map, editing boundaries, approval rules, and definition of done as required. A verification command may be unknown, but that unknown must be preserved explicitly.
2. Useful supporting evidence includes an accessible repository tree, an existing AGENTS.md, README files, package manifests and lockfiles, formatter or linter configuration, test configuration, framework configuration, CI workflow files, deployment documentation, and contributor guidance.
3. If Codex has repository access, it may perform read-only inspection of relevant files to ground the draft. It must not edit files, run commands, install dependencies, modify configuration, create commits, open pull requests, deploy, migrate data, clear production caches, rotate credentials, or publish anything while generating this document unless the user separately authorizes that action.
4. Distinguish each instruction or command source as owner-supplied, repository-observed, inferred, or unknown. Repository-observed means the exact value appears in inspected project evidence. Inferred content must be labeled for owner review and must not be presented as established fact.
5. Never expose or reproduce secrets, tokens, private keys, credentials, customer data, or sensitive environment values. Refer only to environment variable names or redacted examples when necessary.
6. Do not invent commands, path permissions, deployment procedures, rollback steps, or approval authority. When a required fact is missing or conflicting, ask a focused clarification question if it blocks a safe boundary. Otherwise, produce a bounded draft with a clearly marked owner decision item.
7. If an existing AGENTS.md is present, do not silently replace its instructions. Compare it with the supplied requirements, identify conflicts and scope differences, and produce a proposed consolidated draft plus a short change summary.
8. Account for AGENTS.md scope: repository-root instructions establish the default, while a more specific AGENTS.md in a descendant directory may refine instructions for that subtree. Do not claim that repository instructions override system, platform, user, security, or organizational policy.

Drafting workflow
1. Inspect the supplied evidence and identify the repository architecture, package managers, generated artifacts, test layers, CI entry points, deployment-sensitive files, migration paths, caches, and security boundaries that are actually evidenced.
2. Reconcile editable and protected paths. A protected path takes precedence when lists overlap. Mark ambiguous, missing, generated, vendored, lockfile, schema, infrastructure, credential, and production configuration boundaries for owner review.
3. Convert coding conventions into actionable rules tied to the actual stack, such as formatting, static analysis, dependency policy, framework conventions, database migration practices, backward compatibility, generated-file handling, and test placement. Include only applicable rules.
4. Build a workflow that requires Codex to inspect before editing, state its intended files and approach, keep changes within scope, preserve unrelated work, make the smallest coherent change, and stop when repository state or instructions conflict.
5. Build a command matrix from owner-supplied or repository-observed commands. Separate fast targeted checks from broader tests, linting, static analysis, builds, integration tests, and release checks. Never imply that a command was executed merely because it appears in AGENTS.md.
6. Define approval gates for consequential operations. Deployment, production access, destructive database operations, irreversible migrations, dependency upgrades with broad impact, secret handling, force pushes, history rewrites, cache clearing in shared environments, external communications, and deletion of user or production data must require explicit human authorization when applicable.
7. Define stop conditions and recovery controls. Codex must stop on suspected secret exposure, unexpected destructive output, permission uncertainty, failing preconditions, unrelated repository changes, ambiguous environment targets, unavailable rollback paths, or a verification failure that makes further action unsafe.
8. Define truthful reporting states so future Codex sessions keep proposed, changed, executed, passed, failed, blocked, skipped, unavailable, and unverified work distinct.

Required AGENTS.md structure
Return the complete file in one Markdown code block using these sections:

# Project Instructions
State the project purpose, relevant architecture, primary stack, and the evidence basis for the instructions.

## Instruction Scope and Precedence
Explain repository-root and descendant-directory scope, conflict handling, and the precedence of system, platform, organizational, security, and explicit user instructions.

## Repository Map
Describe important source, test, configuration, generated, vendor, migration, infrastructure, and documentation locations that are supported by evidence. Mark unknown locations rather than guessing.

## Change Authority Matrix
Provide a table with columns for path or resource, allowed action, prohibited action, approval required, evidence source, and notes. Cover editable paths, protected paths, generated files, dependencies, database schemas or migrations, CI configuration, deployment configuration, secrets, and production data when applicable.

## Coding and Change Rules
Specify stack-relevant conventions, dependency and lockfile policy, generated-file policy, migration compatibility requirements, security expectations, scope control, and treatment of unrelated changes.

## Required Work Sequence
Define the inspect, clarify, plan, edit, verify, review, and report sequence. Require Codex to name intended files before editing and to pause when the requested work exceeds authority.

## Verification Matrix
Provide a table with columns for change type, exact command, source, execution authority, expected successful observation, failure handling, and unavailable-command fallback. Include targeted tests, broader tests, linting, formatting, static analysis, builds, and relevant CI or release checks only when applicable. Unknown commands must remain explicit owner action items.

## High-Risk and Production Operations
List applicable approval gates, environment confirmation requirements, backup or rollback prerequisites, dry-run expectations, monitoring or post-change checks, and stop conditions. State that documentation of a command is not authorization to execute it.

## Security and Data Handling
Cover secret redaction, least privilege, sensitive logs, personal or production data, dependency provenance, and incident escalation appropriate to the supplied project.

## Definition of Done
Translate the supplied definition into observable acceptance criteria. Require scope reconciliation, applicable verification evidence, documentation updates where needed, no unauthorized protected-path changes, and disclosure of unresolved failures or skipped checks.

## Completion Report Contract
Require future Codex sessions to report changed files, concise change summary, commands actually executed, actual outcomes, checks not run and why, assumptions, residual risks, approval-dependent actions, and recommended human follow-up. Prohibit claims such as fixed, tested, verified, approved, deployed, rolled back, or completed unless the corresponding action occurred and evidence is available.

After the code block, provide these companion sections:

## Evidence and Decision Register
Use a table with columns for item, classification, source, confidence, conflict or gap, and owner action. Classifications must distinguish supplied fact, repository observation, inference, unknown, and conflict.

## Owner Review Checklist
Include concrete checks for path scope, command accuracy, nested AGENTS.md behavior, secret safety, approval ownership, destructive operations, rollback readiness, verification expectations, and definition-of-done acceptance.

## Proposed Change Summary
If an existing AGENTS.md was inspected, summarize retained, changed, added, and unresolved instructions. Otherwise state that this is a new proposed file.

Final validation
- Confirm every project-specific statement is traceable to supplied or inspected evidence, or is labeled as an inference or unknown.
- Confirm protected paths override editable paths where they overlap.
- Confirm every command is exact and sourced, or explicitly unknown.
- Confirm command documentation and command execution authority are separate.
- Confirm consequential actions require the stated human approval and applicable recovery controls.
- Confirm no secret values or sensitive data are included.
- Confirm acceptance criteria are observable and unresolved states remain visible.
- Confirm no execution, test, approval, deployment, rollback, or completion claim is made without actual evidence.
- Confirm the AGENTS.md is internally consistent and copy-ready, while remaining a proposal until the project owner reviews and installs it.