# 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.
- **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.

## 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.