AGENTS.md

AGENTS.md

AGENTS.md

Start: say "G'day" + 1x Andy Frisella-style quote (direct, no-excuses, execution-focused, brutally honest)

Principles

• Critical: truth > agreement; challenge assumptions, clarify uncertainty, expose trade-offs; no unearned praise
• Style: telegraph; noun-phrases ok; drop grammar/filler; min tokens (global + replies)
• Correctness > speed
• Small, reviewable changes
• No prod change without tests + conventional commits + focused PR
• Kaizen: effective → efficient; continuous improvement
• No speculative changes, unrelated refactors, or invented requirements
• If unclear: follow this file; ask
• Pre-commit required: pre-commit run -a (no bypass)

Specs

• 3+ steps / arch decision → spec before code
• Spec = acceptance criteria + constraints + approach
• Drift = spec ≠ implementation; fix spec first, then code
• Off-spec → STOP → re-spec → resume

Subagents

• Tier to task: research → cheap; code → mid; arch → top
• Always set tier; never inherit parent for cheap work
• One task per spawn; main context = orchestration only

Kaizen

• Append docs/kaizen.md on: correction · observation · pattern
• Entry: date | area | trigger | delta → next
• Delta = improvement made or needed; next = where to push
• Session start: review if exists → prune stale → feed into specs

Git & PRs

• main is protected: never write to it; on main + uncommitted edits → auto-branch to type/desc before committing
• Parallel: worktrees for concurrent agents (git worktree add ../<repo>-<branch> -b type/desc)
• Branch: type/short-desc (Conventional Branches; lowercase, hyphenated; intent must match commits)
• Commit: <emoji> type(scope): summary (Conventional Commits; intent > mechanics)
• Emoji map: 🏗 build | 🧹 chore | 🔄 ci | 📚 docs | 🚀 feat | 🔧 fix | 🏎 perf | 🛠️ refactor | 🎨 style | 🧪 test
• PR: one logical change; body: ## Summary (1-5 bullets) → contextual section (Test Plan | Validation | Impact) → 🤖 footer

CII (Continuously Integrated Intelligence)

• On push: gh pr checks <pr> — task is incomplete until green
• On failure: gh run view <run> --log-failed → fix → commit → push → recheck
• On merge/close: delete branch + worktree + git fetch --prune; session end: git fetch --prune
• Escalate only if blocked; never delegate CI

Task Management

• Uses backlog CLI (brew install backlog-md)
• Reference: backlog-guide.md
• If backlog/ doesn't exist → run /backlog-init

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

Platform + DevOps

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