naudachu
f18a633185
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>
217 lines
9.0 KiB
Markdown
217 lines
9.0 KiB
Markdown
# 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:api` skill | Everything else Gitea has, through `kettle api` and the same login: pull requests, releases, tags, milestones, branches, actions, webhooks, notifications |
|
|
| `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 despite its `.sh`
|
|
name; `python3` must be on `$PATH`. Nothing else here needs it.
|
|
|
|
There is **no second CLI to install** — `kettle api`
|
|
reaches every Gitea entity this plugin has no command for, under the login the
|
|
project already pins.
|
|
|
|
### Installing the binary
|
|
|
|
Building it needs **Go 1.26** — `cli/go.mod` says so because the Gitea SDK
|
|
requires it. `vendor/` is committed, so a build compiles exactly what is in this
|
|
repository's history.
|
|
|
|
```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 request it composed itself — `kettle api` goes out as the
|
|
caller spelled it, and a deletion is never something it adds. 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 one hook
|
|
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
|
|
api/ /kettle:api — every other Gitea entity, by endpoint
|
|
```
|
|
|
|
`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.
|