md.html AGENTS.md

AGENTS.md — md.html

Architecture · Abstractions · Vision · Getting Started · ADRs · Sentrux

Write the minimum code that runs. No fluff, no gold-plating.

• Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
• Choose the simplest implementation that fully meets the current requirements. Avoid speculative abstractions, configuration, and indirection.
• Grow the system in layers. Start from the smallest version that works end to end, and add each new capability on top of a product that already works. Never trade a working product for unfinished complexity.
• Keep components modular and concerns clearly separated.
• Prefer established, well-maintained libraries when they reduce overall complexity or improve reliability. Do not reimplement common functionality without a clear reason.
• Lean on the dependencies already in the project before writing your own implementation or adding packages. Do not assume a library lacks a capability without checking its documentation and types.
• Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.
• Study how established products solve the problem before designing a solution. Adopt their proven patterns and conventions rather than inventing an approach from scratch.

Repository rules

• AGENTS.md is the single source of guidance. CLAUDE.md, GEMINI.md, CURSOR.md, AGENT.md and .github/copilot-instructions.md are symlinks to it. Never edit a symlink; never let one drift into a real file.
• Never commit secrets. Tokens, credentials, and service-account JSON stay in a secret manager or a gitignored .env. The pre-commit hook scans the staged diff; do not work around it.
• No personal or production-derived data in source, migrations, fixtures, tests, or docs. Committed fixtures are synthetic. User-specific values belong in runtime configuration.
• Never expose internals to users. No stack traces, internal URLs, or env var names in user-facing copy.
• Conventional Commits required. feat:, fix:, docs:, refactor:, test:, chore:. One logical change per commit; one bounded scope per PR. Release tooling parses them — a break in a published contract ships as feat!: or carries a BREAKING CHANGE: footer, never as a plain feat:.
• Never --no-verify. If a hook blocks, fix the underlying issue.
• Code, comments, and identifiers in English. Surgical changes — no opportunistic refactors in feature PRs, no suppression comments to silence a linter.
• Shell scripts run under set -euo pipefail and are idempotent — re-running completes what is missing instead of duplicating or destroying.