Cameron Cordes
5b5314631b
- 38 skills from mattpocock/skills into .agents/skills/ (symlinked into .claude/skills/ for Claude Code) - skills-lock.json for reproducible installs - docs/agents/: issue-tracker (Gitea via tea CLI), triage-labels (default five-role vocabulary), domain docs (single-context) - CLAUDE.md: add '## Agent skills' section pointing at docs/agents/ - .gitignore: un-ignore docs/agents/ under the local /docs/* rule
85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
# Issue tracker: Gitea (self-hosted)
|
|
|
|
Issues and specs for this repo live as issues on Gitea
|
|
(`https://git.crkc.xyz/Apps/ImageApi`). Use the `tea` CLI for all operations.
|
|
|
|
## Conventions
|
|
|
|
- **Create an issue**: `tea issues create --title "..." --description-file -`
|
|
(read the body from a heredoc on stdin), or `--description "..."` for a
|
|
one-liner. Add labels at creation with `--labels "..."`.
|
|
- **Read an issue**: `tea issues <index> --comments`. Use
|
|
`tea issues list -f index,title,body,labels,comments -o json` for
|
|
machine-readable output.
|
|
- **List issues**: `tea issues list --state open` (default state is open)
|
|
with appropriate `--labels` / `--keyword` filters.
|
|
- **Comment on an issue**: `tea comments add <index> "..."` (alias:
|
|
`tea comments <index> "..."`).
|
|
- **Apply / remove labels**: `tea issues edit <index> --add-labels "..."` /
|
|
`--remove-labels "..."`. Labels that don't exist yet are created by the
|
|
server on first use.
|
|
- **Close**: `tea issues close <index>`. It does not accept a closing
|
|
comment, so post the explanation first with
|
|
`tea comments add <index> "..."`, then close.
|
|
- **Raw API access** (for anything the `tea` subcommands don't cover):
|
|
`tea api <endpoint>` makes an authenticated request to the Gitea API
|
|
(prefixes `/api/v1/` when the path doesn't start with `/api/`).
|
|
Placeholders `{owner}` and `{repo}` are replaced from the current repo
|
|
context. Use `-F` for typed fields (numbers, booleans) and `-d` for raw
|
|
JSON bodies.
|
|
|
|
Infer the repo from the `git remote` (`-R` lets `tea` discover the Gitea
|
|
login from the remote); `tea` does this automatically when run inside a
|
|
clone. Confirm the acting user with `tea whoami`.
|
|
|
|
Unlike GitHub, Gitea numbers issues and pull requests separately, so a bare
|
|
`#42` is unambiguous once you know which surface it refers to.
|
|
|
|
## 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 pulls` equivalents (`tea pulls list/view/edit`,
|
|
`tea pulls close`, plus `tea comments` which covers PRs). Keep only PRs
|
|
from outside collaborators (drop the repo owner and team members) when
|
|
listing external PRs for triage.
|
|
|
|
## When a skill says "publish to the issue tracker"
|
|
|
|
Create a Gitea issue.
|
|
|
|
## When a skill says "fetch the relevant ticket"
|
|
|
|
Run `tea issues <index> --comments`.
|
|
|
|
## Wayfinding operations
|
|
|
|
Used by `/wayfinder`. The **map** is a single issue with **child** issues
|
|
as tickets.
|
|
|
|
- **Map**: a single issue labelled `wayfinder:map`, holding the
|
|
Notes / Decisions-so-far / Fog body.
|
|
`tea issues create --title "..." --labels wayfinder:map --description-file -`.
|
|
- **Child ticket**: an issue carrying `Part of #<map>` at the top of its
|
|
description, labelled `wayfinder:<type>` (`research`/`prototype`/
|
|
`grilling`/`task`). Once claimed, the ticket is assigned to the driving
|
|
dev.
|
|
- **Blocking**: Gitea's **native issue dependencies** (enabled on this
|
|
server), the canonical, UI-visible representation. Add an edge with
|
|
`tea api --method POST repos/{owner}/{repo}/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-issue-index>`
|
|
(the Gitea dependencies API takes the issue index, i.e. the visible
|
|
`#number`, not an internal database id). Where dependencies aren't
|
|
available, fall back to a `Blocked by: #<n>, #<n>` line at the top of
|
|
the child description. A ticket is unblocked when every blocker is
|
|
closed.
|
|
- **Frontier query**: list the map's open children (issues whose
|
|
description carries `Part of #<map>`), drop any with an open blocker
|
|
(dependency or `Blocked by` line) or an assignee; first in map order wins.
|
|
- **Claim**: `tea issues edit <n> --add-assignees <username>` (the
|
|
session's first write; `<username>` from `tea whoami`).
|
|
- **Resolve**: `tea comments add <n> "<answer>"`, then
|
|
`tea issues close <n>`, then append a context pointer (gist + link) to
|
|
the map's Decisions-so-far.
|