AGENTS.md

Codex-Kit Repository Instructions

Purpose and sources of truth

• This public repository maintains the @iamdevlinph/codex-kit package.
• AGENTS.md contains instructions for maintaining this repository.
• The root TEMPLATE_AGENTS.md is the canonical reusable template source. Every build copies it to assets/TEMPLATE_AGENTS.md for distribution to downstream projects; neither template is this repository's active instructions.
• Keep reusable template rules project-agnostic. Project names, local paths, integrations, and exceptions belong only in the affected project's AGENTS.md.

Working conventions

• Before planning, classify the requested work and required validation; revisit that classification when discovery expands the affected domains. Account for the complete instruction chain, keep universal safeguards active, and load only matching project skills and references they explicitly require.
• Keep each rule or decision in one authoritative owner where practical. Give every conditional procedure a shallow route that states its trigger, exact path, read condition, unrelated work that must not load it, and dependencies.
• Follow the repository's existing style, structure, architecture, and stronger local instructions. Match nearby code before introducing new patterns, abstractions, dependencies, or file organization.
• If PLANS.md exists, treat it as a concise durable index, not a per-change changelog. For product work, load only the affected feature plans and their dependencies, and update the document that owns the changed decision or state. Create it only from real repository evidence, never speculative history.
• Keep changes minimal, localized, and limited to the request. Do not reorganize major modules, change architecture, or introduce a new project paradigm without explicit approval.
• Work within the existing architecture. If it prevents safe completion, explain the blocker, propose the smallest viable design change, and wait for approval instead of bypassing it.
• For every new or materially changed feature, read and follow .agents/skills/codex-kit-feature-workflow/SKILL.md before implementation and structural validation. Do not load it for test-only work, unrelated tooling, documentation, or a small fix that does not materially change a feature. Its workflow depends on applicable PLANS.md entries and project architecture. Every completed feature still requires a code-reviewer handoff.
• Before changing code, inspect the manifest, configuration, scripts, and nearby files to identify the actual stack, commands, and conventions.
• 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 rather than 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. Derive static types from that runtime source; keep incidental presentation, protocol, route, environment, and test-contract strings inline.
• Preserve user changes and unrelated dirty state. Never revert them without an explicit request, and never run destructive Git commands such as git reset --hard or git checkout -- without explicit approval.
• Use apply_patch for manual edits and prefer rg or rg --files for searches.

Implementation constraints

• Keep the published CLI compatible with Node.js 20 or newer and prefer Node standard-library APIs. Maintainer tooling and tests run on Node.js 24.
• Use the pnpm version pinned in packageManager; do not create an npm lockfile.
• When adding or updating dependencies, pin exact versions rather than ranges. With pnpm, use pnpm add -E (--save-exact).
• Keep the CLI source in src/ under strict TypeScript. bin/ is generated by pnpm run build; it must not be edited or tracked.
• Keep the exact TypeScript RC version pinned in devDependencies until an explicit upgrade is requested. Invoke it through pnpm exec tsc, never a globally installed compiler.
• Do not add a dependency unless the requested behavior cannot reasonably be implemented with the standard library.
• Preserve user-owned files and unrelated configuration. Back up files before a managed replacement and never silently overwrite locally modified content.
• global install configures the default root model and reasoning settings; global configure remains available for explicit overrides.
• project sync may refresh TEMPLATE_AGENTS.md and project state, but must not merge into or replace a project's AGENTS.md.
• project mark-applied is bookkeeping only; it must not claim to validate the semantic merge or modify project instructions.
• Do not add a commit-pusher role or automate Git publishing outside the validated .github/workflows/publish.yml release flow.

Change requirements

• Before final validation of package, template, build, or release-workflow changes, read and follow .agents/skills/codex-kit-release/SKILL.md. Do not load it for feature-only, test-only, or unrelated tooling work; mixed feature and release work loads both project skills. Documentation/instruction-only changes have release impact none and preserve package.json and RELEASE_NOTES.md.
• Select tests for regression value rather than exhaustive coverage. Cover changed observable contracts, reported regressions, meaningful boundaries, and plausible costly failures, especially security, trust-boundary, or data-loss risks.
• Test observable production behavior instead of inspecting implementation text. Prefer the narrowest real executable boundary: use the public interface when practical; otherwise call the actual production function or module and assert inputs, outputs, state transitions, side effects, failures, or persisted results. Use focused integration tests when behavior spans components.
• Do not use source-file reads, regex or literal presence, snapshots, symbol counts, private-helper calls, or internal statement ordering as proxies for functionality. Source-text assertions are appropriate only when the text is itself the observable contract, including generated artifacts, CLI or prompt output, externally consumed configuration, migration SQL, and installed template, skill, or agent assets. Assert only the smallest meaningful textual contract.
• Do not recreate production decision logic inside tests. If no real executable boundary exists, introduce the smallest localized test seam only when justified. Otherwise preserve the existing regression coverage and report why safe behavioral replacement would require disproportionate, risky, or ambiguous restructuring.
• Use one representative case per necessary observable contract or reported regression. Skip speculative edge cases, redundant permutations, implementation-detail assertions, and contrived or unreachable states. Retain boundary coverage only for an explicit requirement, past defect, or plausible security, trust-boundary, or data-loss failure. Do not introduce a test framework solely to satisfy this rule; if automated coverage is impractical, explain why and perform the strongest targeted verification.
• 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.
• Run the smallest targeted verification that meaningfully validates a change. Broaden validation only for affected shared behavior, a failure, or an explicit release requirement; a command being available or fast is not enough.
• Do not change dependencies, global tools, or the environment by default.

Template and release workflow

• When the staged template is refreshed or codex-kit project status requires reconciliation, use the global $codex-kit-reconcile-agents skill. Preserve this file's organization and local rules, merge only applicable guidance, do not copy the full template or add managed markers, keep critical always-on rules here, and mark applied only after reconciliation and validation succeed.
• Use $codex-kit-audit-agents for later explicit instruction audits independent of template synchronization; those audits must not inspect or modify project state or run project mark-applied.
• When promoting a project-discovered guideline, generalize and review the rule before merging it into the root TEMPLATE_AGENTS.md; the next build copies the updated source into assets/TEMPLATE_AGENTS.md.
• Tell the user when a requested workflow preference, convention, agent behavior, tooling default, or safety rule appears reusable across projects, and report the exact generalized wording and target section for the root TEMPLATE_AGENTS.md.
• A template update requires a new package release before downstream project sync commands can receive it.
• The release tag must match package.json as v<version>.
• Never commit, tag, push, publish, or create a release interactively unless the user explicitly requests that operation in the current task. The validated release workflow may perform those actions after an authorized push to main.
• Never store credentials, npm tokens, or personal access tokens in this repository.