# tea — Claude Code plugin for the Gitea CLI

A Claude Code plugin that gives Claude a reference for the `tea` CLI and enforces a hard rule: every `tea` command runs under the login **the operator chose**, never one Claude picked.

## What it ships

| Piece | What it does |
|---|---|
| `/tea:auth` skill | Prompts you to pick a Gitea login and pins it to the project |
| `/tea:issue` skill | Issues as units of work — create, read, grep, validate, walk the dependency graph. Entirely offline |
| `/tea:sync` skill | Moves issues between the local store and Gitea — pull, push, comment, close, evict |
| `/tea:use` skill | Tea CLI reference for everything that is not an issue — loads command docs on demand |
| `tea-runner` agent | Subagent on Haiku that runs the scripts and reports back a receipt — the mechanical half, off your main context |
| `tea-guard` hook | PreToolUse hook that blocks or rewrites every `tea` invocation |

## The layering

An issue is a unit of work first and a Gitea row second. That is two layers,
and knowledge flows one way:

```
skills/issue    DOMAIN     what an issue is: format, validation, dependency graph
      ▲                    offline — no tracker, no network, stdlib only
      │ imports
skills/sync     BRIDGE     md <-> Gitea issue JSON, then over the wire
      ▲
      │ calls
tea-runner      EXECUTION  runs the scripts, reports a receipt — no opinions
```

Delete `skills/sync` and the issue domain keeps working. Work that lives only
on your machine is first-class, not a draft waiting to be uploaded. That is the
point of the split: you can plan, write, and validate without a tracker, and
publish only what you choose to.

## Prerequisites

- **Claude Code** — CLI, desktop app, or IDE extension
- **Python 3** — required by the `tea-guard` hook (`python3` must be on `$PATH`)
- **`tea`** — Gitea's official CLI. Install with `brew install tea` (macOS) or from [gitea.com/gitea/tea/releases](https://gitea.com/gitea/tea/releases)
- At least one login configured: `tea logins add` (interactive — run it in a terminal, not via Claude)

## Installation

This is a Claude Code plugin — install it through the plugin marketplace, not by hand-editing `settings.json`.

1. Register the marketplace this plugin ships in:

   ```
   /plugin marketplace add https://git.noodles.cam/claude-skills/marketplace.git
   ```

   Already have a local clone? Point at the directory instead:

   ```
   /plugin marketplace add /path/to/marketplace
   ```

2. Install the plugin:

   ```
   /plugin install tea@claude-skills
   ```

The skills (`/tea:auth`, `/tea:issue`, `/tea:sync`, `/tea:use`) and the `tea-guard` hook load immediately. Use `/plugin` to enable, disable, or update it later.

> The marketplace registration is written to `extraKnownMarketplaces` and the plugin to `enabledPlugins` in your settings automatically — you don't edit those by hand. There is **no** top-level `"plugins"` settings key; if you've added one from older instructions, remove it.

## First use

Run `/tea:auth` once per project. Claude will list your available Gitea logins and ask you to pick one. The choice is written to the project root's `.claude/settings.local.json` and takes effect immediately — no restart needed.

Once per *project*, not once per checkout: a `git worktree` shares its main checkout's pin. Both the hook and the scripts find it from inside a worktree, so don't run `/tea:auth` there — it would leave a second pin in a directory that disappears with the branch.

```
/tea:auth
```

After that, just ask Claude to do something with issues or Gitea — it loads the
right skill automatically. `/tea:auth` is only needed for the tracker side;
`/tea:issue` works without any login at all.

## How the login guard works

Every `tea` invocation Claude writes must carry the literal placeholder `--login "$GITEA_LOGIN"`. The `tea-guard` hook intercepts the Bash call before it runs, looks up the pinned login from `.claude/settings.local.json`, and rewrites the command to use it. The hook and the scripts look it up the same way — one search order, in `skills/auth/scripts/pin.py`.

Claude is **blocked** from:
- running `tea` without `--login` at all
- naming a login itself (e.g. `--login myaccount`)
- using any variable other than `$GITEA_LOGIN`

This prevents silent fallback to the machine's default login (often a personal account) when working in a project that belongs to a different identity.

`tea logins list` and `tea --version / --help` are exempt — they don't touch Gitea data.

## The tea-runner agent

The skills carry meaning; the scripts carry work. `tea-runner` is a subagent on
Haiku that does the second half in its own context and hands back a receipt —
what ran, what it touched, what failed, verbatim.

