sulthan
3ea96e49b2
Adds docs/agents/{issue-tracker,triage-labels,domain}.md so the engineering
skills know where issues live (Gitea via tea, not gh), which triage labels to
apply, and that domain docs are single-context.
Every CLAUDE.md was a stale subset of the AGENTS.md beside it, so each is now
a symlink and AGENTS.md is the single source of truth.
61 lines
3.5 KiB
Markdown
61 lines
3.5 KiB
Markdown
# Issue tracker: Gitea (`tea` CLI)
|
|
|
|
Issues and specs for this repo live as issues on the self-hosted Gitea instance
|
|
`gitea.violetcrown.my.id` (repo `sulthan/mangaBookmark`). **`gh` does not work here** — use
|
|
[`tea`](https://gitea.com/gitea/tea) for everything past plain git. Auth lives in `tea login`,
|
|
not a `GH_TOKEN` env var. `tea` infers the repo from the local clone's `origin`.
|
|
|
|
`tea` prints rendered boxes rather than plain text; pass `--output json` (or `-o json`) when a
|
|
skill needs to parse the result.
|
|
|
|
## Conventions
|
|
|
|
- **Create an issue**: `tea issue create --title "..." --description "..."` (`--labels`,
|
|
`--assignees` optional). Multi-line bodies: pass the body through a shell variable or heredoc.
|
|
- **Read an issue**: `tea issue <number> --comments` (add `-o json` for machine-readable output).
|
|
- **List issues**: `tea issue list --state open -o json --fields index,title,body,labels,state,author`;
|
|
filter with `--labels "..."`, `--state open|closed|all`, `--assignee`, `--keyword`.
|
|
- **Comment**: `tea comment <number> "..."` (alias of `tea comments add`).
|
|
- **Apply / remove labels**: `tea issue edit <number> --add-labels "..."` / `--remove-labels "..."`.
|
|
Labels must exist first — see `tea labels list` / `tea labels create --name "..." --color "#rrggbb"`.
|
|
- **Close**: `tea issue close <number>` (comment separately with `tea comment`; `close` takes no
|
|
`--comment` flag).
|
|
|
|
## Pull requests as a triage surface
|
|
|
|
**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature
|
|
requests; `/triage` reads this flag.)_
|
|
|
|
When set to `yes`, PRs run through the same labels and states as issues, using the `tea pr`
|
|
equivalents: `tea pr <number> --comments`, `tea pr list --state open -o json`,
|
|
`tea pr create --head <branch> --base main --title "..." --description "..."`, `tea comment`,
|
|
`tea pr close`. Gitea shares one index space across issues and PRs, so a bare `#42` may be either
|
|
— resolve with `tea pr 42` and fall back to `tea issue 42`.
|
|
|
|
## When a skill says "publish to the issue tracker"
|
|
|
|
Create a Gitea issue with `tea issue create`.
|
|
|
|
## When a skill says "fetch the relevant ticket"
|
|
|
|
Run `tea issue <number> --comments`.
|
|
|
|
## Wayfinding operations
|
|
|
|
Used by `/wayfinder`. The **map** is a single issue; **tickets** are child issues.
|
|
|
|
- **Map**: one issue labelled `wayfinder:map` holding the Notes / Decisions-so-far / Fog body.
|
|
`tea issue create --labels wayfinder:map --title "..." --description "..."`.
|
|
- **Child ticket**: an issue labelled `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`)
|
|
with `Part of #<map>` as the first body line, and a task-list entry in the map body. `tea` has no
|
|
sub-issue command, so the task list plus the `Part of` line is the canonical link.
|
|
- **Blocking**: a `Blocked by: #<n>, #<n>` line at the top of the child body. Gitea's native issue
|
|
dependencies exist in the API but `tea` does not expose them; the body line is the source of
|
|
truth. A ticket is unblocked when every listed blocker is closed.
|
|
- **Frontier query**: `tea issue list --state open -o json` scoped to the map's task list; drop any
|
|
ticket with an open blocker or an assignee; first in map order wins.
|
|
- **Claim**: `tea issue edit <n> --add-assignees <your-username>` — the session's first write.
|
|
(`tea` has no `@me` shorthand; use the Gitea username from `tea login list`.)
|
|
- **Resolve**: `tea comment <n> "<answer>"`, then `tea issue close <n>`, then append a context
|
|
pointer to the map's Decisions-so-far via `tea issue edit <map> --description "..."`.
|