agents/AGENTS.template.md

AGENTS.md — how changes are made in this repo

This file is read by AI agents (via opencode) and by human developers. Follow it.

What this repo is

A Docker Swarm homelab stack. docker-compose.yml is the stack; merging to main deploys it to node1 automatically (GitOps). So every change that lands on main ships to production, one at a time (deploys are serialized).

Golden rules

• You may edit any file in this repo (including ci/ and .gitea/).
• NEVER push to main, and NEVER merge a pull request. All work goes on a branch and becomes a PR that a human reviews and merges. You do not have merge authority — do not attempt it.
• Never print, exfiltrate, or invent secret values. You may edit config that references secrets, but never paste real secret values into comments, PRs, logs, or code.
• Keep changes minimal and match the conventions already in the file you're editing.
• Do the work on a branch — never paste code or diffs into the issue thread.

Branches & pull requests

You start on branch ai/issue-<N> (N = the issue number).

Split independent changes into separate PRs. Infrastructure changes must be small and independently mergeable, so they can be reviewed and deployed one at a time. For each independent change, use its own branch:

git checkout main
git checkout -b ai/issue-<N>-<short-slug>      # e.g. ai/issue-12-healthcheck, ai/issue-12-limits
# make just that one change
git add -A && git commit -m "<what changed>" && git push -u origin HEAD

• Only keep changes together on one branch if they genuinely must ship as a unit.
• Commit and push incrementally as you work, so progress is visible on the branch.
• Do not open pull requests yourself — the automation opens one PR per branch you push, and the maintainer merges them sequentially.

PR description

End your reply with a clean pull-request description wrapped EXACTLY between these markers. Everything before BEGIN_PR_DESCRIPTION is treated as working notes and discarded:

BEGIN_PR_DESCRIPTION
## Summary
<1-2 sentences: what changed and why>
## Changes
<short bullet list of the changes>
END_PR_DESCRIPTION

Do not paste full files or large diffs — the review happens in the PR diff.

Migrations (imperative changes)

docker stack deploy is additive — it will NOT remove a service, run a one-off command, prune, or do anything imperative. For those, add a script under migrations/ and the deploy runs it on the swarm manager (after the stack deploy), exactly once, tracked in a ledger on the node.

• Name files migrations/NNNN-short-description.sh (zero-padded; applied in sorted order).
• Make them idempotent — guard with existence checks (the ledger can be lost on a node rebuild).
• Example: if you delete a service from docker-compose.yml, also add a migration that runs docker service rm homelab_<name> — otherwise the old service keeps running after deploy.

When unsure

If the task is genuinely unclear or missing details you cannot reasonably assume, make no changes and reply with specific questions instead.