Delegate a **batch**: pull a milestone and rebuild the index, push the three
issues you just wrote, bootstrap the label set, post a comment from a file you
prepared. Spawning it for a single `pull.py 42` costs more than running the
command yourself; the saving is in the loop, the retry, and reading somebody
else's stderr.

It cannot decide anything. No `Edit`, no `Write`, no `--force`, no closing or
retitling, no raw `tea`, no pushing beyond the set it was handed. A missing
type, a failed validation, an unpushed dependency come back as a question, not
as a guess. The `tea-guard` hook applies to it exactly as it does to the main
session — the pinned login is enforced on every call it makes.

## Project layout

```
.claude-plugin/
  plugin.json                plugin manifest
                             (the marketplace catalog lives one level up, in
                              the repo root's .claude-plugin/marketplace.json)
agents/
  tea-runner.md              subagent (Haiku) that executes the scripts
hooks/
  hooks.json                 registers the PreToolUse hooks
  tea-guard.sh               the guard (Python 3, no deps)
  agents-sync.sh             keeps AGENTS.md real and CLAUDE.md a symlink to it
skills/
  auth/                      /tea:auth — the identity layer
    SKILL.md
    scripts/pin.py             where the login pin is and how it is found —
                               imported by _gitea.py AND by tea-guard.sh
  issue/                     /tea:issue — the issue domain, offline
    SKILL.md
    references/format.md       canonical issue format (identity, types, templates)
    scripts/                   Python 3, stdlib only, no network:
      issue.py                   domain module: slug identity, parse/render,
                                 validation, taxonomy, dependency graph,
                                 body checkboxes
      issue_new.py               create a local issue from its type template
      issue_check.py             validate against the format
      issue_ac.py                list the body's checkboxes; tick one
      issue_tree.py              draw the dependency graph
      issue_evict.py             drop closed issues the tracker also has
      issue_index.py             rebuild .tea/issues/INDEX.md
      issue_init.py              create the .tea/ marker that makes a
                                 directory a project; migrates tmp/issues in
  sync/                      /tea:sync — the bridge to Gitea
    SKILL.md
    scripts/
      map.py                     md <-> Gitea JSON, pure functions, no I/O
      _gitea.py                  transport: login pin, tea api, pagination, filters
      pull.py                    Gitea -> .tea/issues/
      push.py                    .tea/issues/ -> Gitea, then drops the local file
      remote.py                  discovery listing to stdout
      comment.py                 post or edit a comment
      close.py                   the state field, both ways
      evict.py                   refresh state: from Gitea, then evict
      labels.py                  put the canonical label set into a repository
  use/                       /tea:use — tea CLI reference (non-issue entities)
    SKILL.md
    references/tea/            command docs
```

`AGENTS.md` carries the same layout with the reasoning behind it; if the two
ever disagree, `AGENTS.md` is the one being worked from.

## Local issue store

Issues live in `.tea/issues/` as flat markdown with one metadata field per line
— so `grep -l 'labels:.*type/bug' .tea/issues/*.md` works without a parser.

**Run `issue_init.py` once per project.** It creates the `.tea/` marker, which
is what every script resolves the store from: they walk up from the working
directory to the nearest one. The marker is never inferred from the tree, and
with none anywhere the commands stop and name the directories they searched
rather than picking a plausible one.

```bash
python3 <plugin>/skills/issue/scripts/issue_init.py
```

It is idempotent, adds `.tea/` to `.gitignore`, and moves an older
`tmp/issues` store in if it finds one. Don't run it inside a git worktree: the
marker is gitignored, so a worktree has none by design and reaches the main
checkout's store on its own — exactly like the login pin.

An `origin: local` file **is** the issue — the store, and the only copy.
Anything with `origin: gitea` is a working copy of something the tracker
already has, and it is deleted as soon as a push confirms the tracker is up to
date:

- Identity is a slug (`wire-sqlc-appclick.md`), never a tracker number. Numbers
  live in a `gitea:` field.
- `origin: local` is a complete state. An issue that never leaves your machine
  is valid and finished — but it is not permanent: pushing ends it.
- **A successful push deletes the local file** (`--update` too) and prints the
  number and URL it now lives at. Only after a confirmed response: a failed
  call leaves the file exactly where it was. Get it back with `pull.py <n>` —
  same slug, same `depends:`, even after a rename in Gitea.
- Pulling overwrites the body: a fetch, not a merge. It is also how a pushed
  issue comes back.
- Nothing tracks drift, and there is no second copy to drift. A file that is
  still here has not been pushed.