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/README.md
+213
View File
@@ -0,0 +1,213 @@
# kettle — Claude Code plugin for issues as local markdown
Issues are units of work first and tracker rows second. `kettle` keeps them as
flat markdown files in your project, works on them entirely offline, and moves
them to and from Gitea when you decide to — never before.
The plugin is a thin wrapper. The work is done by the **`kettle` binary**, which
lives in this same repository under [`cli/`](../../cli); the skills carry the
rules and procedures a binary cannot state, and their command reference is
generated from the binary's own command registry, so the docs cannot drift from
the tool.
## What it ships
| Piece | What it does |
|---|---|
| `/kettle:init` skill | Makes a directory a project: creates the `.kettle/` marker every command resolves the store from. Once per project, and only you can run it |
| `/kettle:auth` skill | The credential workflow — what this machine holds, and which login this project runs under |
| `/kettle:project` skill | Generated flag reference for `init`, `auth`, `config`, `gen` |
| `/kettle:issue` skill | Issues as units of work — create, read, grep, validate, tick, evict, walk the dependency graph. Entirely offline |
| `/kettle:sync` skill | Moves issues between the local store and Gitea — pull, push, comment, close, evict |
| `/kettle:use` skill | `tea` CLI reference for the Gitea entities kettle does not cover: pulls, releases, milestones, webhooks, actions |
| `kettle-runner` agent | Subagent on Haiku that runs batches of commands and reports back a receipt — the mechanical half, off your main context |
## Prerequisites
- **Claude Code** — CLI, desktop app, or IDE extension.
- **The `kettle` binary, on your `PATH`.** It is not installed for you, and
nothing here works without it — see below.
- **Python 3** — the `agents-sync` hook is a Python script; `python3` must be on
`$PATH`. Nothing else here needs it.
- **`tea`** (optional) — Gitea's own CLI, only for `/kettle:use`. `brew install
tea`, or from [gitea.com/gitea/tea/releases](https://gitea.com/gitea/tea/releases).
It keeps its own logins (`tea logins add`), separate from kettle's.
### Installing the binary
Building it needs **Go 1.26** — `cli/go.mod` says so because the Gitea SDK
requires it. `vendor/` is committed, so the build itself needs no network.
```bash
# from a clone of this repository
cd cli && go build -o ~/.local/bin/kettle ./cmd/kettle
# or, without cloning
go install git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest
```
Make sure the target directory is on your `PATH` (`go install` uses
`$(go env GOPATH)/bin`). Check it with:
```bash
kettle help
```
If a skill ever answers `command not found: kettle`, that is the whole diagnosis:
the binary is missing. Install it and run the command again — the skills say so
rather than falling back to something that half-works.
## 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 kettle@claude-skills
```
The skills 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 `/kettle:init` once per project. It creates the `.kettle/` marker that says
*this* directory is the project whose issues live in it — every command resolves
the store by walking up to the nearest one, and with no marker anywhere they stop
and name the directories they searched rather than picking a plausible one.
```
/kettle:init
```
Only you can run it; Claude can't invoke it on its own. Which directory is a
project is a statement, and a model guessing at one is the failure the marker
exists to prevent. It is idempotent, adds `.kettle/` to `.gitignore`, and moves
an older 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.
That is all `/kettle:issue` needs — no login, no network, no tracker.
For the Gitea side, give this machine a credential and pin it to the project:
```
/kettle:auth
```
Claude will list what `kettle auth` already holds and ask you to pick. Adding a
login is yours to do — the token is read from standard input so it never lands in
shell history, and never in a transcript:
```bash
kettle auth add --name noodles --url https://git.example.com < token.txt
kettle init --login noodles --repo owner/name
```
Tokens live in `~/.config/kettle/logins.yaml`, mode 0600, outside every working
tree. What goes in the repository is the login's **name**, in
`.kettle/config.yaml` — worth nothing on its own, which is what makes it safe
there. `kettle config` prints everything a directory resolved to and never prints
a token.
After that, just ask Claude to do something with issues — it loads the right
skill on its own.
## The kettle-runner agent
The skills carry meaning; the binary carries work. `kettle-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 `kettle pull 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 widening the
set it was handed, no raw `tea`. A missing type, a failed validation, an unpushed
dependency come back as a question, not as a guess.
## 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/
kettle-runner.md subagent (Haiku) that runs the commands
hooks/
hooks.json registers the PreToolUse hooks
agents-sync.sh keeps AGENTS.md real and CLAUDE.md a symlink to it
skills/
init/ /kettle:init — make a directory a project
auth/ /kettle:auth — the credential a project runs under
project/ generated flag reference: init, auth, config, gen
issue/ /kettle:issue — the issue domain, offline
references/format.md canonical issue format (identity, types, templates)
sync/ /kettle:sync — the bridge to Gitea
use/ /kettle:use — tea CLI reference
references/tea/ command docs
```
`AGENTS.md` carries the same layout with the reasoning behind it, and the
binary's own design is in [`cli/AGENTS.md`](../../cli/AGENTS.md). If any two
disagree, the binary is right and the prose is stale.
## Local issue store
Issues live in `<project>/.kettle/issues/` as flat markdown with one metadata
field per line — so `grep -l 'labels:.*type/bug' .kettle/issues/*.md` works
without a parser. The directory is gitignored by `kettle init`; drop that line if
your team decides otherwise.
It holds two kinds of file and only one of them is a store:
- **An `origin: local` file *is* the issue** — the only copy of that work. It is
a complete state, not a draft, and nothing evicts it, in any state.
- **Anything with a tracker origin is a working copy.** A successful push deletes
it — `--update` too, one rule with no exception — and only after the tracker
confirms the write. Get it back with `kettle pull <n>`: same slug, same
`depends:`, even after a rename in the web UI.
- Identity is a slug (`wire-sqlc-appclick.md`), never a tracker number. Numbers
live in a `gitea:` field.
- A closed issue is **evicted, not archived**. The store is a working set.
- Pulling overwrites the body: a fetch, not a merge. Checkbox state is the one
exception, because a tick is monotone.
- Nothing tracks drift, and there is nothing to track: a file that is still here
has not been pushed.
## Development
```bash
cd cli && go test ./... # the binary's suite
cd cli && go build -o /tmp/kettle ./cmd/kettle
/tmp/kettle gen skills --out plugins/kettle/skills --check # docs vs binary
```
The second command is the plugin's only mechanical invariant: what the skills say
about a command matches the command. Run `gen skills` without `--check` to
rewrite the generated regions after changing the CLI, and never edit inside the
`<!-- kettle:gen -->` markers by hand.