naudachu
01fb5a2703
There is no CI: the instance has no act_runner and none is planned, so releases are cut by hand. That makes `make check` the only thing standing between a mistake and the tracker, and it is one command: gofmt, vet, the suite with the cache defeated, `go mod verify`, a vendored build, and `kettle gen skills --check`. The last one is the invariant worth having — the plugin's SKILL.md command reference is generated from the binary's registry, so a flag that changed cannot ship with documentation that recommends the old one. `cli/cmd/release` publishes to Gitea using the same SDK the binary already vendors, which is a pleasing thing to be able to say: nothing third-party handles the artifacts. It is a second binary rather than a `kettle` subcommand on purpose — `kettle`'s command tree is what generates the plugin's skills, so a verb there ships to every operator, and publishing a release is build infrastructure. It is idempotent end to end: an existing release for the tag is reused, an asset of the same name is replaced rather than doubled, and a retried run converges instead of duplicating. `make release` refuses three things, each with its own message: a dirty working tree, a TAG that is not what `git describe` reports, and a tag the remote does not have. A release built from uncommitted code is unreproducible and nobody finds out until they need to reproduce it. `kettle version` reports the stamp, the toolchain and the VCS revision. The default is `dev`, and a hand build says so and means it — a binary out of somebody's working tree is not a release and must not claim to be one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.8 KiB
AGENTS.md — the tdl plugin
Three Dots Labs Go conventions as an enforceable rule set. One skill,
/tdl:audit, which does two things with the same body of rules: audits a Go project
against them, or scaffolds code that already follows them.
No binary, no hooks, no state, no network. Everything here is markdown an agent reads.
.claude-plugin/plugin.json the manifest
skills/audit/
SKILL.md the procedure: parse args, load rules, audit or scaffold
references/rules-*.md nine rule files, loaded in full before any operation
templates/*.md nine scaffolds, one per generated artefact
The rules
Nine files, by subject: architecture, domain, cqrs, repository, errors,
ports, naming, codestyle, watermill. They encode the conventions of the
wild-workouts-go-ddd-example reference implementation and the four canonical Three
Dots Labs articles — DDD Lite in Go, Introducing Clean Architecture, Basic CQRS in
Go, Repository Pattern in Go.
The skill loads all nine before it does anything, in parallel, and the reason is that the rules cross-reference each other: a naming finding is only correct in the light of the layer the file sits in, and an audit that read one file would report violations of a rule it had not read the exception to.
Findings are reported by severity, and the severity is part of the rule, not a judgement made at report time. That is what makes the output usable: a run that flags everything equally is a run somebody stops reading.
The templates
Nine, one per artefact the scaffolder can produce: service, command, query,
entity, repo, unified_server, watermill_router, event_handler,
event_publisher.
They exist so that "generate a handler" and "audit a handler" cannot disagree — a template that would fail the audit is a bug in the template. When a rule changes, the templates it touches change in the same edit; that is the plugin's only real invariant and nothing mechanical checks it.
Usage
/tdl:audit # audit the working directory
/tdl:audit ./internal/orders # audit one path
/tdl:audit scaffold command PlaceOrder # generate from a template
/tdl:audit scaffold service Billing
The scaffold types are listed in the skill's argument parsing, and an argument that matches no pattern gets usage help rather than a guess.
Keeping this file true
- Scope: this plugin's layout, the two things the skill does, and the
template ⇄ rule invariant. Files:
SKILL.md,references/,templates/. - Update it when a rule file or a template is added or removed (both lists above name every one), a scaffold type is added, or the skill grows a third mode.
- Do not copy rule content here. The references are the rules; this file says what they are for.