codexicon AGENTS.md

AGENTS.md — [PROJECT_NAME]

Durable repository guidance for Codex. Keep this file short; detailed workflows belong in skills and project facts belong in agent_docs/.

Project

• Name: [PROJECT_NAME]
• Purpose: [one sentence describing the problem and intended outcome]
• Stack: [language · framework · data store · deploy target]
• Phase: [idea | prototype | alpha | production]
• Owner: [name or GitHub handle]

If these fields are still placeholders, treat the repository as an unconfigured template. Use $discover before making product or stack decisions, then $init to configure the repository.

Commands

Run commands from the repository root.

./scripts/setup.sh              # install dependencies and prepare local config
./scripts/dev.sh                # start the local development environment
./scripts/lint.sh               # lint, format-check, and type-check
./scripts/lint.sh --fix         # apply safe lint/format fixes
./scripts/test.sh               # run the full test suite
./scripts/security.sh           # scan tracked/non-ignored safe files for credentials
python scripts/codexicon.py doctor  # diagnose harness/configuration drift
python scripts/codexicon.py verify  # run lint, tests, and security in canonical order
./scripts/deploy.sh staging     # deploy to staging
./scripts/deploy.sh prod        # production; requires DEPLOY_APPROVED=true

Before initialization, native Windows can run ./scripts/lint.ps1 and ./scripts/test.ps1. $init must create equivalent native wrappers or platform-neutral commands for every command the configured project supports; do not silently substitute weaker verification.

Working agreements

• Start from the requested outcome and done conditions. Inspect first; preserve unrelated changes.
• For clear requests, own the internal build/review loop and do not turn skills into approval gates. Make reversible assumptions; record consequential ones; batch blocking questions; escalate only for material product, irreversible, destructive, external, production, credential, legal, regulatory, security, or financial risk.
• For medium or high-complexity work, use $engineering-loop when independent exploration, implementation, testing, or review lanes materially improve the result. Keep small clear changes direct.
• Use $find-skills only for an explicit capability search. External skill discovery is read-only until the user approves a reviewed, pinned, project-local installation.
• Prefer the smallest complete solution. Use rg for search and apply_patch for manual edits.
• Load only relevant context. Use targeted commands and bounded output; do not dump whole logs, generated files, or minified content when an excerpt proves the point.
• Communicate densely: no request restatement, filler, or repeated summary. Preserve exact code, commands, paths, identifiers, and errors. Clarity wins for risk or ambiguity.
• Verify proportionally: full lint/tests for code, config, generated artifacts, and shipping; security before Git publication; applicable structural checks for documentation-only work.
• Report commands, results, and anything not verified.