anchor AGENTS.md

AGENTS.md — Anchor

The production-grade template for AI coding agent instructions. Adapt sections to fit project scope. Keep your agents grounded.

This file governs itself. Agents working on AGENTS.md must follow all rules herein — the decision ladder, commit conventions, tradeoff comments, quality gates, and output discipline. No section should be added that future agents would need to explain away as inapplicable.

This is the high-level entry point. Every numbered section's full rule text lives in a lazy-loaded skill file under skills/. The most important rules are reproduced in full below so they apply to every task even in constrained context windows. Load a skill file only when the corresponding task applies.

---

How to Use This File

1. Always loaded: This file (header, core rules below, Section Index, Cheatsheet).
2. Lazy-loaded: The full text of every section is in skills/NN-name.md. Load a skill only when your task matches its "Load when" trigger. This keeps context lean — a model with a 32K window can follow all rules without reading 6,700 lines.
3. Follow cross-references: When a loaded skill references another section (e.g. "see Section 35"), that referenced section is NOT included — load skills/NN-name.md for it too before proceeding. The Section Index maps every section to its file.
4. Full text on demand: The Section Index and Skills Directory below map every section to its skill file. If a task touches a topic, load that skill and follow it exactly.
5. Verification: When in doubt about a rule's full wording, read the skill file — never guess.
6. Template usage: Projects should copy this file, keep the core rules, then trim the skill list to what applies and inline the needed skills into their own AGENTS.md (target ≤2,000 lines, per Section 51.3).

---

Section Index (Glossary)

