claude-skills/marketplace
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects 1 Releases 2 Wiki Activity

refactor!: rewire the plugin onto the kettle binary, and rename it

Browse Source 
BREAKING: the plugin is `kettle`, not `tea`, and its commands are `/kettle:*`.
It also now needs a binary on PATH that it did not need before; the README and
every skill say how to get one and what a missing one looks like.

The plugin was 3800 lines of Python doing what a compiled binary does better,
and the name pointed at a tool that no longer takes part: `tea` is Gitea's CLI,
and since the transport moved into the binary nothing here shells out to it for
issues at all. A plugin named after it was going to keep suggesting otherwise.

Deleted: 19 scripts, the 14-file unittest suite, and the tea-guard hook. The
guard blocked any `tea` invocation that would run under a login the model picked
instead of the operator; the binary holds its own credentials and reads the
pinned login out of the project's own config, so that failure is no longer
expressible and there is nothing left to police. agents-sync stays — it is about
AGENTS.md symlinks and has nothing to do with any of this.

What the plugin keeps is what only a plugin can carry: the rules an operator
states and a binary cannot enforce. `init` still refuses to run inside a linked
worktree and still may not be model-invoked, because which directory is the
project is a statement a person makes. The issue format reference stays here and
stays the source of truth. The runner subagent is still for batches and still
may not decide what an issue says.

The command reference in the issue, sync and project skills is GENERATED from
the binary's own command registry, between markers, so a flag that changed
cannot ship with a skill that recommends the old one. `kettle gen skills
--check` exits non-zero when they drift. The generator owns the region and
nothing outside it: the frontmatter description, which is what decides whether a
skill loads at all, stays hand-written.

