]> git.giacomolli.uk - onechat/blob - AGENTS.md
Stamp daemon log lines only outside the journal
[onechat] / 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.