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>
99 lines
5.3 KiB
Markdown
99 lines
5.3 KiB
Markdown
# AGENTS.md — the repository root
|
|
|
|
One repository holding a Claude Code **plugin marketplace** and the **binary one
|
|
of its plugins drives**. Three things live here and nothing else does:
|
|
|
|
```
|
|
.claude-plugin/marketplace.json the catalog: one entry per plugin
|
|
cli/ the kettle binary — Go, no cobra, 8 packages
|
|
plugins/ one directory per plugin
|
|
```
|
|
|
|
Where to go from here, and each of these directories documents itself:
|
|
|
|
| directory | what it is |
|
|
|---|---|
|
|
| [`cli/`](cli/AGENTS.md) | one Go module, two binaries: `kettle`, which owns this project's connection to its tracker — the format, the store, the credentials, the transport, and through `kettle api` every Gitea entity that has no command of its own — and [`cmd/release`](cli/cmd/release/AGENTS.md), which publishes this repository's own releases. `make check` is the gate; there is no CI here |
|
|
| [`plugins/`](plugins/AGENTS.md) | what a plugin is here, and what the catalog entry has to match |
|
|
| [`plugins/kettle/`](plugins/kettle/AGENTS.md) | the plugin that wraps the binary: skills, the runner subagent, the hooks |
|
|
| [`plugins/tdl/`](plugins/tdl/AGENTS.md) | the Three Dots Labs Go rule set — no binary, no state, just rules and templates |
|
|
|
|
The split between `cli/` and `plugins/kettle/` is the one architectural fact
|
|
worth carrying: **a binary holds what can be enforced, a plugin holds what can
|
|
only be stated.** Anything mechanical belongs in Go where a test can hold it
|
|
down; anything that is a judgement an operator makes belongs in a SKILL.md.
|
|
|
|
`kettle api` is that rule applied to an external dependency rather than to a
|
|
script. Reaching a release or a pull request used to mean requiring `tea`, which
|
|
put the credentials, the request and the flags outside anything this repository
|
|
could test — so the mechanical half came in as one command over the transport
|
|
that already existed, and what stayed in the plugin is the half that was never
|
|
mechanical: which endpoint answers the question, and whether the thing should be
|
|
deleted at all.
|
|
|
|
## The AGENTS.md convention
|
|
|
|
**Every directory with a story documents itself, in that directory.** This file
|
|
is a map, not a manual — it says what lives where and sends you down. A reader
|
|
who opens `cli/internal/gitea/` gets the transport's rules from
|
|
`cli/internal/gitea/AGENTS.md` and does not have to load the whole repository's
|
|
design to change one request.
|
|
|
|
Three rules make that work:
|
|
|
|
1. **`AGENTS.md` is the real file; `CLAUDE.md` beside it is a symlink to it.**
|
|
`plugins/kettle/hooks/agents-sync.sh` enforces that before every Bash call and
|
|
repairs any directory that drifted — it renames, re-points and swaps, and it
|
|
never deletes content. Two real files with different content is the one case
|
|
it refuses to resolve and reports instead. `CLAUDE.md` is gitignored, because
|
|
it is generated.
|
|
2. **A directory's file describes that directory only.** What a parent or a child
|
|
owns gets a link, never a second copy — the copy is what goes stale. If a
|
|
sentence is true of the whole binary it belongs in `cli/AGENTS.md`; if it is
|
|
true of one package it belongs in that package's file.
|
|
3. **Every file ends with its own maintenance contract** — the *Keeping this file
|
|
true* section. It names the files the document covers and what kind of change
|
|
obliges an edit.
|
|
|
|
### What keeps them true
|
|
|
|
Nothing automatic, and that is a choice. Keeping these files honest is the job of
|
|
whoever changes the code they describe, which is what the *Keeping this file true*
|
|
section at the bottom of each one is for.
|
|
|
|
A hook that nagged after every write was written and then removed: it would have
|
|
fired for every user of the `kettle` plugin, on every edit in every repository
|
|
they touched, to enforce a documentation convention that is this repository's and
|
|
nobody else's. A plugin about issue tracking does not get to reach that far.
|
|
|
|
`plugins/kettle/hooks/agents-sync.sh` stays, because it repairs the filesystem
|
|
layout rather than asking anybody for anything: `AGENTS.md` a real file,
|
|
`CLAUDE.md` a symlink to it. It cannot fail a tool call — it exits 0 on every
|
|
path, including its own bugs, because documentation maintenance is not permitted
|
|
to break a build.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
cd cli && make check # fmt, vet, test, go mod verify, build, docs — the gate
|
|
cd cli && make help # install, dist, release
|
|
```
|
|
|
|
**There is no CI on the instance this lives on**, so `make check` is the only thing
|
|
between a mistake and the tracker, and it is on whoever is committing to run it. Its
|
|
last step is the repository's one mechanical documentation invariant: the
|
|
command reference an agent reads inside the plugin is generated from the command
|
|
registry the binary is built from. Everything else in this tree — including every
|
|
`AGENTS.md` — is prose, and prose is held true by the hook above and by whoever
|
|
is editing.
|
|
|
|
## Keeping this file true
|
|
|
|
- **Scope:** the repository layout, the plugin/binary split, and the AGENTS.md
|
|
convention itself. Every deeper subject belongs to a deeper file.
|
|
- **Update it when** a top-level directory appears or goes, a plugin is added or
|
|
removed, the marketplace catalog changes shape, or either hook's behaviour
|
|
changes.
|
|
- **Do not** put a command reference, a package's rules, or a skill's procedure
|
|
here. Link to the file that owns it.
|