naudachu
62c8ff976d
A checkbox is the one part of a body that is state and not prose.
Everything else is written once; boxes get ticked as the work goes, and
until now the only ways to tick one were a human with an editor or a
model rewriting the whole body. The second is worse: the rewrite re-flows
lines and re-words sentences, so the issue's diff swells around a change
that means one character. Progress was invisible too — issue_index.py
builds INDEX.md from metadata and never looked inside a body, so "3 of 7
done" required opening the file.
All three pieces are domain: a checkbox is body syntax, which is part of
the answer to "what is an issue". The parser goes in issue.py so the sync
layer can reuse it instead of redefining the format on its own side.
issue.py gains checkboxes(text) -> [Checkbox(index, line, end_line,
checked, text, section)], plus set_checkbox(text, item, checked) and
checkbox_progress(text). All pure, no I/O, importable from another layer.
The scan covers the whole text, in any section: the type/feature template
keeps child issues as checkboxes under `## Issues`, so binding the parser
to `## Acceptance criteria` would silently lose half of them; the heading
is recorded, never required. Only a marker line opens an item, so a
wrapped continuation line belongs to the item above it rather than
counting as one of its own. A `- [ ]` inside a code fence is an example
of the markup and is skipped. Line numbers are relative to the text
given, which is what lets a caller work on a body or on a whole file.
issue_ac.py lists the items numbered, grouped by heading, and ticks one
by number or by substring. An ambiguous substring is an error that prints
the matches — a coin flip would tick the wrong box and look like it
worked. It patches the file rather than round-tripping through
Issue.to_text(), so exactly one character changes: metadata order,
wording, wrapping, trailing whitespace and CRLF endings all come back
byte for byte, proven by a diff in the tests.
INDEX.md gains a progress column: `3/7` for an issue with checkboxes,
blank for one without. Counted off the body at build time and stored in
no field — a second copy of the state would be wrong by the next edit.
issue_check.py is unchanged and stays that way on purpose: an unticked
box is work not done yet, not a malformed issue, and validate() carries a
comment saying so.
Delivering a tick to the tracker is out of scope — that is push.py
--update in /tea:sync.
format.md gets one clarifying bullet. It said acceptance criteria are
checkboxes but never said what a checkbox is, so the parser had to settle
questions the format left open: any section, wrapped items, fenced
examples. Those rules are now written down where the parser and the sync
layer can both point at them.
tests/ is new, and is the convention: plain stdlib unittest, no pytest
and no third-party deps, since the code under test may not have
dependencies either. Scripts are imported via sys.path.insert and every
fixture is built in a TemporaryDirectory, never in tmp/.
python3 -m unittest discover -s tests -v 32 tests, OK
skills/issue/scripts/ still imports stdlib only, with no subprocess.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
166 lines
7.4 KiB
Markdown
166 lines
7.4 KiB
Markdown
# 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 |
|
|
| `/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. Those are 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 JSON, then over the wire
|
|
▲
|
|
│ calls
|
|
tea-runner EXECUTION runs the scripts, reports a receipt — no opinions
|
|
```
|
|
|
|
Delete `skills/sync` and the domain layer keeps working — issues that live only
|
|
on your machine are first-class, not drafts waiting to be uploaded. That is the
|
|
point of the split: you can plan, write, validate, and track work 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 this repo as a marketplace:
|
|
|
|
```
|
|
/plugin marketplace add https://git.noodles.cam/claude-skills/tea.git
|
|
```
|
|
|
|
Already have a local clone? Point at the directory instead:
|
|
|
|
```
|
|
/plugin marketplace add /path/to/tea
|
|
```
|
|
|
|
2. Install the plugin:
|
|
|
|
```
|
|
/plugin install tea@tea
|
|
```
|
|
|
|
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 `.claude/settings.local.json` and takes effect immediately — no restart needed.
|
|
|
|
```
|
|
/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.
|
|
|
|
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
|
|
marketplace.json marketplace catalog (makes `/plugin install` work)
|
|
agents/
|
|
tea-runner.md subagent (Haiku) that executes the scripts
|
|
hooks/
|
|
hooks.json registers the PreToolUse hook
|
|
tea-guard.sh the guard (Python 3, no deps)
|
|
skills/
|
|
auth/SKILL.md /tea:auth skill
|
|
issue/ /tea:issue — the domain layer, 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_index.py rebuild tmp/issues/INDEX.md
|
|
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 -> tmp/issues/
|
|
push.py tmp/issues/ -> Gitea (additive; never deletes)
|
|
remote.py discovery listing to stdout
|
|
comment.py post or edit a comment
|
|
use/ /tea:use — tea CLI reference (non-issue entities)
|
|
SKILL.md
|
|
references/tea/ command docs
|
|
```
|
|
|
|
## Local issue store
|
|
|
|
Issues live in `tmp/issues/` (gitignore it) as flat markdown with one metadata
|
|
field per line — so `grep -l 'labels:.*type/bug' tmp/issues/*.md` works without
|
|
a parser.
|
|
|
|
It is **the store, not a cache of Gitea**:
|
|
|
|
- Identity is a slug (`wire-sqlc-appclick.md`), never a tracker number. Numbers
|
|
live in a `gitea:` field.
|
|
- `origin: local` is a durable state. An issue that never leaves your machine is
|
|
complete and valid.
|
|
- Pushing is additive — the file gains `gitea:` / `url:` / `synced:` and stays
|
|
put. Pulling overwrites the body: a fetch, not a merge.
|
|
- Nothing tracks drift. `synced:` tells you how old your copy is.
|