git.giacomolli.uk - onechat/blob - AGENTS.md

   1 # Agent guide
   2
   3 Read this file in full. It holds the rules for every task.
   4
   5 ## References
   6
   7 - `README.rst`: project scope, setup, and commands.
   8 - `AGENTS.local.md`: the preferences of one person, machine, or account.
   9   Git ignores it. Read it when it exists. When it conflicts with this
  10   guide, this guide wins.
  11
  12 ## Skills
  13
  14 Read the `SKILL.md` of a skill before you start the task that it covers:
  15
  16 | Task                                            | Skill                    |
  17 | ----------------------------------------------- | ------------------------ |
  18 | Write or change Go code or Go tests             | `.agents/skills/go-code` |
  19 | Write or change documentation or prose comments | `.agents/skills/docs`    |
  20 | Format and check the repository                 | `.agents/skills/check`   |
  21 | Make any commit                                 | `.agents/skills/commit`  |
  22 | Read or write an issue                          | `.agents/skills/issues`  |
  23
  24 ## Rules
  25
  26 - Use ASD-STE100 Simplified Technical English for communication with the
  27   user, documentation, and code comments.
  28 - Every file describes the current state only. Do not write history in
  29   files: no dates of changes, no "was", "previously", or "no longer",
  30   and no changelogs or work logs. Git records what changed and why.
  31 - Keep the implementation small. Add a feature, dependency, or
  32   integration only when a task requires it.
  33 - Change only what the task asks for. Do not change unrelated code to
  34   match a style rule.
  35 - Nix is the reference environment. The pinned flake supplies the Go
  36   toolchain, the tools, and every dependency. Keep Nix code in `nix/`.
  37   Do not install host dependencies or add a dependency that works only
  38   outside Nix.
  39 - Write only ASCII characters in files, commit messages, and issues. Use
  40   `<-` and `->` for arrows, `-` for dashes, and straight quotes. Use
  41   other characters only in test data that checks Unicode handling.
  42 - Keep secrets and local runtime files out of Git and Nix sources.
  43 - Do not reveal infrastructure in files, code comments, commit messages,
  44   or issues. This includes host, server, and domain names, IP addresses,
  45   ports, network devices, user names, paths outside the repository, and
  46   deploy steps. Values from `AGENTS.local.md` or the local machine are
  47   private too.
  48 - Use a neutral placeholder, such as `example.com` or `HOST`, or
  49   describe the condition instead. Write a real value only when the user
  50   explicitly allows that value for the current task.
  51 - Change `AGENTS.md` and `.agents/` only when the user asks.
  52 - Put personal, machine, or account preferences in `AGENTS.local.md`,
  53   never in a tracked file.
  54
  55 ## Decisions
  56
  57 Stop and ask the user before you act when:
  58
  59 - the task can be read in more than one way;
  60 - two or more reasonable solutions give different results;
  61 - the task conflicts with this guide or a skill.
  62
  63 Ask one short question. Give the options and your recommendation.
  64 Continue only with work that the answer cannot change.