# AGENTS.md

## Project goals

1. **Unify and systematize issue workflow** for the development team with minimal context usage. Issue operations (create, fetch, format) are wrapped in scripts so agents spend tokens on the task, not on re-deriving commands and formats.
2. **Route all Gitea interaction through the `tea` CLI via scripts** instead of direct ad-hoc calls wherever possible. Scripts give deterministic, reviewable behavior; the `tea-guard` hook enforces that every `tea` invocation runs under the operator-pinned login.

## Repo layout

- `skills/auth` — pin the Gitea login used by `tea` (`/tea:auth`)
- `skills/use` — `tea` CLI reference, loaded on demand (`/tea:use`); `references/` holds command docs and the canonical issue format; `scripts/` holds the issue scripts:
  - `issue_get.py` — fetch issue(s) into the local grep cache `tmp/issues/`, by key or by filter (`--milestone`, `--label`, `-q`; one request per 50 issues); `--deps` walks the dependency graph and writes `tree-<slug>.md`
  - `issue_push.py` — validate a local draft, create missing labels, POST it, delete the draft
  - `issue_list.py` — discovery to stdout; `issue_index.py` — rebuild `tmp/issues/INDEX.md`; `_tea.py` — shared login/api/format helpers
- `skills/issue` — draft an issue locally in the canonical format, then push it (`/tea:issue`)

## Local issue cache

`tmp/issues/` (gitignored) is a **cache and a drafting area, not a mirror**: no
drift tracking, no sync back. Fetched issues are flat greppable markdown with
one metadata field per line; drafts live in `tmp/issues/drafts/` until
`issue_push.py` creates them in Gitea and removes the local file.
- `hooks/` — PreToolUse hooks: `tea-guard` blocks or rewrites `tea` invocations that don't use the pinned login; `agents-sync` keeps every directory canonical (`AGENTS.md` real file, `CLAUDE.md` symlink to it)