53 lines
2.6 KiB
Markdown
53 lines
2.6 KiB
Markdown
# 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.
|