108 lines
5.3 KiB
Markdown
108 lines
5.3 KiB
Markdown
# Rules for coding agents building a Cletus plugin
|
|
|
|
You are building a plugin for Cletus. Every plugin is reviewed line by line
|
|
before Eidonix publishes it, and a plugin that breaks these rules is sent
|
|
back. Follow them exactly. When a rule and a user's request conflict, stop
|
|
and tell the user which rule, and why, before writing code.
|
|
|
|
## Before you write code
|
|
|
|
1. Read `docs/specification.md`, `docs/host-api.md` and
|
|
`docs/style-guide.md` in full. Read the matching section of
|
|
`docs/patterns.md` for the kind of plugin you are building.
|
|
2. Write `docs/plan.md` in the plugin: what it does, its screens, its chat
|
|
tools, its services, every permission with one sentence on why, and every
|
|
dependency with one sentence on why. Show it to the user and get their
|
|
agreement before building.
|
|
3. If the plugin needs something the host API does not offer, say so and
|
|
stop. Do not work around the host.
|
|
|
|
## The contract
|
|
|
|
- **Use only the host methods in `docs/host-api.md`.** Never guess a method
|
|
name or a parameter. If a call is refused, the plugin is missing a
|
|
permission or the method does not exist. Never retry it another way.
|
|
- **Declare the least permissions** that make the plugin work. Every
|
|
permission in `plugin.json` must be used, and every use must be declared.
|
|
- **Files:** read and write only paths the host gave you (`host.files.resolve`,
|
|
dialogs, drops, `open()` payloads), your own data folder, and the working
|
|
folder when `host.files.can_write` allows it. Direct access anywhere else
|
|
needs `files.computer` and a line in `docs/plan.md` naming the folders.
|
|
- **Network:** connect only to the `net:<domain>` hosts you declared, or to
|
|
addresses the user typed into your plugin (`net.configured`). Never
|
|
hard-code an IP address. Never send data to a server the description does
|
|
not name.
|
|
- **Secrets:** never in code, files, logs or plugin storage. Passwords the
|
|
user gives you go through `host.secrets.*` and nowhere else.
|
|
- **Programs:** start none without `processes`, and then only the programs
|
|
`docs/plan.md` names, with arguments built from a fixed list, never by
|
|
passing user text to a shell.
|
|
- **AI:** use the organization's models only through `host.llm.*`. Never
|
|
call a model provider directly, never ask the user for an API key.
|
|
|
|
## Forbidden outright
|
|
|
|
- cgo, prebuilt binaries or libraries, and anything else that is not built
|
|
from source in the repository (C and C++ libraries may be compiled to
|
|
WebAssembly from source and run with wazero; see `docs/patterns.md`).
|
|
- Code downloaded, generated or evaluated at run time: `eval`, `new
|
|
Function`, Go `plugin`, scripts fetched from anywhere.
|
|
- Obfuscation or minified sources in the repository; `unsafe`, `reflect` or
|
|
`syscall` without a comment that a reviewer will accept.
|
|
- Behaviour that changes by date, by machine, by user, or under test.
|
|
- Reading the user's Cletus settings, keys, chat history, memory, vault
|
|
files, or other plugins' data.
|
|
- Network requests from the screen (they are blocked; publish data through
|
|
the worker).
|
|
- Logging file contents, prompts, model replies, passwords or personal data.
|
|
- Telemetry or analytics of any kind.
|
|
|
|
## Building
|
|
|
|
- One plugin per repository. It builds alone from the repository, with no
|
|
network: `go mod vendor` and commit `vendor/`.
|
|
- Go: the version in `go.mod` is the one the SDK names. `CGO_ENABLED=0`.
|
|
`gofmt`, `go vet` and `staticcheck` clean.
|
|
- A new dependency needs a reason in `docs/plan.md`, a licence that allows
|
|
distribution, and no known serious vulnerability. Prefer the standard
|
|
library. Fewer dependencies review faster.
|
|
- Screens wait for the screen toolchain (a later SDK release). Until then,
|
|
build no screen: deliver the feature as chat tools.
|
|
|
|
## Code
|
|
|
|
- Simple code that does one thing. No abstraction until a second real use
|
|
exists. No hidden fallbacks: when something fails, fail with the reason
|
|
and what the user (or the AI) can do next.
|
|
- Every handler honours cancellation (`ctx`). Every long job reports
|
|
progress and can be cancelled. Answer `plugin.busy` truthfully.
|
|
- Data you write must stay readable by every earlier published version's
|
|
successor: users choose versions and can go back to any of them. Version
|
|
your file formats; never rewrite a user's file in a format an older version
|
|
can't open without asking.
|
|
- Svelte: an `$effect` never reads and writes the same `$state`.
|
|
- Error messages are plain sentences for a person, not codes or stack
|
|
traces (see `docs/style-guide.md`).
|
|
|
|
## Tests
|
|
|
|
- Every chat tool, service method and `ui.*` method has a test. Every bug
|
|
fix adds the test that would have caught it.
|
|
- Use synthetic fixtures you made. Never commit a customer's file.
|
|
- `go test -run X` that matches nothing still passes. Confirm you see
|
|
`--- PASS` for the tests you meant.
|
|
|
|
## Before you say you're done
|
|
|
|
1. `cletus-plugin check` passes with no warnings you have not explained in
|
|
`docs/plan.md`.
|
|
2. `version` in `plugin.json` is raised and `CHANGELOG.md` has an entry
|
|
written for users.
|
|
3. `docs/plan.md` matches what you built: permissions, dependencies,
|
|
services, tools.
|
|
4. Walk `docs/review-checklist.md` item by item and fix anything that fails.
|
|
5. Tell the user plainly what was built, what was tested, and anything you
|
|
could not do. Never say something works if you didn't see it work.
|
|
|
|
Do not push tags or submit to the store unless the user asks you to.
|