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, drop filler; brevity never costs reasoning, specs, or code
• Correctness > speed
• Small, reviewable changes
• No prod change without tests + conventional commits + focused PR
• Kaizen: effective → efficient
• No speculative changes, unrelated refactors, or invented requirements
• Unclear → follow this file; ask
• Pre-commit required: pre-commit run -a (no bypass)

Language (Claude only)

• Follow the ASD-STE100 Part 1 writing rules when you talk to me. Use ordinary English vocabulary and Australian spelling. Do not apply the Part 2 Dictionary.
• Use active voice. Clearly state who or what does the action.
• Keep sentences to 20 words or fewer.
• Give one main idea per sentence.
• Use simple tenses: present, past, and future.
• Do not use idioms, slang, or unnecessary jargon.
• Keep paragraphs to 6 sentences or fewer.
• Keep technical items exact. Do not simplify or alter file paths, function names, column names, prices, numbers, or identifiers.
• Prioritise clear, direct, unambiguous language.
• Hard limit: 150 words. If you cannot answer inside it, give the one-line answer and ask before you expand.
• Exempt: code, commands, tables, commit and branch names, quoted material, and the Andy Frisella quote.

Specs

• 3+ steps / arch decision → spec before code
• Spec = acceptance criteria + constraints + approach
• Drift (spec ≠ impl): check before commit; fix spec first
• Off-spec → STOP → re-spec → resume

Subagents

• You own scope, sequence, decisions, integration, final answer — accountability doesn't transfer
• Default inline — never hand off trivial, sequential, latency-sensitive, or CI-triage
• Delegate for: independent parallelism (fan-out bounded by tokens + time), noisy bulk/logs, fresh-context critique, costly-if-wrong refutation (brief to refute, not confirm)
• Reads fan out; parallel writes need disjoint ownership + merge plan; dependent → sequence
• Brief any handoff like a contractor: goal, paths, knowns/unknowns, constraints, acceptance, return; minimum sufficient context
• Returns (yours or a sub's) = distilled conclusions + file:line; verified/inferred; no dumps; failed/empty handoff = your gap to close
• Contradiction between sources or agents = signal → investigate
• Verify decision-gating findings yourself; size subagent model/effort to task, downgrade only for bounded mechanics

Kaizen

• docs/kaizen.md = staging buffer: lessons not yet earned a permanent home; healthy = churn, not growth
• Append only what will recur — repeated failure, workflow friction, process pattern; one-offs die in commits/PRs
• Entry: - rfc3339_utc | area | trigger | lesson → next — lesson = reusable rule; next = encode/test/automate/watch
• Session start: read → prune stale → feed relevant lessons into specs
• Recurred 2-3× and still true → standardise: CI/pre-commit > AGENTS.md topical line (scope-matched) > docs/**; delete entry

Git & PRs

• main is protected: no edits in its checkout; new work → git worktree add -b type/desc ../<repo>-<desc> && cd $_ (always fresh; never reuse existing worktrees)
• 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)

• Before push: fetch; behind → rebase origin/main; rewrote history → --force-with-lease, never --force; reject → repeat
• Push → gh pr checks <pr> --watch --fail-fast --interval 30; pending = wait; fail = inspect; missing ≠ green
• No checks: wait 60s → retry once → gh run list --branch <branch> --limit 5
• Failure: gh run view <run> --log-failed → fix → commit → push → recheck
• Merge/close: delete remote + local branch/worktree if present → git fetch --prune && git worktree prune
• CI: never delegate; read failed logs → fix or escalate if blocked

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
• Local Flux test (kind): flux build ks <name> --path <dir> --kustomization-file <file> --dry-run; apply via pipe to kubectl apply -f -; never commit-to-test

Terraform

• Version: tfenv; commit .terraform-version
• Pre-commit: terraform_fmt · terraform_validate · terraform_docs
• No -auto-approve; plan before apply
• Pre-merge: in worktree, cd <module> && tf init && tf plan; fail → fix → rerun tf init + tf plan until clean
• Apply: manual only; share final clean plan + exact tf apply command, do not run it
• Mixed PR (TF + GitOps): same pre-merge rule; GitOps reconciles on merge

Secrets

• never argv/echo/log/commit/history; enter silently, feed via stdin
• read -rs V && echo && printf '%s' "$V" | <sink>; unset V (printf=no newline)

Extend via

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