#	Section	Summary	Full Text
1	Core Principles	8 non-negotiable principles: no dead code, no stubs, no silent failures, test-first, proven integration	skills/01-core-principles.md
2	Commit Protocol	Commit/push workflow, Never Go Rogue, Never Spend Money, user identity	skills/02-commit-protocol.md
3	Shell Execution Rules	Shell command discipline: quoting, cwd, no pipelines	skills/03-shell-execution-rules.md
4	Code Style	Python/TypeScript style, English-only, import order	skills/04-code-style.md
5	Project Structure Conventions	Standard folder layout (src, tests, docs, research)	skills/05-project-structure-conventions.md
6	TODO.md — Task Tracking Standard	Task tracking legend, current sprint, completed sprints	skills/06-todo-md-task-tracking-standard.md
7	Docker / Deployment	Containerized app, build/deploy commands	skills/07-docker-deployment.md
8	Testing Requirements	Test commands, run full suite before completion	skills/08-testing-requirements.md
9	Linting & Type Checking	ruff/mypy/vulture sweep, pre-commit	skills/09-linting-type-checking.md
10	Error Handling Patterns	No silent failures, specific exceptions, log before swallowing	skills/10-error-handling-patterns.md
11	Configuration Management	Settings, env vars, config handling	skills/11-configuration-management.md
12	API Design	REST conventions, public/admin split	skills/12-api-design.md
13	Security Best Practices	Injection, auth, secrets, parameterized queries	skills/13-security-best-practices.md
14	Logging Standards	Structured logging, levels, PII	skills/14-logging-standards.md
15	Git Workflow	Branching, commit messages, merge strategy, WHY format	skills/15-git-workflow.md
16	Documentation Requirements	README, DEEPDIVE.md, docs discipline	skills/16-documentation-requirements.md
17	Dependency Management	Add only when needed, check existing deps first	skills/17-dependency-management.md
18	Performance Considerations	Optimize only with measurements	skills/18-performance-considerations.md
19	Build & Deployment	Build steps, CI, deploy	skills/19-build-deployment.md
20	External Integrations	Third-party APIs, resilience, timeouts	skills/20-external-integrations.md
21	AI Agent Instruction Guidance	7 patterns: critical findings, role boundaries, error recovery	skills/21-ai-agent-instruction-guidance.md
22	Multi-Agent Cooperation Patterns	Role templates, sequential handoff, hierarchy, termination	skills/22-multi-agent-cooperation-patterns.md
23	Verification Gates	Format/action/context/termination validation	skills/23-verification-gates.md
24	Common Failure Modes	Invalid format, hallucination, task/context limit	skills/24-common-failure-modes.md
25	Common Gotchas	Python version, shell, env vars, git mistakes	skills/25-common-gotchas.md
26	Getting Help	Self-service first, framework resources, escalation	skills/26-getting-help.md
27	Code Quality Standards	Python idioms, anti-patterns, security, performance, docs, testing	skills/27-code-quality-standards.md
28	Default Tech Stack Playbook	Per-project-type stack choices and anti-recommendations	skills/28-default-tech-stack-playbook.md
29	Operational Patterns	Circuit breaker, DLQ, middleware, semantic cache	skills/29-operational-patterns.md
30	Health Endpoint Specification	/health design, probe configuration	skills/30-health-endpoint-specification.md
31	Production Security Patterns	Prompt injection, audit logging, IP whitelist	skills/31-production-security-patterns.md
32	Docker Support	Dockerfile best practices, compose, K8s deployment	skills/32-docker-support.md
33	PR & Change Size Standards	800-line limit, single feature rule	skills/33-pr-change-size-standards.md
34	AI Code Quality — Anti-Pattern Detection	Spot LLM laziness, confusion, bloat	skills/34-ai-code-quality-anti-pattern-detection.md
35	PR Description Format & Template	Template with agent disclosure + self-check	skills/35-pr-description-format-template.md
36	Explicit Prohibitions — The "NEVER" List	Bright lines: code, git, GitHub, financial, identity, testing	skills/36-explicit-prohibitions-the-never-list.md
37	Pre-Commit Hook Standards	pre-commit framework setup, enforcement	skills/37-pre-commit-hook-standards.md
38	CI/CD Pipeline Standards	CI, release, deploy pipelines, SHA pinning	skills/38-ci-cd-pipeline-standards.md
39	Semantic Versioning & Changelog	SemVer rules, Keep a Changelog format	skills/39-semantic-versioning-changelog.md
40	Code Coverage Enforcement	Thresholds, branch coverage, exclusion	skills/40-code-coverage-enforcement.md
41	Observability Standards	Structured logging, tracing, metrics, SLOs	skills/41-observability-standards.md
42	Infrastructure as Code	Terraform/OpenTofu structure, state, environments	skills/42-infrastructure-as-code.md
43	Database Backup & Recovery	Schedules, restore procedures, verification	skills/43-database-backup-recovery.md
44	Secrets Management	Tiered strategy, SOPS+Age, rotation	skills/44-secrets-management.md
45	Flaky Test Management	Quarantine, four sources, remediation	skills/45-flaky-test-management.md
46	Mutation Testing	mutmut setup, mutation score interpretation	skills/46-mutation-testing.md
47	Performance Benchmark Testing	pytest-benchmark, time budgets	skills/47-performance-benchmark-testing.md
48	Contract Testing (Pact)	Consumer-driven contracts, CI integration	skills/48-contract-testing-pact.md
49	Chaos Engineering	Netflix principles, experiment design	skills/49-chaos-engineering.md
50	Intentional Minimalism	Decision ladder, tradeoff comments, honesty boundaries	skills/50-intentional-minimalism-the-simplicity-first-architecture.md
51	Instruction Architecture	Lazy loading, context budgets, provenance	skills/51-instruction-architecture-context-economy-self-improvement.md
52	Rule Enforcement Architecture	Prose→hooks, evidence-first, CI gates	skills/52-rule-enforcement-architecture-from-advisory-to-deterministic.md
53	Project Type Patterns	Mobile, embedded, data pipelines, CLI, static sites, AI/agentic apps	skills/53-project-type-patterns.md
54	MCP Usage & Guardrails	Vetting MCP servers, mcp__* permission scoping, tool output as untrusted	skills/54-mcp-usage-and-guardrails.md
55	Prompt-Injection Defenses for Agents	Trust boundary, instruction hierarchy, input/output guardrails	skills/55-prompt-injection-defenses-for-agents.md
56	Agent Memory & State Management	What survives compaction, MEMORY.md discipline, subagent isolation	skills/56-agent-memory-and-state-management.md
57	Tool-Call Permission & Safety Rules	Deny-first precedence, PreToolUse hooks, sandboxing	skills/57-tool-call-permission-and-safety-rules.md
58	Supply-Chain Security & SBOM	Dependency verification, scanning, SBOM, signing, SLSA provenance	skills/58-supply-chain-security-and-sbom.md
59	Incident Response & Runbooks	Severity taxonomy, runbook-first rollback, blameless postmortems	skills/59-incident-response-and-runbooks.md
60	Property-Based Testing	Hypothesis, shrinking, seeds, CI integration	skills/60-property-based-testing.md
61	Snapshot / Golden-File Testing	syrupy, matchers, never blind snapshot updates	skills/61-snapshot-golden-file-testing.md
62	Retries, Backoff & Idempotency	Timeout budgets, exponential backoff+jitter, idempotency keys	skills/62-retries-backoff-and-idempotency.md