marketplace/README.md

claude-skills — the kettle binary, and a plugin marketplace

One repository holding two things: kettle, a Go binary that keeps a project's issues as local markdown and syncs them with Gitea, and a small Claude Code plugin marketplace with one plugin in it.

Installing kettle

kettle is one binary and it installs itself into your project. There is no plugin to add — cli/go.mod requires Go 1.26, and the first build downloads eight modules, verified against go.sum:

go install git.noodles.cam/claude-skills/marketplace/cli/cmd/kettle@latest

# or from a clone of this repository, version stamped:
cd cli && make install                          # ~/.local/bin/kettle
cd cli && make install BINDIR=$(go env GOPATH)/bin

Put the target directory on your PATH and check with kettle version. Then, in a project you want to track issues in:

kettle init --interactive

That walks you through the login, the token (typed with the echo off, so it lands in no history and no file), the tracker repository, and the .claude/ tree — which is where the slash commands and skills come from:

.claude/commands/kettle/*.md      /kettle:init /kettle:auth /kettle:issue
                                  /kettle:sync /kettle:api /kettle:project
.claude/skills/kettle-*/          loaded by description, never by name
.claude/agents/kettle-runner.md   the batch runner, on a cheap model

Every flag table in those documents is rendered from the binary's own command registry, and the prose around it is embedded in the same binary. They cannot describe a version of kettle other than the one that wrote them — which is the whole reason this stopped being a plugin. kettle config tells you when the tree on disk was written by an older build; kettle gen scaffold refreshes it.

Prefer flags to prompts? Everything --interactive asks has one:

kettle init --login noodles --repo owner/name --mirror-hook
kettle init --no-scaffold                       # marker and config only

The marketplace

/plugin marketplace add https://git.noodles.cam/claude-skills/marketplace.git
/plugin install tdl@claude-skills

Plugin	Commands	What it does
tdl	/tdl:audit	Three Dots Labs Go conventions as an enforceable rule set — audits a Go project against nine categories of CQRS/DDD/Clean-Architecture rules by severity, or scaffolds services, handlers, entities, repositories and Watermill adapters from templates that already follow them

---

The kettle CLI

A single Go binary that keeps a project's issues as flat markdown files and moves them to and from Gitea when you say so — and, with kettle api, reaches every other Gitea entity under the same login, so nothing here needs a second CLI. Everything outside the sync and api groups works with the network off. Two direct dependencies, vendored, no cobra, seven internal packages with one direction of imports — see cli/AGENTS.md.

What it does

project — the project itself

command	what it does
kettle init	makes this directory a project: creates the .kettle/ marker every other command resolves the store from, migrates an older store in, gitignores it
kettle auth	manages the tokens this machine holds — one file, mode 0600, outside every working tree
kettle config	prints every path and setting a run resolved to, with overrides applied. Never prints a token
kettle gen scaffold	writes the .claude/ commands, skills and subagent, prose and flag tables both, from inside this binary
kettle mirror	keeps CLAUDE.md a symlink to AGENTS.md in every directory below here. --hook is the PreToolUse form and never fails a call
kettle version	what this binary was built as — dev from a working tree, the tag when a release build stamped it in

issue — units of work, offline, no tracker involved

command	what it does
kettle new	creates a local issue from its type template. origin: local is a complete state, not a draft
kettle check	validates issues against the canonical format. Exit 1 on errors, so a hook or a CI step can call it
kettle ac	lists and ticks an issue's checkboxes — one byte of the file changes, so the diff is the state that changed
kettle tree	draws the dependency graph read off depends:
kettle index	rebuilds INDEX.md from what is on disk, progress counted from the bodies
kettle evict	removes closed issues that also live in a tracker. A local one is never evicted, in any state

sync — moving issues between the store and the tracker

