agents/AGENTS.md

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 autopilot 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 autopilot 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 (autopilot label)

An issue labeled autopilot 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 autopilot 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.
• human-merge label (together with autopilot): everything above except the merge — after @qa approves, @pm tells the creator the PR is ready and a human merges. 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.