sulthan
f5d3fe58ec
Forge usage lived in three places (`AGENTS.md`, `docs/agents/issue-tracker.md`, and habit). This moves the how-to-run-`tea` half into a model-invoked skill that fires on any issue/PR task, and reduces `AGENTS.md` to identity plus pointers. - **new** `.claude/skills/gitea/SKILL.md` — command table plus the traps `tea <cmd> --help` will not tell you. - `AGENTS.md` — Forge section is now one line: Gitea not GitHub, `gh` and the `issue://`/`pr://` URIs fail, then pointers to the skill, `docs/agents/issue-tracker.md`, and `docs/agents/triage-labels.md`. - `.claude/skills/implement-tickets/SKILL.md` — pointer split: tracker conventions to the doc, `tea` usage to the skill. Both `docs/agents/` files are untouched; the skill cites them instead of restating them. Facts in the skill are measured against `tea` 0.14.2 on 2026-08-17, not remembered: - `gh` is not installed, so `read issue://71` errors — there is no fallback to add. - **A bare read is a truncated read.** Without `--comments`, `tea issue <n>` drops every comment silently, with no prompt under a non-TTY: issue #123 prints 40 lines bare, 132 with the flag. The skill makes `--comments` mandatory for any read meant to understand a ticket, with `tea issue list --fields index,comments` as the checkable count. - Issues and PRs share one index space; output is rendered boxes so parsing needs `-o json`; `close` takes no `--comment`; labels never auto-create; multi-line bodies need a heredoc; `tea` exposes neither sub-issues nor dependencies. Unmeasured and marked as such: whether `--comments` covers a PR's review-comment stream — no PR in this repo has comments, so `tea pr review-comments <n>` is named without a claim about overlap. Reviewed-on: #126 Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com> Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>
76 lines
3.9 KiB
Markdown
76 lines
3.9 KiB
Markdown
---
|
|
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.
|