command	what it does
kettle pull	fetches issues by address (42, #42, owner/repo#42, a URL) or by filter, with their blockers, comments included
kettle push	sends local issues up, blockers first, and deletes the local copy once the tracker confirms it
kettle remote	lists what exists in the tracker, one line each. Writes nothing
kettle comment	posts or edits a comment, body from a file or inline, then refetches the whole thread
kettle close	closes or reopens issues in the tracker, and on disk with them. State only
kettle labels	creates the canonical type/* and severity/* labels in a repository, exclusive flag and all
kettle sync-evict	refreshes state from the tracker first, then evicts what is closed

api — everything else Gitea has, reached directly

command	what it does
kettle api	one request to an endpoint this binary has no command for — pull requests, releases, tags, milestones, branches, actions, webhooks — under the login the project already pins. One invocation is one request; it does not paginate, does not reformat the answer, and -X DELETE needs --yes

kettle help prints the tree; kettle help <command> prints one command in full — flags, defaults and worked examples. Flags may be typed after positional arguments.

Usage

Once per project

kettle auth add --name noodles --url https://git.example.com < token.txt
kettle init --login noodles --repo owner/name
kettle config                      # what did that actually resolve to?

The token is read from standard input because an argument is in the shell history the moment it is typed. What lands in the repository is the login's name; the tokens stay in ~/.config/kettle/logins.yaml.

Working offline

kettle new --type task --title "Wire sqlc into the appclick repo layer" \
           --label tech/sql --label comp/appclick
kettle new --type bug  --title "Fix the index rebuild on an empty store" \
           --depends wire-sqlc-appclick --milestone v0.2

kettle check                       # every issue in the store
kettle check --strict              # warnings count as errors
kettle ac wire-sqlc-appclick       # numbered checkboxes with their state
kettle ac wire-sqlc-appclick --check 3
kettle tree --depth 2              # every root, two levels down
kettle index

No login, no network and no tracker for any of that. The store is flat markdown with one metadata field per line, so plain grep works without a parser:

grep -l  'labels:.*type/bug'        .kettle/issues/*.md
grep -ln 'depends:.*migrate-schema' .kettle/issues/*.md   # who depends on it

The tracker

kettle labels --dry-run            # print the plan; not one writing request
kettle labels                      # create whatever is missing

kettle push                        # everything the tracker lacks, blockers first
kettle push --update wire-sqlc-appclick
kettle push --dry-run              # validate and print the plan; no network

kettle remote --state all --label type/bug --limit 50
kettle pull 42                     # the issue and everything blocking it, any state
kettle pull 42 --no-deps           # just that one — one request
kettle pull owner/repo#42           # an issue in another repository
kettle pull --milestone v0.2 --limit 20

kettle comment wire-sqlc-appclick --file notes.md
kettle close 42 43
kettle close --reopen 42
kettle sync-evict --dry-run

The rule worth knowing before you push

The store holds what has not left this machine. A successful push deletes the local file — on --update too, one rule with no exception — and only after the tracker confirms the write. Get it back with kettle pull <n>: it lands under the same slug, with the same depends:, even on a machine that has never seen it, because the slug travelled up in the body as a marker and was recorded in a local number → slug ledger.

A never-pushed origin: local issue is the only copy of that work, and nothing deletes it — in any state, not even when it is named on the command line.

Configuration

file	holds	notes
<project>/.kettle/config.yaml	login: (a name) and repo:	written by kettle init; safe inside a repository because a name is worth nothing on its own
~/.config/kettle/logins.yaml	the tokens	one file per machine, mode 0600, outside every working tree

KETTLE_LOGIN, KETTLE_REPO, KETTLE_URL, KETTLE_TOKEN and KETTLE_CONFIG_HOME each override the file they shadow — for CI, and for anyone who would rather have no token on disk at all. An unknown key in either file is an error, not a silent drop: an older binary would otherwise delete the setting it did not recognize the next time it wrote the file.

---

Layout

.claude-plugin/
  marketplace.json           the catalog — one entry per plugin, source is a
                             path into plugins/
cli/                         one Go module, two binaries
  Makefile                   the gate and the release: make check | dist | release
  cmd/kettle/                what people install
  cmd/release/               what publishes this repository's own releases
  internal/                  seven packages, one direction of imports
plugins/
  kettle/
    .claude-plugin/plugin.json
    agents/ hooks/ skills/
    README.md  AGENTS.md
  tdl/
    .claude-plugin/plugin.json
    skills/audit/{references,templates}

A plugin's root is its directory under plugins/, so ${CLAUDE_PLUGIN_ROOT} resolves inside it and every path a plugin uses stays relative to itself. Adding a plugin means adding a directory here plus one entry in marketplace.json — nothing else in the repo needs to know about it.

cli/ is deliberately not inside a plugin: a binary is installed on a machine, while a plugin is a directory Claude Code loads, and collapsing the two is what put an earlier version's issue store inside a versioned plugin cache.

Development

There is no CI. The instance this lives on has no Actions runner and none is planned, so nothing runs on a push, nothing checks a branch, and nothing will tell you afterwards. make check is the whole gate, it takes about ten seconds, and it is on whoever is committing to run it:

cd cli && make check

Five steps in one command, non-zero the moment any of them fails:

step	what it holds down
gofmt -l cmd internal	nothing in the tree is unformatted. It reports and never rewrites — a formatting change made silently by a build is a change nobody reviewed
go vet ./...	the compiler's own second opinion
go test -count=1 ./...	the whole suite, with the test cache defeated: a gate that can pass because it passed an hour ago on different code is not a gate
go mod verify + go build -mod=vendor ./...	every module matches its hash in go.sum, and the committed vendor/ is complete and is what compiles. A vendor/ that has drifted from go.mod breaks nobody until somebody builds with a cold module cache
kettle gen scaffold --check	the documents embedded in the binary still agree with the registry it is built from. Exit 1 the moment they do not, and dist/kettle gen scaffold --out internal/scaffold/assets is the fix

That last one is circular on purpose. What a project gets is embedded in the binary with the registry's flag tables already spliced in, so the embedded copy has to hold what the current registry would produce. Change a flag and it goes stale; regenerate, then rebuild, because the binary has to pick the new bytes up.

Where the design notes are

Every directory with a story carries its own AGENTS.md, starting at the repository root and recursing into cli/, each of its packages, and each plugin. A CLAUDE.md beside one is a generated symlink to it, and kettle mirror keeps that arrangement honest — six of the seven states it can find are repaired losslessly, and the seventh (two real files whose contents differ) is reported and left alone, because one of them is somebody's writing. Register it with kettle init --mirror-hook if you want it run before every Bash call. Read the file next to the code you are changing rather than the whole tree.

make help lists the rest — build, install [BINDIR=…], dist, clean. make install puts a version-stamped binary in ~/.local/bin (override with BINDIR=$(go env GOPATH)/bin) and says so if that directory is not on your PATH, which is the whole of what a skill means by command not found: kettle.

Design notes live next to the code they describe: every directory with a story carries its own AGENTS.md, starting at the repository root and recursing into cli/, each of its packages, and each plugin. A CLAUDE.md beside one is a generated symlink to it. Two hooks in the kettle plugin keep the arrangement honest — one repairs the layout before every Bash call, the other asks for the nearest AGENTS.md to be corrected after a file is written.

Cutting a release

Releases are cut by hand, from a developer's machine, and published by this repository's own code. cli/cmd/release is a second binary in the same module that talks to Gitea's API through the same SDK kettle uses: no third-party action, and nothing between a tag and what people download that is not in this tree. It is deliberately not a kettle subcommand — kettle is a tool for issues, and its command tree is what generates the documents it writes into a project.

cd cli
make check                          # nothing else is going to run this for you
git tag -a v0.2.0 -m v0.2.0         # on the commit you mean to ship
git push origin v0.2.0
export KETTLE_URL=https://git.noodles.cam KETTLE_TOKEN=…   # or run it from an
                                    # initialized project and it reads the
                                    # login pinned there
make release TAG=v0.2.0 NOTES=../notes-v0.2.0.md TITLE="kettle v0.2.0"

step	what it verifies
make check	the five things above. A release is the worst place to find out
git tag / git push	the tag exists, and it exists on the server. A release naming a tag nobody else can fetch is a download page pointing at nothing
make release	refuses a dirty working tree — what shipped would not be what is committed, and nobody could rebuild it; refuses a TAG that is not what git describe reports — which is only true when the tag exists and HEAD is standing on it, so it also catches "I tagged, then committed one more thing"; and refuses a tag that is not on the remote
the dist it runs first	kettle cross-compiled for darwin and linux on amd64 and arm64, CGO_ENABLED=0, each stamped with the tag via -ldflags, plus a SHA256SUMS over all four
the publish	creates the release or reuses the one already there, uploads each artifact, replaces an asset of the same name rather than doubling it, and prints the release URL with every asset under it

Re-running it is safe, and that is the point. An upload that died half way through is fixed by running the same command again: the tag's release is reused, the assets that made it are replaced by the freshly built ones, and corrected notes actually land. You get one release and one copy of each asset either way.

kettle version on a downloaded binary reports the tag it was built from; a binary somebody built out of a working tree says dev and means it.