codexicon: Instructions file for Codex

AGENTS.md — Codexicon

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

Project

• Name: Codexicon
• Purpose: Portable local-first template and manager for inspectable, verified agent-driven development.
• Stack: Python 3.10+ · Markdown/TOML/JSON · filesystem state · local checkout and GitHub Actions
• Phase: production
• Owner: bnet47

Use $discover to create or amend the root SPEC.md before making product or stack decisions. Only consequential unresolved decisions may pause the work.

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.
• Build is autonomous by default: inspect, plan, implement, verify, critique, refine, and continue through the root TASKS.md without routine approval prompts or suggested-next-prompt stops while work is runnable. Make reversible assumptions and record consequential ones; batch genuinely blocking questions.
• Use $autonomous-build for multi-task work. Use $engineering-loop only for independent read-only research or review. 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.
• Record consequential assumptions and decisions as new append-only records in agent_docs/decisions/, including rationale, alternatives, impact, owner, date, status, and evidence.
• Related scope may expand only for a small, reversible, directly related change within the declared system boundary; explicitly escalate authority, product behavior, schema/data shape, security posture, irreversible or destructive outcomes, credentials, production actions, migrations, external writes, publication, deployment, legal/compliance commitments, or material architecture changes.