matcha AGENTS.md

🍵 matcha — Core AI Directives

Simple. Efficient. Deliberate. Never twice.

Engineering philosophy for AI coding agents. Enforces deliberate thinking before, during, and after implementation.

<execution_filter>

The 6-Checkpoint Filter

🎯 Purpose → 🔎 Reuse → 🔍 Stack → 🛠️ Implementation → 🧹 Cleanup → ✅ Verify → 🔒 Review

#	Checkpoint	Rule
🎯	Purpose + Reuse	Intent Discovery with evidence (file:line, metrics). Can't answer Why/How? → STOP unless trivial (≤5 LOC, 1 file, no logic) — then proceed on a recorded assumption. Search codebase first (src/, lib/, pkg/, app/). Never duplicate.
🔍	Stack	Scan manifests (package.json, Cargo.toml, go.mod, etc.) for service overlap.
🛠️	Implementation	No hardcode. Explicit errors. One function = one responsibility. Simpler path? → Use it. Deliberate-choice comments → // matcha: marker at write time (not cleanup).
🧹	Cleanup	Done = working AND clean. Mark deliberate shortcuts with // matcha: [reason] — standard format + English only.
✅	Verify	Run empirical test/build command. Fail? → STOP and fix immediately.
🔒	Review	Blocking gate. Catch bugs, performance, security, architecture. Nothing ships without PASS.
</execution_filter>

<core_principles>

Core Principles

1. Proportionality (effort ↔ risk) — Match ceremony to task size: trivial (≤5 LOC, 1 file, no logic) → no plan, fast pass; small (1-3 files) → short plan + lint review; large (cross-cutting/prod risk) → full gate. Planning > implementation = over-planning. Exit conditions beat STOP: proceed on a recorded assumption rather than blocking on trivia.
2. Simple AND Efficient (Never Twice) — Choose the path that is BOTH simple to read AND optimal in runtime. Naive code causing future refactoring is a failure.
3. DRY & Reuse First — Search codebase before writing new code (file:line evidence required). Never duplicate existing functions.
4. Type-Safe & Boundary Guard — Strict types (no any). Validate schemas and inputs at entry points (fail fast).
5. Pure Core & Clean Architecture — High cohesion, low coupling, deterministic pure logic. Isolate side effects.
6. Performance & Resource Awareness — Zero N+1 queries or unbatched I/O, avoid O(n²+) time/space complexity, prevent memory leaks, limit payload sizes.
7. Security & Data Safety — Parameterize queries (no SQLi/XSS), isolate credentials to env vars ([APPNAME]_VAR_NAME), restrict least-privilege state access.
8. Resilience & Explicit Errors — Idempotent mutations (safe to retry), explicit error paths, no silent catches or dummy fallbacks.
9. Zero Tech Debt Leakage — Mark deliberate shortcuts with // matcha: [reason] — standard format + English only (// matcha:explain <reason>, // matcha:todo <task>, // matcha:debt <reason>, <fix when>, // matcha:adr <ref>). Do it at write time, not as a cleanup pass — if a comment documents a deliberate choice (skip, workaround, intentional hardcode), prefix it while writing. Plain "what this does" comments need no marker.
10. Loop Guardrail (Self-Termination) — Halt and ask for guidance if 2 consecutive attempts fail or yield identical results.
11. Empirical Verification Anchor — Never declare completion without fresh test/build execution logs confirming success. </core_principles>