naudachu
1815d91cdf
A discussion leaves behind a directory of markdown somewhere outside this repo, and the only durable home for it is the Gitea wiki. Getting it there by hand means re-deriving the same three things every time: what each file should be called, where it goes, and whether the page already exists. Two skills wrap that, along the split the repo already uses. `skills/page` is domain, offline, stdlib-only, and knows nothing about Gitea. It imports a directory into a space under `tmp/wiki/`, titles every file, records the result in `.pages.json`, and writes the index. `skills/wiki` is the bridge — `wikimap.py` translates, and the transport is `_gitea.py`, the same one the issue side uses. There is no second transport, and `tea` has no wiki subcommand to offer one. The Gitea wiki is flat, and that fact shapes everything There are no directories. A title of `a/b` is stored as one file named `a%2Fb.md`, and Gitea escapes it by rules of its own: space becomes `-`, `/` becomes `%2F`, and a literal `-` forces a trailing `.-` marker so the two stay distinct. `Chain decisions — DC` under two levels of prefix comes back as `Simple-Chains%2FParked%2FChain-decisions-%E2%80%94-DC`. So `sub_url` is the identity, it is read back from whatever the API returned, and it is never constructed. One built by hand that is almost right does not fail — it creates a second page and abandons the first. And a real subdirectory committed into a wiki's git repository is a ghost: the file exists, the API and the web UI do not see it. `folder/page.md` in this repo's own wiki is one. Nothing here clones a wiki repo. A title is a decision, not a derivation Titles come from the first heading, because there is no mechanical route from `03-q-01-do-we-know-the-chain-participant-by-name.md` to `Q-01. Do We Know the Chain Participant by Name`. But they are derived exactly once. A re-import replaces bodies and keeps titles, so editing a heading cannot rename a published page — which would not rename it, it would publish a second one. `--retitle` opts in. It finds the prior entry by `source` rather than by path, because the path is derived from the title and a retitle moves it; looked up by path the page would read as new and the next push would duplicate it. The old file goes, `sub_url` comes along, and `pushed` is cleared — a rename can leave the body byte-identical, and push decides by body hash alone, so a stale hash would skip the rename forever. Ordering is a `NN-` file-name prefix and never reaches the title. `00-` means "this is the directory's own page", and that page is named for the directory, not for its own heading: a child's title has to extend its parent's exactly, and `ideas/00-intro.md` opens with "Ideas for chain business requirements". Path collisions are reported and never resolved. Picking a winner is how a discussion loses a document. The index is navigation, not decoration Nothing draws a tree from flat titles. `page_index.py` writes one as an ordinary page, nested by title depth rather than by manifest path order — those disagree, since on disk `Top/System.md` sorts before `Top/Ideas/Scale.md` while in the hierarchy System is a child and Scale a grandchild. A parent with no page of its own still gets a node, so its children are not hidden. Links use `sub_url` when there is one and Gitea's `[[Title|label]]` syntax when there is not, so the order is push, rebuild, push. The same stances as the issue store, for the same reasons Pull overwrites, push is additive and never deletes, change detection is one hash and there is no drift model. A page with no `sub_url` has never been published, and that is a durable state. Issues gain a `wiki:` field holding page titles — titles, not URLs, so the reference stays in the domain. It already round-trips as a foreign key; this documents it. Verified against a live Gitea 1.26.1: create, update with a message, unchanged-skip, prefix-filtered pull, byte-identical round trip, and the per-page revision history carrying the operator's own words. The probe pages were deleted afterwards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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-guardhook (python3must be on$PATH) tea— Gitea's official CLI. Install withbrew install tea(macOS) or from 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.
-
Register this repo as a marketplace:
/plugin marketplace add https://git.noodles.cam/claude-skills/tea.gitAlready have a local clone? Point at the directory instead:
/plugin marketplace add /path/to/tea -
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
extraKnownMarketplacesand the plugin toenabledPluginsin 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
teawithout--loginat 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 agitea:field. origin: localis 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.