Files

T

naudachu f18a633185 feat: reach the rest of Gitea with kettle api, and drop tea

The plugin required `tea`, Gitea's own CLI, for everything that is not an
issue: releases, pull requests, milestones, branches, actions, webhooks. That
put a second binary, a second set of logins nothing here could see, and 400
lines documenting somebody else's flags outside anything this repository can
test. One command over the transport that already existed removes all three.

Transport: `post` — the hand-rolled request the SDK cannot express, written for
the dependency endpoint — is generalized to an exported `Do`, and `post` is
three lines on top of it. Same http.Client, so the same RoundTripper files the
body under .kettle/payload/, the same `token …` header authenticates it, and a
non-2xx is the same *APIError. It does not paginate, does not reformat the
answer, and names no domain concept, so the layering test is untouched.

The endpoint rule is `tea api`'s, so an endpoint table written for that tool
still works — with one restriction it did not have: a full URL must be on this
instance. Every request carries the project's token in a header, and a URL on
another host would hand the token to whatever was typed.

Command: `kettle api <endpoint>` in a new `api` group, so the generator writes
plugins/kettle/skills/api/SKILL.md — group, directory and /kettle:api are one
word. No --repo and no --login, for the reason no sync command has them: a
cross-repository address is an address, and another instance is KETTLE_URL.
`-X DELETE` needs `--yes`; a flag typed on purpose is an operator's decision.

Scopes: a token minted for issues carries write:issue and answers 403 on the
first request outside issues, naming no scope. Gitea cannot be asked what a
token may do — its own token listing needs a password — so `auth add --scopes`
records it, `auth list` and `config` show it, and a 403 says which category it
is likely to be. Documentation only; nothing is checked against it.

skills/use — the tea reference, 239 lines of it — becomes skills/api: what to
ask for, which endpoints paginate, and how to write a body. Every mention of
`tea` as a requirement is gone from the manifests, the READMEs, the runner and
the four other skills; what survives is the back-compat with the old plugin,
which is a decision and not a debt.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-12 14:25:20 +05:00

5.3 KiB

Raw Blame History

AGENTS.md — the repository root

One repository holding a Claude Code plugin marketplace and the binary one of its plugins drives. Three things live here and nothing else does:

.claude-plugin/marketplace.json   the catalog: one entry per plugin
cli/                              the kettle binary — Go, no cobra, 8 packages
plugins/                          one directory per plugin

Where to go from here, and each of these directories documents itself:

directory	what it is
`cli/`	one Go module, two binaries: `kettle`, which owns this project's connection to its tracker — the format, the store, the credentials, the transport, and through `kettle api` every Gitea entity that has no command of its own — and `cmd/release`, which publishes this repository's own releases. `make check` is the gate; there is no CI here
`plugins/`	what a plugin is here, and what the catalog entry has to match
`plugins/kettle/`	the plugin that wraps the binary: skills, the runner subagent, the hooks
`plugins/tdl/`	the Three Dots Labs Go rule set — no binary, no state, just rules and templates

The split between cli/ and plugins/kettle/ is the one architectural fact worth carrying: a binary holds what can be enforced, a plugin holds what can only be stated. Anything mechanical belongs in Go where a test can hold it down; anything that is a judgement an operator makes belongs in a SKILL.md.

kettle api is that rule applied to an external dependency rather than to a script. Reaching a release or a pull request used to mean requiring tea, which put the credentials, the request and the flags outside anything this repository could test — so the mechanical half came in as one command over the transport that already existed, and what stayed in the plugin is the half that was never mechanical: which endpoint answers the question, and whether the thing should be deleted at all.

The AGENTS.md convention

Every directory with a story documents itself, in that directory. This file is a map, not a manual — it says what lives where and sends you down. A reader who opens cli/internal/gitea/ gets the transport's rules from cli/internal/gitea/AGENTS.md and does not have to load the whole repository's design to change one request.

Three rules make that work:

AGENTS.md is the real file; CLAUDE.md beside it is a symlink to it. plugins/kettle/hooks/agents-sync.sh enforces that before every Bash call and repairs any directory that drifted — it renames, re-points and swaps, and it never deletes content. Two real files with different content is the one case it refuses to resolve and reports instead. CLAUDE.md is gitignored, because it is generated.
A directory's file describes that directory only. What a parent or a child owns gets a link, never a second copy — the copy is what goes stale. If a sentence is true of the whole binary it belongs in cli/AGENTS.md; if it is true of one package it belongs in that package's file.
Every file ends with its own maintenance contract — the Keeping this file true section. It names the files the document covers and what kind of change obliges an edit.

What keeps them true

Nothing automatic, and that is a choice. Keeping these files honest is the job of whoever changes the code they describe, which is what the Keeping this file true section at the bottom of each one is for.

A hook that nagged after every write was written and then removed: it would have fired for every user of the kettle plugin, on every edit in every repository they touched, to enforce a documentation convention that is this repository's and nobody else's. A plugin about issue tracking does not get to reach that far.

plugins/kettle/hooks/agents-sync.sh stays, because it repairs the filesystem layout rather than asking anybody for anything: AGENTS.md a real file, CLAUDE.md a symlink to it. It cannot fail a tool call — it exits 0 on every path, including its own bugs, because documentation maintenance is not permitted to break a build.

Development

cd cli && make check          # fmt, vet, test, go mod verify, build, docs — the gate
cd cli && make help           # install, dist, release

There is no CI on the instance this lives on, so make check is the only thing between a mistake and the tracker, and it is on whoever is committing to run it. Its last step is the repository's one mechanical documentation invariant: the command reference an agent reads inside the plugin is generated from the command registry the binary is built from. Everything else in this tree — including every AGENTS.md — is prose, and prose is held true by the hook above and by whoever is editing.

Keeping this file true

Scope: the repository layout, the plugin/binary split, and the AGENTS.md convention itself. Every deeper subject belongs to a deeper file.
Update it when a top-level directory appears or goes, a plugin is added or removed, the marketplace catalog changes shape, or either hook's behaviour changes.
Do not put a command reference, a package's rules, or a skill's procedure here. Link to the file that owns it.