AGENTS.md — how changes are made in this repo

Read by AI agents (via opencode) and humans. Follow it.

What this repo is

The shared AI-agent workflow (.gitea/workflows/agent.yml, reusable via workflow_call) used by every other repo through a thin caller. Changes here affect ALL repos that call it — so be extra careful, keep changes small and independently mergeable, and never break the trigger gate or the loop guards.

Golden rules

You may edit any file. NEVER push to main, NEVER merge a PR — all work goes on a branch and becomes a PR a human reviews and merges.
- Narrow exception — @qa autopilot merge: @qa (and only @qa) MAY merge a single PR only when the linked issue carries the fully-automatic label, the PR is clearly correct, and any CI checks are green. @qa triggers the merge by ending its reply with the MERGE_PR marker (the workflow performs the merge + closes the issue). On any doubt or bug, @qa must NOT merge: it ends with HALT_AUTOPILOT instead, which removes the fully-automatic label and returns the issue to human control. No other agent may merge, and @qa may not merge without the label.
Never print, exfiltrate, or invent secret values.
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.

Autopilot (`fully-automatic` label)

An issue labeled fully-automatic runs without the usual human checkpoints:

@pm plans and delegates in the same turn (skips the "ready to build? reply yes" gate).
After the dev's PR is opened, @qa is auto-triggered to verify it, and merges + closes on success (see the QA merge exception above).
Kill switch: remove the fully-automatic label at any time. The label is re-read fresh at the start of every run, so the next agent turn reverts to normal human-approval behavior. @qa also removes the label itself whenever it halts on a bug or a failed merge. No label (the default) = today's behavior, unchanged.

Branches & pull requests

Start on ai/issue-<N>. Split independent changes into separate branches (one PR each). Commit and push incrementally. Do NOT open PRs yourself (automated). End your reply with the PR description block:

BEGIN_PR_DESCRIPTION
## Summary
<what changed and why>
## Changes
<short bullet list>
END_PR_DESCRIPTION

Understanding the "why"

git log / git show <commit> / git blame — history is the changelog.

When unsure

Make no changes and reply with specific questions instead.

2.6 KiB Raw Blame History