Add agent notes, coding standards, and the issue tracker

CODING_STANDARDS.md

@@ -0,0 +1,80 @@
+# Coding standards
+
+Rules a reviewer applies to a diff. Anything a tool can check lives in
+`.yamllint`, `.ansible-lint`, or `scripts/check.sh`. This file covers the calls a
+tool cannot make.
+
+## Layout
+
+A service directory is either flat or role-based. Pick by the service, not by
+taste.
+
+Use the flat layout for one container plus a proxy:
+
+```
+service/
+├── files/
+├── vars/
+│   └── default.yml
+├── playbook.yml
+└── readme.md
+```
+
+Use roles when the service has more than one container, unit, or stateful volume:
+
+```
+service/
+├── roles/
+│   ├── network/
+│   ├── storage/
+│   └── service/
+├── vars/
+│   └── default.yml
+├── playbook.yml
+└── readme.md
+```
+
+`playbook.yml` lists roles in dependency order. The data tier goes first, the app
+next, and the edge last. Each role has `tasks/main.yaml`. Add
+`handlers/main.yaml` and `templates/` only when the role needs them.
+
+## Naming
+
+- `playbook.yml`, `vars/default.yml`, and `readme.md` in every service directory.
+- Role task and handler files use `main.yaml`. Playbook and vars files use `.yml`.
+  This matches the existing tree. Do not rename either set in an unrelated change.
+- Handler names describe the action, for example "Restart Caddy", not the trigger.
+
+## YAML
+
+- Two-space indent, no tabs, LF line endings.
+- Quote Jinja values only when YAML would misread them.
+- Task names are sentence case and specific. "Create the data directory" is
+  better than "Create directory".
+
+## Tasks
+
+- Prefer a module to `command` or `shell`. When a command is necessary, add
+  `creates`, `changed_when`, or `failed_when` so a second run reports no change.
+- Put a long command string in `files/` or a template.
+- A task that writes a config file notifies a handler. It does not restart the
+  container inline.
+- Do not add `ignore_errors` to silence a check. Fix the task or narrow it.
+
+## Variables
+
+- Every variable a playbook needs has a value in `vars/default.yml` or a comment
+  naming the host fact that supplies it.
+- Quote passwords so a leading `0` or a `#` survives YAML.
+- `vars/default.yml` is where this repo keeps deploy values, including passwords.
+  Treat that file as sensitive. Rotate any value that leaks.
+
+## README
+
+Each `readme.md` states what the playbook deploys, the variables the operator
+must set, and the command to run it. Link the upstream image or project.
+
+## Commits
+
+One logical change per commit. Sentence case, imperative. Reference the issue
+when there is one, for example `Closes #12`.