# 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.