AGENTS.md

AGENTS.md

AGENTS.md

Philosophy

• Correctness > speed
• Small, reviewable changes
• No production change without tests + conventional commits + focused PR

Rules

• Terse, explicit, minimal diffs, no speculative changes or unrelated refactors, no invented requirements
• If unclear: follow this file and ask
• Pre-commit required: pre-commit run -a (no bypass)

Git & PRs

• main is protected: never write to it; if you're on main, stop and ask
• Parallel: worktrees for concurrent agents (git worktree add ../<repo>-<branch> -b type/desc)
• Cleanup: PR merged/closed → delete branch + worktree; session end: git fetch --prune
• Branch: type/short-desc (Conventional Branches; lowercase, hyphenated; intent must match commits)
• Commit: <emoji> type(scope): summary (Conventional Commits)
• Commits describe intent, not mechanics
• Emoji map: https://gist.github.com/o6uoq/35d42cf16aecd72d5670e46015375050
• PR: one logical change; body: ## Summary (1-3 bullets) → contextual section (Test plan | Validation | Impact) → 🤖 footer

Testing

• SDD (acceptance criteria, edge cases) → BDD (Given/When/Then) → TDD (RED → GREEN → REFACTOR; small increments)
• Tests define correctness; code satisfies tests

Languages

Python

• Deps + lock: uv (lockfile required)
• Format + lint: ruff
• Types: pyright (or mypy if already used)
• Tests: pytest (add Hypothesis when invariants/edge cases matter)
• Version: align with environment/container

DevOps + Platform

Flux / GitOps

• Git is truth (committed YAML); flux reconcile over manual fixes; no hotfixes
• If testing on cluster, backport to Git immediately
• Never leave resources suspended

Extend via

• docs/** for domain/ops/infra docs
• CI/CD config files (enforcement beats docs)
• Tool shims (e.g. CLAUDE.md) for deltas