docs: AGENTS.md (gitea issue tracker workflow) + docs/agents/issue-tracker.md

2026-09-28 21:05:07 +00:00 · 2026-09-22 17:30:53 +00:00
parent 83bbe3277d
commit b34993402f
2 changed files with 76 additions and 0 deletions
@@ -0,0 +1,7 @@
+# AGENTS.md
+
+## Agent skills
+
+- **Issue tracker**: Gitea — `hermes/email-assistant` on https://gitea.nixg.ru.
+  See `docs/agents/issue-tracker.md` for the full workflow (tea CLI `gitea.nixg-full` login / gitea-mcp MCP tools, triage labels, blocking-edge convention).
+- **Domain docs**: single-context — `CONTEXT.md` and `docs/adr/` at repo root if/when they exist.
@@ -0,0 +1,69 @@
+# Issue Tracker
+
+**Tracker:** Gitea (self-hosted, https://gitea.nixg.ru)
+**Repository:** `hermes/email-assistant`
+**Web UI:** https://gitea.nixg.ru/hermes/email-assistant
+
+This is a custom ("Other") tracker configuration for the Matt Pocock engineering skills (`to-tickets`, `to-spec`, `triage`). Gitea is not natively supported by `/setup-matt-pocock-skills` (which offers GitHub / GitLab / local files), so the workflow is recorded here as freeform prose.
+
+## How to publish issues
+
+Use the **`tea` CLI** (v0.16.0, at `~/.local/bin/tea`) with the login **`gitea.nixg-full`**:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+
+# Create an issue
+tea issues create --login gitea.nixg-full --repo hermes/email-assistant \
+  --title "Ticket title" \
+  --description "Ticket body (use the to-tickets per-ticket template)" \
+  --labels "ready-for-agent"
+
+# List issues
+tea issues list --login gitea.nixg-full --repo hermes/email-assistant -o simple
+
+# Show one issue (with comments)
+tea issues --login gitea.nixg-full --repo hermes/email-assistant 42 --comments
+
+# Add a comment
+tea comment --login gitea.nixg-full --repo hermes/email-assistant 42 "comment"
+
+# Close / reopen
+tea issues close --login gitea.nixg-full --repo hermes/email-assistant 42
+```
+
+**Alternative:** the `gitea` MCP server (gitea-mcp, 72 tools: `create_issue`, `list_issues`, `update_issue`, `add_issue_labels`, ...) is configured in Hermes `mcp_servers.gitea` — it talks to the same instance with the same token. Use whichever is more convenient; prefer MCP tools when you are already in an agent session, `tea` for quick shell checks.
+
+## Repository and credentials
+
+- Instance: `https://gitea.nixg.ru` (API v1.26.2, external VPS 5.129.217.146)
+- Owner/repo: `hermes/email-assistant` (issues enabled: yes)
+- Login (tea): `gitea.nixg-full` — token `hermes-mcp-full` (full: `read:user`, `write:user`, `read:issue`, `write:issue`, `read:repository`, `write:repository`)
+- Token source: `/opt/hermes/.hermes/secrets/git-tokens.env` (`GITEA_NIXG_TOKEN`); also in Hermes `config.yaml` → `mcp_servers.gitea` env `GITEA_TOKEN`.
+- SSH (for git push): `ssh://git@gitea.nixg.ru:2222/hermes/email-assistant.git`
+
+## Triage labels (created)
+
+The five canonical labels are already created in this repo (IDs shown):
+
+| Label | Color | ID |
+|---|---|---|
+| `needs-triage` | `#e11d21` | 1 |
+| `needs-info` | `#fbca04` | 2 |
+| `ready-for-agent` | `#0e8a16` | 3 |
+| `ready-for-human` | `#006b75` | 4 |
+| `wontfix` | `#ffffff` | 5 |
+
+Use `ready-for-agent` for tickets published by `to-tickets` (agent-grabbable by construction, per the skill default).
+
+## Blocking edges
+
+Gitea has no native issue-blocking links in the API used here. Follow the `to-tickets` rule for trackers without native blocking: publish tickets in dependency order (blockers first), and set each ticket's **"Blocked by"** section to the blocking issues' real identifiers (e.g. `#12`, `#13`).
+
+## Scope / local files fallback
+
+If a task is not tied to `hermes/email-assistant` (e.g. infra on another repo), either:
+- create the issue in the matching repo on gitea.nixg.ru (`tea issues create --repo <owner>/<repo>`), or
+- fall back to local markdown under `.scratch/<feature>/issues/` in that project.
+
+Update this file if the tracker repository ever changes.