Add a gitea skill; point AGENTS.md at it

Forge usage was spread across AGENTS.md, docs/agents/issue-tracker.md, and
whatever the agent remembered about `gh`. Move the how-to-run-`tea` half into a
model-invoked skill so it loads on any issue/PR task, and leave AGENTS.md a
single line of identity plus pointers.

The skill carries only what `tea --help` cannot answer: `gh` is absent so the
harness's `issue://`/`pr://` URIs error out, issues and PRs share one index
space, rendered-box output needs `-o json`, `close` takes no `--comment`,
labels never auto-create, bodies need a heredoc, and a read without
`--comments` silently drops every comment (issue #123: 40 lines bare, 132 with
the flag). Tracker conventions and triage label strings stay in
docs/agents/, cited rather than copied.
This commit is contained in:
2026-08-17 17:50:09 +07:00
parent 766aa8f00d
commit 2b96b43fd0
3 changed files with 77 additions and 9 deletions
+75
View File
@@ -0,0 +1,75 @@
---
name: gitea
description: Use for every forge operation in this repo — read, create, comment on, label, close, or search an issue; create, review, merge, or check out a PR; and whenever `gh`, `issue://`, or `pr://` fails or a ticket number is ambiguous. This repo's forge is self-hosted Gitea driven by `tea`, not GitHub.
---
# Gitea, not GitHub
`origin` is the self-hosted Gitea instance `gitea.violetcrown.my.id`, repo
`sulthan/mangaBookmark`. Everything past plain git goes through
[`tea`](https://gitea.com/gitea/tea) (0.14.2 on this machine).
**`gh` is not installed**, so the harness's `issue://<n>` and `pr://<n>` URIs
error out (`GitHub CLI (gh) is not installed`, measured 2026-08-17). There is no
fallback to add — read tickets with `tea`.
`tea` infers the repo from `origin`; auth lives in `tea login`, never a
`GH_TOKEN`. Your Gitea username comes from `tea login list` — `tea` has no `@me`.
Flags are the environment's job: run `tea <command> --help` rather than trusting
a remembered flag. This file carries only what `--help` will not tell you.
## Commands
| Job | Command |
|---|---|
| Read | `tea issue <n> --comments` / `tea pr <n> --comments` — `--comments` is not optional |
| List | `tea issue list --state open\|closed\|all -o json --fields index,title,body,labels,state,author` |
| Search | `tea issue list -k "<keyword>" -L "<label>" -A "<author>"` (`-K all` also searches PRs) |
| Create | `tea issue create -t "..." -d "..."` (`-L`, `-a` optional) |
| Comment | `tea comment <n> "..."` |
| Label | `tea issue edit <n> --add-labels "..."` / `--remove-labels "..."` |
| Close | `tea issue close <n>` / `tea pr close <n>` |
| PR | `tea pr create --head <branch> --base main -t "..." -d "..."`, `tea pr checkout <n>`, `tea pr review <n>`, `tea pr merge <n>` |
## Traps
- **A bare read is a truncated read.** Without `--comments`, `tea issue <n>` and
`tea pr <n>` print the opening body and drop every comment silently — no
prompt, no marker, no hint that more exists (measured 2026-08-17: issue #123
prints 40 lines bare, 132 with `--comments`). The comments are where the
decisions live and the body is usually the stalest part of the ticket, so
**every read that exists to understand an issue or PR passes `--comments`**,
and understanding means body plus all comments plus whatever ticket they point
at. Comment count is `tea issue list --fields index,comments`, so a read that
shows fewer than that is incomplete. A PR's review comments are a second
stream: `tea pr review-comments <n>`.
- **One index space for issues and PRs.** A bare `#42` may be either: try
`tea pr 42`, fall back to `tea issue 42`. Say which one you found.
- **Output is rendered boxes**, not plain text. Anything you parse needs
`-o json`, plus `--fields` to keep the payload small. `tea pr create` prints
the PR URL on its last line.
- **`close` takes no `--comment`.** Comment with `tea comment <n>`, then close.
- **Gitea will not auto-create a label.** `tea labels list` first; missing one
gets `tea labels create --name "..." --color "#rrggbb"` before the `edit`.
- **Multi-line bodies go through a heredoc**, never inline escapes:
```bash
tea issue create -t "Title" -d "$(cat <<'EOF'
body line one
- acceptance criterion
EOF
)"
```
- **No sub-issue and no dependency command.** Gitea's API has issue
dependencies, `tea` does not expose them, so parentage and blocking live as
body lines — the shapes are in `docs/agents/issue-tracker.md`.
## Conventions this repo layers on top
Ticket bodies, wayfinding issues, and the PR-as-request-surface flag:
`docs/agents/issue-tracker.md`. Triage label strings: `docs/agents/triage-labels.md`.
A label named there still has to exist in the tracker before `--add-labels`.
Finish a forge action by stating the number you touched and its state after —
"commented and closed #71" — so the write is checkable without a second query.