agentic-qa-boilerplate: Instructions file for Codex

AGENTS.md: AI Persistent Memory

Always-on layer (L0). Detail lives in section files under .agents/instructions/, loaded through the ROUTER (progressive disclosure). Edit a section file, never paste section prose back here; project rules go in .agents/instructions/agent-project.md. Every instruction edit goes through /framework-development mode instructions.

LOAD PROTOCOL

Before acting on a request, match it against the ROUTER and read every matched section file not already in this conversation. A ROUTE: line injected by the hook is binding and wins over your own judgment: read its file before acting. A ROUTE-OPTIONAL: line is not binding: read one of its files only when the task needs it. A ROUTE-PENDING: line names a binding file still unread: read it before the next step. A section once read is not re-read unless compaction or /clear removed it. Unsure whether a section applies → read it: a skipped section is the failure this design guards against. A section binds exactly like this file. A §N citation anywhere names the numbered heading kept verbatim in the file the ROUTER lists for it.

1. CRITICAL RULES: ALWAYS APPLY

Each line is the rule's binding sentence; Full: agent-critical-rules.md#n = its full text in .agents/instructions/agent-critical-rules.md, under the heading ## n.

1. CREDENTIALS = BY NAME, NEVER BY VALUE: Reference a secret only through its variable NAME ($STAGING_USER_PASSWORD expanded by the shell, process.env.X in code, a name in the MCP loader's --filter list). NEVER open, print or paste a secret value: no Read/cat/grep of .env* (except .env.example and the committed .env*.schema files), .auth/** or .claude/settings.local.json; no printenv, env, echo $SECRET, set -x, curl -v, varlock printenv|reveal, or varlock load without --agent. To learn WHETHER a variable is set, run the repo's redacted presence check (named in the full text). A missing secret value is the human's to type, in a terminal or the secret manager, never through the chat; the AI MAY write a non-sensitive value (URL, project key, flag, port) when asked. NEVER hardcode or guess. Full: agent-critical-rules.md#1
2. PLAN BEFORE CODING: Produce test plan (spec.md / impl plan) BEFORE writing test code. Full: agent-critical-rules.md#2
3. NO AI ATTRIBUTION: NEVER include "Generated with AI", harness branding, or AI Co-Authored-By trailers in commits. Forensic trailers are the one MANDATORY exception and are NOT attribution: every commit ends with Worktree: <name|primary> then Session: <label>. Full: agent-critical-rules.md#3
4. SHIFT-LEFT: Evaluate ACs for clarity, testability, completeness. Full: agent-critical-rules.md#4
5. PUSH TO PROTECTED = RESOLVE git_strategy.policy.direct_push_to_protected (.agents/project.yaml; protected list = git_strategy.protected): forbidden → NEVER direct-push, route through a PR. confirm → ask explicit user confirmation before EVERY push. allowed → standing authorization, push without asking. git_strategy block missing or null (fresh scaffold) → behave as confirm (safe default: ask). Full: agent-critical-rules.md#5
6. GIT HISTORY (INVARIANTS, not strategy choices — no git_strategy value relaxes them): NEVER rewrite pushed history (rebase/amend on pushed commits). NEVER force-push a branch others may share. NEVER delete remote branches without confirmation. Full: agent-critical-rules.md#6
7. QUALITY VERIFICATION: After code changes, verify in order: tests → types → lint. Full: agent-critical-rules.md#7
8. FILE OPERATIONS: ALWAYS read file before edit. Preserve formatting + indent. NEVER overwrite without reading. Full: agent-critical-rules.md#8
9. SKILLS-FIRST: All workflows live in .agents/skills/. NEVER paste instructions inline. Full: agent-critical-rules.md#9
10. MCP CREDENTIAL FAILURE = STOP IMMEDIATELY: NO workaround. STOP, tell user exact env var, point to .env / .env.example, ask fix .env + RESTART AGENT SESSION (env cached at MCP-spawn time, no refresh mid-session). MCP UNAVAILABLE = SAME STOP, AT THE POINT OF USE. Full: agent-critical-rules.md#10
11. SCRIPTS = READ package.json DIRECTLY. NEVER quote test/build commands from this file or any doc: drift kills. Full: agent-critical-rules.md#11
12. KATA MANIFEST = SOURCE OF TRUTH. Before proposing new Page, Api, Steps module, or @atc('PROJ-XXX') ID: MUST load kata-manifest.json and check it. Full: agent-critical-rules.md#12
13. CONCISION COMES FROM §2, NOT FROM A PLUGIN: Concision comes from §2 (Butler + PM Voice) and the user-level OUTPUT STYLE. No communication-mode plugin is assumed or recommended. Full: agent-critical-rules.md#13
14. LANGUAGE DETECTION + MIRRORING: Mirror that language in ALL conversational replies (questions, summaries, explanations, status updates). Repo artifacts ALWAYS English regardless of conversation language. Full: agent-critical-rules.md#14
15. NO GLOBAL DISCARDS (MULTI-SESSION SAFETY): PROHIBITED to run repo-wide destructive git commands: git restore ., git checkout -- ., git reset --hard, untargeted git stash, git clean -f. Discard ONLY explicit paths YOU modified in THIS session. Full: agent-critical-rules.md#15
16. A SUCCESS CODE DESCRIBES THE CALL, NEVER THE OUTCOME — VERIFY AT THE DESTINATION: a write is verified by READING IT BACK from the destination, a message by the recipient answering it, a transition by re-reading the issue's status, a file write by re-parsing the file, a dispatch by the worker's own first report. Full: agent-critical-rules.md#16
17. COMMITTED PROSE NAMES THE SOURCE OF TRUTH, NEVER ITS CURRENT VALUE: text that is committed (this file, .agents/**, docs/**, README.md, INSTALLER.md, .env.example, the decks) NEVER states a fact that changes with the normal life of the repo or the tracker. Full: agent-critical-rules.md#17