Plugins — YAML composition, now with distribution
v1's thesis still holds: YAML files ARE plugins. A plugin is a fragment someone includes — no code, no registration, no plugin API. What changed is that v2 adds a distribution layer on top: bundles, install refs, a store, and ops verbs (ADR-0079). The plugin unit is still YAML; now it also ships.
The plugin is still a file
# plugins/notify/slack.yaml — a fragment
id: notify-slack
driver: shell
on: [notify.requested]
emits: [notify.done]
params:
cmd: 'curl -X POST -H "Content-type: application/json" --data "{\"text\":\"${event.payload.message}\"}" ${secret.SLACK_WEBHOOK_URL}'A campaign "installs" it with include: — see Include and snippet resolution. Install = drop a file; use = include:; version = git; override = deep-merge; remove = delete the include line.
The bundle is the shippable plugin
When a plugin must cross machines — a CI gate, a release pipeline, a shared fragment library — it becomes a bundle: a tamias.yaml manifest plus a payload of workflows, .node.yml, .driver.yml, .field.yml files.
tamias install git:9aia/peregrin//libraries/docs-deploy # → the tamias store
tamias list && tamias info docs-deploy
tamias deploy docs-deploy # materialize + unit- Install — fetch from fs/git/http/cf, unpack into tamias's install store (
~/.local/share/tamias/<name>@<version>/), record the resolved pin (commit sha orsha256:digest). Refs pin by git ref or content digest; the fetch cache makes warm installs free. - Compose — a manifest's
include:deep-merges base bundles under the local payload, same rules as file-level includes. - Instantiate —
tamias deployrunstamias-driver-peregrin'sdeployverb, which writes the operator's node config (the bundle'smain.yamlincluded,config:params merged, agithub-webhookingress node built fromprovider.ingress[]) into~/.config/peregrin/and the campaign-host dir — and rendersprovider.services[]as systemd units. The operator config is where secrets and watched repos bind — a bundle never shipsparams.repos/secret_envvalues.
The ref grammar, store layout, cache, and verbs are specified in Distribution.
Why not a real plugin system?
A plugin system adds registration, versioning, dependency resolution, loading order, namespace management. Bundles get versioning and distribution from git and tarballs — the same mechanisms the ecosystem already runs — while the plugin itself stays a YAML document the loader already understands. The ceremony stays out of the engine.
See also
- Distribution — refs, store, cache, verbs
- Include and snippet resolution — the file-level half
- Run the docs-deploy bundle — the install → deploy → hooks flow end to end