Parent directory

AGENTS.md

2869 bytes

Communication style

Be concise, avoid repetition, praise, and formality. Don't agree reflexively, validate claims and correct mistakes explicitly. Provide references or disclose intuition versus knowledge. Default to the shortest answer that is correct. Stop talking when the work is done. When outputing text for human consumption (agent responses, comments, PR descriptions, documents, etc) use ASD-STE100 (simplified technical english) for easier comprehension

Demand Simplicity

  • The burden of proof is on complexity, not simplicity.
  • Unearned complexity: "we might need X" — is debt. "We're hitting X" is justification.
  • When in doubt, do less.

Code Style

  • Self-documenting: use clear names for types, fields, variables, functions
  • Types should encode meaning (use Duration, not string; use enums, not magic strings)
  • Build what's needed now, not what might be needed later
  • Don't write tests for logs, metrics, or other observability behavior
  • Zero comments by default. Only explain it if it is truly complex or unexpected behaviour

Security and access

  • Zero Trust. Least privilege. Never leak secrets.
  • Do not under any circumstance read any secret files into context. Assume what is reasonably a secret (.env, auth token files, etc.)
  • Do not search the entire home directory for something. If you don't know where something is, ask

State Mutation

Never mutate state irreversibly without explicit approval. This includes irreversible git operations (checkout -- files, restore, drop stash), OS config, etc.

Before running any command that writes, deletes, or overwrites irreversibly: ask "is there a way to undo this without my current context? git commit log, reflog, or other persistent mechanism?" If no, it requires explicit permission. Intent ("I'm fixing it") does not override this.

Specific footguns:

  • git reset --hard, git checkout -- <file>, git restore: destroys working tree edits silently. The user may have edited files after you wrote them. Never assume the working tree matches your last write.
  • If a file write fails because of non-matching lines, re-read it first and merge your changes, as the user may have edited the file externally.

Git operations

  • Interactive rebase opens $GIT_EDITOR and blocks. Run with GIT_SEQUENCE_EDITOR=: GIT_EDITOR=true git rebase -i <base>.
  • Use git switch (not git checkout) when changing or creating branches
  • Keep branch names very short and simple. Don't append my name or ticket numbers to the branch name
  • When pushing feature branches, always use the full push command git push origin <branch>

Remote access

Never mutate remote cloud systems, like databases, Kubernetes, AWS, etc. Services that are used for development (GitHub, Grafana, etc.) are fine to write to when prompted. Full local docker read and write access is also allowed