`use` survives and is the one place `tea` is still named — for releases,
webhooks and actions, which kettle does not cover. Its instruction to write
`--login "$GITEA_LOGIN"` and let the hook substitute the pin was true until this
commit and is now rewritten: `tea` keeps its own configuration, kettle keeps
its own, and configuring one configures nothing in the other.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
naudachu
2026-08-12 00:04:44 +05:00
parent 1239fdee70
commit e628ad6fd9
66 changed files with 2091 additions and 12499 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/kettle/AGENTS.md
+156
View File
@@ -0,0 +1,156 @@
# AGENTS.md — the kettle plugin
This plugin is a **thin wrapper over the `kettle` binary**, which lives in this
same repository at [`cli/`](../../cli) and is documented in
[`cli/AGENTS.md`](../../cli/AGENTS.md). The binary owns everything mechanical:
what an issue is, where the store lives, who this machine is, and how issues move
to and from Gitea. Its layering, its walk, its round-trip guarantees and its
tests are described there and are **not repeated here** — one design, one place.
What a plugin can carry that a binary cannot is the reason this directory still
exists:
1. **The rules an operator states.** A binary can refuse to evict an
`origin: local` issue; it cannot refuse to be run in the wrong directory, or
decide that a migration clash is not a model's to resolve.
2. **Routing.** A `description:` in a SKILL.md frontmatter is the only thing that
decides whether an agent loads a skill at all, and no generator can write it.
3. **Procedures.** How to turn a one-line request into a properly filled
template, what to ask the user and what to never invent.
## Installing the binary
**`kettle` is not on anybody's PATH by default.** Nothing in this plugin ships
it, and a skill that assumes it exists fails with `command not found: kettle` —
which is the clearest failure available, and every skill says what to do about
it rather than falling back to something else.
```bash
cd cli && go build -o ~/.local/bin/kettle ./cmd/kettle # from this repository
go install git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest
```
`cli/go.mod` says **go 1.26** — the Gitea SDK requires it, so that is the minimum
for anybody building this. `vendor/` is committed, so a build from a clone needs
no network.
An operator who sees `command not found: kettle` installs it and re-runs; there
is nothing to configure in this plugin either way. `kettle config` is the command
that explains where a run resolved to once it does exist.
## The generated command reference
Every command line in `skills/{project,issue,sync}/SKILL.md` between
```
<!-- kettle:gen --> … <!-- /kettle:gen -->
```
is written by `kettle gen skills` from the command registry the binary is built
from, and **must not be edited by hand** — the next run replaces it. Everything
outside the markers is prose and comes back byte for byte, which is why the
frontmatter is safe.
```bash
cd cli && go build -o /tmp/kettle ./cmd/kettle
/tmp/kettle gen skills --out plugins/kettle/skills # rewrite the blocks
/tmp/kettle gen skills --out plugins/kettle/skills --check # exit 1 if stale
```
`--check` is what a pre-commit hook or a CI step calls; it writes nothing. A file
the run reports as `without a region` is one where somebody dropped the markers —
it is left alone, never overwritten, and the fix is to put them back.
**Groups and skills are not the same set, and that is the one seam.** The binary
groups its commands `project`, `issue`, `sync`; the plugin's skills are `init`,
`auth`, `project`, `issue`, `sync`, `use`. The generator writes one
`<group>/SKILL.md`, so:
| skill | generated region | why |
|---|---|---|
| `issue`, `sync` | yes — the group of the same name | the skill and the group are the same subject |
| `project` | yes — `init`, `auth`, `config`, `gen` | the flag table `init` and `auth` point at |
| `init` | no | it is a *procedure* around one command, and it is operator-only |
| `auth` | no | it is a *procedure* around two, and it must not tempt a model into typing a token |
| `use` | no | it documents `tea`, which is not this binary |
The three skills with no region hold no flag tables of their own. They name a
command and send the reader to `/kettle:project`, which is the point: a file that
hand-copies a flag list is a file that will disagree with the binary in a month.
If the generator ever cannot express what a skill needs, the answer is to change
the generator, not to paste a block that will rot.
## Layout
```
.claude-plugin/plugin.json the manifest (the marketplace catalog is one level
up, in the repo root's .claude-plugin/)
agents/
kettle-runner.md subagent (Haiku): runs kettle commands, reports a
receipt. Batches only, and no opinions about content
hooks/
hooks.json registers the PreToolUse hooks
agents-sync.sh keeps every directory canonical: AGENTS.md a real
file, CLAUDE.md a symlink to it
skills/
init/ SKILL.md /kettle:init — operator-only; the rules around
`kettle init`
auth/ SKILL.md /kettle:auth — the credential workflow around
`kettle auth` and `kettle init --login`
project/ SKILL.md generated flag reference: init, auth, config, gen
issue/ SKILL.md /kettle:issue — the offline commands
references/format.md THE canonical issue format; source of truth
sync/ SKILL.md /kettle:sync — the tracker commands
use/ SKILL.md /kettle:use — the `tea` CLI, for the Gitea entities
references/tea/ kettle does not cover: releases, webhooks,
actions, pull requests
```
`references/format.md` is the one document here that the binary does not
generate and does not own a copy of. It is the format's statement of intent —
identity, metadata, label namespaces, the per-type templates, the language rule —
and it stays hand-written.
## The rules that must survive, because a binary cannot state them
- **An `origin: local` issue is the only copy of that work.** A push deletes the
local file only after the tracker confirms the write and the number → slug
ledger is written; nothing else deletes it, ever.
- **A closed issue is evicted, not archived** — and a local one is never evicted,
in any state, not even when it is named on the command line.
- **Body prose is Russian; the title and the section headers are English.**
- **Do not run `init` inside a linked worktree.** `.kettle/` is gitignored, a
worktree reaches the main checkout's store on its own, and a marker there gives
one project two stores — the second of which disappears with the branch.
- **Which directory is the project is a statement a person makes.** `/kettle:init`
keeps `disable-model-invocation: true` for that reason, and never invents an
`--at`.
- **A migration clash is the operator's to resolve.** The binary stops and names
both files; one of them may be somebody's only copy.
## What this plugin no longer ships, and why
| gone | replaced by |
|---|---|
| every Python script under `skills/*/scripts/` — the whole domain, bridge and transport | the `kettle` binary; see `cli/AGENTS.md` for the three runtime failures that motivated it |
| `tests/` — the stdlib `unittest` suite | `cd cli && go test ./...` |
| the guard hook and its entry in `hooks/hooks.json` | nothing. It existed to stop a `tea` command running under a login the model picked; the binary holds its own credentials and reads the login out of the project's config, so the failure is not expressible any more |
| `.claude/settings.local.json` → `env.GITEA_LOGIN`, the login pin | `<project>/.kettle/config.yaml` (a login **name**) plus `~/.config/kettle/logins.yaml` (the tokens, 0600, outside every working tree) |
| the tea plugin's own store marker | `.kettle/`; `kettle init` migrates an older layout in, and each migration is a move |
`hooks/agents-sync.sh` is unrelated to any of that and stays.
All of it is in git history. `git log --diff-filter=D` finds it if a decision
needs to be re-read rather than re-derived.
## Tests
The plugin has no test suite of its own; the binary's is the suite.
```bash
cd cli && go test ./...
/tmp/kettle gen skills --out plugins/kettle/skills --check
```
The second line is the plugin's only mechanical invariant: the documentation an
agent reads agrees with the binary it is documenting.