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

feat: drop the kettle plugin; the binary writes its own skills

Browse Source 
The plugin and the binary shipped on two release cadences and nothing on an
operator's machine ever checked that the one they installed described the other.
The generated flag block existed precisely so a renamed flag could not ship with
documentation recommending the old one — and then shipped one version behind the
registry it came from, which is the same bug one hop downstream.

So the prose moved into the binary. `internal/scaffold` embeds every document;
`kettle init` and `kettle gen scaffold` write them into a project's own
`.claude/`. The two cannot disagree because there is one artefact.

The namespace survived the move. A project's skills are flat, so the prefix is
spelled into the directory name (`kettle-issue`); a project's *commands* take
their namespace from a subdirectory, so `commands/kettle/init.md` is still
`/kettle:init`. Four of the six command files are thin pointers at a skill, and
that is what kept ~1,600 lines of `/kettle:…` cross-references true without a
rewrite. `init` and `auth` lost `disable-model-invocation: true` — being a
command is that property — and `auth` now restricts `allowed-tools` so a model
cannot reach `kettle auth add` at all.

`gen scaffold` writes files whole rather than splicing a region. The old
refusal protected somebody's hand-written prose around the block; that prose is
embedded now, so there is none to protect, and preserving local edits would
freeze a project's documentation at whatever version first initialized it.
`--check` warns before an upgrade discards one.

The plugin's `agents-sync.sh` — 141 lines of Python behind a filename that said
`.sh` — became `internal/mirror` and `kettle mirror`. Same seven branches, same
refusal to merge two real files that differ, now with a table test per branch
and a check that a repair converges in one pass. `--hook` is the PreToolUse
form and exits 0 on every path including a panic. It is opt-in per project,
which is strictly narrower than the plugin hook that was on for everybody who
installed it.

`kettle init --interactive` walks a person through the login, the token (read
with the echo off, so it lands in no history and no file), the repository, the
`.claude/` tree and the mirror hook. It refuses a stdin that is not a terminal
and names the flags instead: every question it asks has one, and it performs
nothing itself, so an interactive run and a flag run are one code path.

Two rules that used to be prose are now the binary's: init refuses a linked
worktree and names the main checkout, and writing into an existing
`.claude/settings.json` is refused with the snippet printed rather than
reformatting a file the operator commits.

The scaffold version stamp went to its own `.kettle/scaffold.yaml` rather than
into `config.yaml`, because unknown keys there are a hard error and that file
may be committed and read by whatever build each machine has.

