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 best-practices reference application — the canonical example the team builds and points to. It is a small but realistic multi-container app, built and run with docker-compose:

api — the HTTP service (the app's public surface).
worker — background/async job processor.
db — PostgreSQL, the shared datastore.

Everything is wired so the whole stack comes up with a single docker compose up. The point of this repo is that every part demonstrates how we like things done: clear structure, tests, and CI.

Golden rules

You may edit any file in this repo (app code, docker-compose.yml, .gitea/, tests, CI).
NEVER push to main, and NEVER merge a pull request. All work goes on a branch and becomes a PR that a human (or @pm under the autopilot label) merges. You do not have merge authority.
Never print, exfiltrate, or invent secret values. Reference secrets via env vars / compose environment:; never paste real secret values into comments, PRs, logs, or code. Config that references a secret is fine; the value is not.
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.
Because this is a reference repo, favor clarity over cleverness: small services, obvious names, comments where a newcomer would need them.

Project layout (target — grows as features land via issues)

docker-compose.yml        # the whole stack: api + worker + db
api/                      # the HTTP service (its own Dockerfile)
worker/                   # the background worker (its own Dockerfile)
db/                       # schema / migrations / init SQL
tests/                    # automated tests (unit + integration)
.gitea/workflows/         # CI (build, test) + the ai-agent caller

Add a service by giving it its own top-level directory and a service entry in docker-compose.yml.

Local run & tests

Run the stack: docker compose up --build — api, worker, and db should all come up healthy.
Tests: every change must keep the test suite green. Run tests the way CI does (e.g. via a docker compose run test service or the documented test command) before you consider work done.
Prefer integration tests through compose for cross-service behavior (api ↔ db, worker ↔ db) over mocking the whole world.
Give each service a healthcheck in compose and depend on it (depends_on: condition: service_healthy) so startup is deterministic.

CI

CI lives under .gitea/workflows/. It must, at minimum, build the images and run the tests on every PR. Keep CI green — a PR that breaks the build or tests is not ready for review. When adding a new service, extend CI to build and test it too.

Branches & pull requests

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

Split independent changes into separate PRs so each is small and reviewable:

git checkout main
git checkout -b ai/issue-<N>-<short-slug>      # e.g. ai/issue-7-api-healthcheck
# 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 so progress is visible on the branch.
Do not open pull requests yourself — the automation opens one PR per branch you push.

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.

Database changes & migrations

The datastore is Postgres, and docker compose up does not magically evolve a schema. For schema changes:

Put schema/migrations under db/ (e.g. db/migrations/NNNN-description.sql, applied in order).
Make migrations idempotent / forward-only and safe to re-run.
Never require a manual, undocumented step — a fresh docker compose up on an empty volume must produce a working schema.

When unsure

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

4.5 KiB Raw Permalink Blame History