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>
66 lines
2.8 KiB
Markdown
66 lines
2.8 KiB
Markdown
# 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.
|