golang.org/x/term becomes a direct dependency; it was already in the tree
indirectly, so no module was added.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
naudachu
2026-08-12 16:17:24 +05:00
parent f18a633185
commit 8b1b11001a
445 changed files with 231172 additions and 1339 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cli/internal/cmd/AGENTS.md
+105 -28
View File
@@ -11,9 +11,9 @@ and therefore cannot be tested.
Each command is one `register(&Command{…})` in an `init()`, carrying the metadata a
human needs — `Short`, `Long`, `Examples`, `Args`, `Group` — **in the same struct
that carries the code**. That is what lets the plugin's SKILL.md files be generated
from this list: a command whose flags changed cannot ship with documentation that
says otherwise.
that carries the code**. That is what lets a project's skills be generated from
this list: a command whose flags changed cannot ship with documentation that says
otherwise.
```go
func init() {
@@ -47,20 +47,34 @@ token of every invocation, and the grouping that matters for reading is carried
| `command.go` | `Command`, the registry, `Main`, help rendering, `SilentError`, `Fail`, and `permute` |
| `flags.go` | `storeFlag`/`storeRoot`, `wasSet`, the repeatable `stringList` |
| `sync.go` | `syncStart`/`syncStartExisting`, `commentsSidecarPath` — the shared opening of every tracker command |
| `gen.go` | `kettle gen skills`: the generated region in the plugin's SKILL.md files |
| `init.go` `auth.go` `config.go` `version.go` | group `project`. `version.go` also holds `Version`, the string a release build stamps in with `-ldflags -X` |
| `gen.go` | `kettle gen scaffold`: rendering [`scaffold`](../scaffold/AGENTS.md)'s documents with the registry's flag tables spliced in |
| `init.go` `auth.go` `config.go` `version.go` `mirror.go` | group `project`. `version.go` also holds `Version`, the string a release build stamps in with `-ldflags -X` |
| `interactive.go` | `kettle init --interactive`: the only thing here that reads a terminal |
| `settings.go` | registering `kettle mirror --hook` in `.claude/settings.json`, and refusing to reformat one it did not write |
| `new.go` `check.go` `ac.go` `tree.go` `index.go` `evict.go` | group `issue` — no network in any of them |
| `pull.go` `push.go` `remote.go` `comment.go` `close.go` `labels.go` `evict_sync.go` | group `sync` |
| `api.go` | group `api`, alone in it: one request to an endpoint nothing here wraps |
| `cli_test.go` | builds the binary in `TestMain`, runs it as a subprocess |
| `sync_pull_test.go` `sync_write_test.go` `api_test.go` | the tracker halves, against fake servers |
| `gen_test.go` | the generator: determinism, the region splice, the missing-marker refusal |
| `gen_test.go` | the generator: the whole tree, determinism, and that a local edit does not survive |
| `mirror_test.go` | the repair command, and the hook form's promise never to fail a Bash call |
| `init_scaffold_test.go` | the `.claude/` tree, the settings refusal, the worktree refusal, the not-a-terminal refusal |
| `scaffold_coverage_test.go` | the registry ⇄ documents seam, in the one package that can see both |
The fourth group is one command and was still worth naming, because a group is a
skill directory over in the plugin: `api` is a subject somebody loads on its own —
skill written into a project: `api` is a subject somebody loads on its own —
which endpoint, and does it paginate — and folding it into `sync` would have put
"how do I cut a release" behind a skill about the issue round trip.
**`mirror` is the one command in the tree that has nothing to do with issues**,
and it is here rather than in a second binary for the reason this repository
keeps repeating to itself: a binary holds what can be enforced. Repairing an
`AGENTS.md`/`CLAUDE.md` pair is a seven-branch filesystem decision with one
refusal in it, which is a thing a table test can hold down and a shell script
cannot. It was 141 lines of Python behind a filename that said `.sh`, shipped in
the plugin's hooks; when the plugin went, the shell had nowhere to live and Go
did. The domain is untouched: [`mirror`](../mirror/AGENTS.md) imports nothing.
## Three conventions every command follows
**Flags may come after positionals.** The standard `flag` package stops parsing at
@@ -114,7 +128,9 @@ because that is what the operator asked for.
kettle help # the tree, grouped
kettle help push # one command in full: flags, defaults, examples
kettle init --interactive # a person at a terminal, walked through it
kettle init --login noodles --repo owner/name
kettle mirror --check # AGENTS.md ⇄ CLAUDE.md, everywhere below here
kettle new --type task --title "Wire sqlc into the appclick repo layer"
kettle ac wire-sqlc-appclick --check 3
kettle check --strict # exit 1 on any error; --strict counts warnings too
@@ -125,9 +141,59 @@ kettle sync-evict --dry-run
```
Every command's own `Long` text is the reference — it is what
`kettle help <name>` prints and what the generator writes into the plugin. **Do not
restate a flag table here**; it would be a third copy of something already in two
places, one of them mechanically checked.
`kettle help <name>` prints and what the generator splices into
[`scaffold`](../scaffold/AGENTS.md)'s documents. **Do not restate a flag table
here**; it would be a third copy of something already in two places, one of them
mechanically checked.
## `--interactive`, and the two things it may never become
`interactive.go` is the only code in this binary that reads a terminal. Two rules
hold it in place, and both are about what it must not turn into.
**It answers no question the flags cannot answer.** Every prompt has a field in
`initOptions` and therefore a flag — `--login`, `--repo`, `--scaffold-out`,
`--no-scaffold`, `--mirror-hook`. A capability reachable only by answering a
prompt would be a capability no script, no CI run and no agent could ever use.
**It performs nothing.** It fills the struct in and hands it back, so `runInit`
is one code path: the run that follows an interactive session is byte for byte
the run somebody else gets from flags.
It **refuses a standard input that is not a terminal**, and that refusal is load
bearing rather than fussy. A model that reached for `--interactive` would
otherwise block forever on a prompt nobody is going to answer; the error names
the flags instead. It is also what makes the one genuinely better thing here
possible — `term.ReadPassword` puts a token in no history, no file and no
scrollback, which every other route into this binary can only approximate.
`--repo` is offered with a guess read out of `.git/config`, parsed rather than
shelled out to. `git` is one more thing that has to be installed and one more
process to misread; a guess is worth what it costs, and anything unparseable is
no guess at all.
## Writing into `.claude/settings.json`
`settings.go` registers `kettle mirror --hook` on `PreToolUse(Bash)`, and is the
only place this binary touches a file the operator owns and commits. It has three
outcomes and the third is the whole reason it is not ten lines long:
- **no file** — written, hook and all;
- **a file already holding a `kettle mirror` hook** — nothing happens;
- **a file holding something else** — **refused**, with the snippet printed to
paste, unless `--force-settings`.
Go's `encoding/json` cannot preserve key order, so any merge reformats the whole
document. An operator who asked for a documentation hook and got an unrelated
diff across a file they share with their team has been badly served; a snippet
they paste costs them ten seconds. The refusal is reported on stderr and the run
still **succeeds** — everything before it already happened, and reporting a
failure would send somebody looking for damage there is none of.
The registered command carries a `command -v kettle` guard. That line outlives
this binary: an operator who uninstalls `kettle` would otherwise get
`command not found` on every Bash call, from a hook they set up months ago and
have long stopped thinking about.
## push and pull, the two halves of one rule
@@ -173,30 +239,40 @@ the body** — it is a fetch, not a merge — with checkbox state the one except
## The generator
`gen.go` writes the plugin's SKILL.md command reference from this registry.
`gen.go` writes a project's `.claude/` tree: [`scaffold`](../scaffold/AGENTS.md)'s
embedded documents, with this registry's flag tables spliced into the four that
declare a region.
**It owns a region, not a file.** Everything between `<!-- kettle:gen -->` and
`<!-- /kettle:gen -->` is replaced on every run; every byte outside comes back
exactly as it was, which matters most for `description:`, the prose that decides
whether an agent loads the skill at all and the one thing here no generator can
write. A file with **no** markers is reported and left alone, never overwritten —
clobbering somebody's prose because they forgot a marker is the failure this design
exists to prevent.
**It writes every file whole, and that is a deliberate reversal.** The old
generator owned a region and left every byte outside it alone, because the prose
around the block was somebody's hand-written file in this repository. It is not
any more — it is embedded — so there is no hand-written half left to protect, and
preserving local edits would freeze a project's documentation at whatever version
first initialized it. The markers stay in the output so a reader can still see
which half came from the registry.
The principle the old refusal protected did not go away; it moved. **Nobody's
prose is clobbered because nobody's prose is there** — it lives in `assets/`, next
to the code it describes, and `--check` warns before an upgrade replaces a local
edit.
The output is deterministic to the byte — no timestamps, no map iteration — so
regenerating something unchanged produces no diff. `--check` is that property made
useful: it writes nothing and exits 1 when anything on disk differs, which is what a
pre-commit hook or a CI step calls, and it wins over `--dry-run`.
useful: it writes nothing and exits 1 when anything on disk differs, which is what
a pre-commit hook or a CI step calls, and it wins over `--dry-run`.
One file per **group**, so adding a group here adds a skill directory over there;
name one only when it is a subject somebody would load on its own. `api` was
added exactly that way, and the first `gen skills` run after it wrote a stub whose
`description:` said TODO — a stub is not shippable, and filling that line in by
hand is the last step of adding a group, not an optional one. A command with no
`Group` is in no skill and the run says so. A `Long` or `Example` that spells a
region marker out in full is a hard error — the generated block would end inside
One document per **group**, so adding a group here means adding one under
`internal/scaffold/assets`; name a group only when it is a subject somebody would
load on its own. `TestEveryGroupHasSomewhereToBeWritten` is what makes that a
two-step change rather than a silent one-step mistake — the generator walks the
documents, not the registry, so a group with no document would have its commands
written nowhere and nothing would say so. A `Long` or `Example` that spells a
region marker out in full is a hard error: the generated block would end inside
itself.
`--out` defaults to `<project>/.claude`, resolved by the same walk everything else
uses, and no marker is an answer rather than a fallback.
## Keeping this file true
- **Scope:** the shape of the command tree — the registry, the shared helpers, the
@@ -204,7 +280,8 @@ itself.
source file in this directory.
- **Update it when** a command file is added or removed, a group is added, a shared
helper in `flags.go`/`sync.go` changes, an exit code gains a meaning, a command
gains a confirmation gate, or the push/pull ordering guarantees change.
gains a confirmation gate, the push/pull ordering guarantees change, or the rules
around writing into `.claude/` change.
- **Do not** copy a flag list or a command's `Long` text here. `kettle help <name>`
and the generated SKILL.md blocks are the two places that exist for it, and a
third would be the one that drifts.