Cletus plugin kit: rules for coding agents, specification, host API, style guide, worker SDK and cletus-plugin tool

README.md

@@ -0,0 +1,73 @@
+# Cletus plugins
+
+Build plugins for Cletus, the desktop AI assistant for engineering and
+manufacturing teams, and publish them in the Eidonix plugin store.
+
+## Status
+
+- **Ready now:** the specification, the worker SDK (`sdk/pluginsdk`) and the
+  `cletus-plugin` tool, which creates a plugin, checks it the way the store
+  does and runs it under a test host. You can build and test a worker and
+  its chat tools today.
+- **Later releases:**
+  - screens;
+  - more host services (AI models, vision, speech, camera and microphone,
+    saved connections, a secret store);
+  - loading your development build into Cletus itself;
+  - store submissions.
+
+## What a plugin is
+
+A plugin is a Go program (the **worker**) that adds chat tools Cletus's AI
+can use, and services other plugins can call. Through the host it can:
+
+- open and save files the user chooses;
+- read and write the user's shared folders;
+- start background Cletus runs over the user's files;
+- connect to machines, databases and services the user sets up, or to
+  servers it names.
+
+## Start here
+
+If you work with a coding agent (Claude Code, Codex or similar), point it at
+this repository and tell it what you want to build. `AGENTS.md` holds the
+rules it must follow, and it reads the rest from there.
+
+If you work by hand, read in this order:
+
+1. `docs/specification.md`: the package, `plugin.json`, permissions, the
+   worker and services.
+2. `docs/host-api.md`: every host method.
+3. `docs/style-guide.md`: how Cletus plugins read and behave.
+4. `docs/patterns.md`: how to build common kinds of plugin.
+5. `docs/submission.md` and `docs/review-checklist.md`: how publishing will
+   work.
+
+## Tools
+
+Needs Go 1.24 or later.
+
+```sh
+go install git.eidonix.com/eidonix/cletus-plugins/sdk/cmd/cletus-plugin@latest
+
+cletus-plugin new acme.gauge-check                  # a working plugin from the template
+cd gauge-check
+cletus-plugin check                                 # the store's automated checks
+cletus-plugin run -files ./testdata tools           # list the chat tools
+cletus-plugin run -files ./testdata invoke gauge_check_hello '{"name":"Ada"}'
+```
+
+`run` starts your worker under a test host that answers host calls the way
+Cletus does, enforces your declared permissions, and prints every host call
+your worker makes.
+
+## Publishing
+
+Plugins reach users only through the Eidonix plugin store, and Cletus
+installs nothing else. You'll submit source code; Eidonix builds it, checks
+it, reviews it and signs it. See `docs/submission.md`.
+
+## Licence
+
+Apache License 2.0 (`LICENSE`). The names Cletus and Eidonix are not
+licensed.