Reusable defaults for coding agents. Adapt stack details, commands, paths,
product context, and local conventions in the project's active AGENTS.md.
- Follow the repository's existing style, structure, architecture, and stronger
local instructions. Keep product and business decisions aligned with
PLANS.mdwhen it exists. - Use
PLANS.mdfor durable product context, business rules, sequencing, priorities, deferred requirements, product or implementation decisions, and major completed milestones.
- Read and preserve an existing
PLANS.mdduring initialization and template reconciliation; semantically merge durable content instead of replacing it. - Create
PLANS.mdonly when repository evidence contains real roadmap items, durable decisions, or resume-worthy completed work. Never invent or backfill speculative history. - Keep it concise, using sections such as current context, decisions, roadmap/status, and major milestones. It is not a per-change changelog.
- Move roadmap or history misplaced in
AGENTS.mdintoPLANS.mdwhen the content is durable, and keepAGENTS.mdfocused on always-on instructions.
- Before planning, classify the requested work and select only the project skills and supporting references required for that work and its necessary validation. Do not load every available or linked guide preemptively.
- Route every task by narrow relevance. Representative examples: testing work uses applicable testing guidance; UI appearance or interaction work uses styling/UI guidance; visual-regression work may require both; unrelated tooling uses neither. Load release or deployment guidance only when that operation is requested or required. Apply the same classification to any other project-specific workflow.
- Keep
AGENTS.mdfocused on durable, always-applicable repository context: architecture, conventions, commands, safety and authorization boundaries, verification expectations, and concise pointers to specialized workflows. - Use project skills under
.agents/skills/<skill-name>/SKILL.mdfor repeatable, task-specific workflows or detailed guidance needed only for matching tasks. - In existing projects, review large task-specific procedures in
AGENTS.md. When a procedure is reusable and conditionally relevant, extract it into a project skill and leave a concise routing rule inAGENTS.md. - Preserve critical safety, authorization, destructive-operation, database, and
deployment restrictions in
AGENTS.md, even when a skill contains the detailed workflow. - In new projects, begin with a concise
AGENTS.md. Add a skill only after a concrete repeatable workflow or specialized procedure is identified; do not create speculative skills. - Avoid duplicating detailed instructions between
AGENTS.mdandSKILL.md. Keep the always-on rule inAGENTS.mdand the conditional procedure in the skill. - Each project skill must use valid YAML frontmatter with a clear
nameand adescriptionthat states when the skill should trigger. - Put substantial conditional detail in a skill-owned Markdown reference only
when it improves selective loading. The owning
SKILL.mdmust state exactly when to read it; never replace actionable guidance with a bare link.
-
TEMPLATE_AGENTS.mdis a staged reference copy of codex-kit's reusable instructions, not active project guidance. Active repository guidance lives inAGENTS.mdand applicable project skills under.agents/skills. -
When the template is refreshed,
codex-kit project statusreportsreconciliation required, or a user requests template sync or mark-applied, use the global$codex-kit-reconcile-agentsskill. It compares the template withAGENTS.md, project state, and existing skills; preserves local rules; applies only relevant reusable changes; validates them; and marks applied only after success. -
Keep project-specific rules out of
TEMPLATE_AGENTS.md. Treat local template edits as candidates that must be generalized and promoted to the canonicalassets/TEMPLATE_AGENTS.mdin the codex-kit repository. UpdatingAGENTS.mddoes not update either template automatically. -
Keep project-specific context out of the packaged template; keep only reusable cross-project rules here.
-
When a request introduces a reusable workflow preference, convention, agent behavior, tooling default, or safety rule, tell the user it appears template-level and update the current project's active instructions when appropriate.
-
After a likely template-level project change, remind the user to update the packaged template, publish a version, and sync affected projects. Specify:
- the target section and whether to add a bullet, subsection, or section
- whether it replaces an existing rule or adds one
- exact reusable wording or a concise patch
- for replacements, the old and new behavior
- for additions, why the rule applies across projects
-
Merge template updates into other projects without overwriting project-specific context.
Do not copy the complete template into AGENTS.md, replace it wholesale, or
introduce managed markers. If a legacy shared-template marker is present,
preserve local content and reconcile its meaning safely without creating new
markers. Summarize added, updated, skipped, adapted, and skill-moved guidance,
including local/template conflicts and any generalized template-worthy
promotion. Keep critical safety, authorization, secrets, database, deployment,
and destructive-operation rules always-on in AGENTS.md; extract only concrete
conditional procedures into validated project skills.
Classify both existing and incoming guidance by task relevance, keep the
always-on baseline concise, and route conditional detail through narrowly
triggered skills and selectively read references.
- Match nearby code before introducing patterns, abstractions, dependencies, or file organization. Consistency outranks personal preference and generic best-practice refactors.
- Keep changes minimal, localized, and limited to the request. Do not reorganize major modules, refactor core systems, add frameworks, or change architecture or project paradigms without explicit approval.
- Work within imperfect architecture. If it prevents safe completion, stop, explain the limitation, propose the smallest viable design change, and wait for approval. Escalate blockers instead of bypassing them.
- Keep identical configuration and behavior in one source of truth at the narrowest shared scope. Reuse that owner across callers or features; create a separate implementation or instance only when scope, lifecycle, or behavior genuinely differs. Reuse existing constants, schemas, enums, shared types, and components before creating duplicates. Add reusable domain values at their existing source of truth instead of scattering magic strings.
- Replace numeric literals that encode domain rules, limits, durations, units, or protocol values with descriptively named constants. Universally obvious structural values, such as basic indexes or empty-state values, may remain inline.
- Promote repeated closed-set domain values used in production control flow to feature-owned immutable runtime constants. Where the language supports it, derive static types from that runtime source; keep incidental presentation, browser, protocol, route, environment, and test-contract strings inline.
- Before changing code, inspect manifests, configuration, scripts, and nearby files to identify the repository's actual stack, commands, and conventions. Do not assume tools from other projects.
- Keep discovered stack-specific guidance in the project's
# Project-Specific Instructions, not in this shared template. - For user-facing work, perform a UI/style preflight before editing: inspect the closest same-purpose shipped features (especially tables, filters, search, forms, dialogs, and page layouts) and identify their design-system primitives, tokens, spacing, typography, responsive behavior, interactions, states, and accessibility conventions. Reuse applicable components and patterns.
- For new or materially changed user-facing interfaces, preserve accessibility as a baseline: prefer semantic elements and native controls; provide accessible names, labels, instructions, errors, and state; support keyboard operation, logical focus order, visible focus, and appropriate focus management; provide meaningful text alternatives; maintain readable typography and sufficient contrast; and never rely on color alone to communicate meaning. Use ARIA only when native semantics are insufficient, and keep ARIA roles, properties, and states valid and synchronized with behavior.
- When practical, verify changed interaction paths with the repository's accessibility tooling and a manual keyboard/focus check. Report any unavailable checks or known limitations.
- If no written standard exists but trustworthy repeated precedent does, derive
concise durable guidance in the project: always-on conventions belong in
AGENTS.md; feature-specific decisions and approved exceptions belong inPLANS.md. During development, keep new UI aligned with that standard. - Pause and ask the user whether to keep, update, or override the standard before deliberate visual divergence, changing an established guideline, resolving conflicting precedents, or proceeding without a trustworthy analogue. Include the evidence and affected pattern in the question.
- If browser or screenshot tooling exists, compare the rendered feature with the analogue across relevant responsive sizes and states. Otherwise, report that rendered comparison was unavailable.
- Avoid broad commands. After changes, run the smallest targeted verification that meaningfully validates them when practical, then report the command and result. Use the repository's documented package manager and scripts.
- Select tests for regression value rather than exhaustive coverage. When the repository has an established test setup, cover changed observable contracts, reported regressions, meaningful boundaries, and plausible costly failures, especially security, trust-boundary, or data-loss risks.
- Use one representative case per equivalent behavior class. Skip redundant permutations, implementation-detail assertions, and contrived or unreachable states unless a requirement or past defect justifies them.
- Treat existing tests as regression contracts. Preserve their assertions unless the requested behavior intentionally changes. When behavior changes, update only the affected tests and add coverage for the new contract; never weaken or delete tests merely to make the suite pass.
- Do not introduce a test framework solely to satisfy this rule. If automated coverage is impractical, explain why and perform the strongest targeted verification available.
- Run the relevant focused tests after changing tested behavior.
- When adding or updating dependencies, pin exact versions rather than ranges.
With pnpm, use
pnpm add -E(--save-exact). - Do not change dependencies, global tools, or the environment by default.
- Do not run local or remote database inspection, generation, migration, or SQL commands unless the task requires them.
- Follow the repository's organization and naming. Organize feature-specific
code under the feature's existing directory; when a feature contains multiple
substantial UI pieces, place them in a
<feature>/componentssubdirectory. Keep broadly reused code in the repository's established shared locations. - Complete every new or materially changed feature through a semantic pass:
implement and stabilize it, map each responsibility to its final file, extract
independently understandable concerns, validate the decomposed implementation,
then hand it off to
code-reviewer. Pages, routes, controllers, commands, and entrypoints contain composition and orchestration only. Web page files may keep framework exports, metadata, loading, guards, page-level state, minimal layout wrappers, and imported child composition, but not child components, substantial UI sections, or domain logic. Independently changeable UI concerns (tables, filters, forms, dialogs, and sections) belong in descriptive feature-local component files. Hooks, schemas, data access, transformations, and domain logic move out of presentation files when independently testable or when they obscure the component's primary responsibility. Avoid genericutils,helpers, orcomponentsdumping grounds; filenames must identify owned behavior. Keep components feature-local by default; promote them to shared/design-system locations only when reused across features or explicitly global primitives. Tiny private helpers or markup may remain inline only when inseparable from the file's single responsibility. Do not broaden an unrelated small fix, but leave any new or materially changed feature decomposed. Every completed feature gets an automaticcode-reviewerstructure review; exceptions require a concrete framework or tooling constraint identified in the handoff. - Use intent-revealing domain names. A reader should understand what a variable
contains or what a helper guarantees at the call site without opening its
implementation. Avoid vague transformation names such as
normalized,processed,result, ordatawhen a value- or behavior-specific name is available. Prefer clear structure, and simplify or extract complex logic before relying on comments. Use comments to explain non-obvious purpose, constraints, invariants, tradeoffs, or workarounds, not to narrate statements. - Keep naming conventions consistent within each code-owned object, schema, type, and module. Do not mix identifier casing styles in the same representation unless required by an external contract or framework. Preserve externally defined names at the boundary, then map them once to the project's internal convention.
- Do not reorganize feature directories, shared modules, routes, server boundaries, schemas, or state patterns unless requested and approved.
- In React, React Native, and Expo projects using TypeScript, use
kebab-casefor code-owned file and directory names. Preserve framework-mandated and contract-derived names, including Expo Router notation and React Native platform suffixes such as.ios.tsx,.android.tsx, and.native.tsx. - Use
PascalCasefor components, context providers and consumers, type aliases, interfaces, and enums. - Use
camelCasefor functions, variables, props, state, and code-owned object properties. - Name custom hooks as
useThing, higher-order components aswithThing, and local event-handler functions ashandleThing. Name callback props withon, such asonSubmit. - Prefix boolean props, state, and variables with
is,has, orshouldwhen the prefix accurately describes their meaning. - Use
UPPER_SNAKE_CASEfor module-level constants and enum members. Keep ordinary localconstbindings incamelCase.
- Update schemas first, then generate migrations or derived types. Never edit generated migration snapshots manually unless requested.
- Validate form and server inputs explicitly. After successful mutations, invalidate or refresh relevant cached data when applicable.
- Read
PLANS.mdbefore product-facing work. Implement only the requested feature, not the whole plan. - Record requirement, product, workflow, permission, priority, scope, deferral, and durable implementation decisions in the relevant feature chunk/checklist, not only narrative summaries.
- After product-facing work, update the relevant item's state: implemented, verified, deferred, or pending. Check items only after implementation and verification; manual testing may revert them.
- Record major completed, resume-worthy milestones in a concise
PLANS.mdmilestone or accomplishment section. State the technical scope and value; never exaggerate impact or invent metrics. - Keep
PLANS.mddetailed enough for a fresh session, but exclude temporary handoff state, command output, debugging notes, and scratch work unless they represent durable decisions. - If
PLANS.mdconflicts with the current request, follow the request and update the plan.
- Preserve user changes and unrelated dirty state. Never revert them without an explicit request.
- Never run destructive Git commands such as
git reset --hardorgit checkout --without explicit approval. - Use
apply_patchfor manual edits. - Prefer
rgandrg --filesfor approved searches. - Keep final responses concise and state what was verified or which manual verification commands were suggested.
After changes, summarize:
- changed files and behavior
- suggested verification, or commands run with explicit approval and results
- relevant
PLANS.mditems deferred, updated, or marked complete - whether the change is template-level; if so, give the packaged template's target section and exact addition or replacement