Lab Conventions
Decisions for peteretelej/herdr-plugins, the lab’s plugin suite. These are settled; do not relitigate them per plugin. Where a convention exists in the ecosystem, this page says why we matched or diverged.
The suite
| Decision | Value | Rationale |
|---|---|---|
| Repo | peteretelej/herdr-plugins (public) | One repo card in the marketplace; monorepo is first-class there |
| Layout | Cargo workspace, members plugins/* | Shared dependency versions; herdr plugin install peteretelej/herdr-plugins/plugins/<name> |
| Plugin ids | peteretelej.<name> | Username-prefixed ids are the only style with zero collisions in the index (all 29 dup ids are flat names) |
| License | MIT | The ecosystem norm (~76% of indexed plugins). Herdr itself is Apache-2.0, which leaves the plugin license unconstrained |
| Language | Rust, one crate per plugin | Matches the lab’s strength and the strongest plugins in the market (agent-usage, file-viewer) |
| Deps | clap(derive), serde, serde_json, anyhow, toml, ureq (add rusqlite(bundled) only when reading SQLite) | The proven event/data stack; see plugin-archetypes.md |
| Manifest commands | Always sh -c exec "$HERDR_PLUGIN_ROOT/target/release/<bin>" ... | Ecosystem-standard launcher line; avoids relative-path resolution issues |
| min_herdr_version | Lowest version that actually works | Hard-fail asymmetry; see version-compat-doctrine.md |
| Docs | Per-plugin README; AGENTS.md at repo root once the suite grows | AI-collaboration docs are the norm in high-quality plugins (collie, file-viewer, zoetrope) |
Suite roadmap
| Plugin | Status | What it is |
|---|---|---|
peteretelej.tab-topic | Designed; skeleton in build-tab-topic.md | Rename agent panes to live topics, tabs after first agent pane |
peteretelej.notify | Designed; skeleton in build-notify-skeleton.md | blocked/done notifications with Telegram + webhook sinks, per-workspace routing |
peteretelej.cost-tokens | Idea | OpenCode token/cost sidebar via opencode.db (read herdr-agent-usage’s opencode.rs first) |
Prior art is reference, not veto
The market already has 15+ notify plugins. That is not a reason to skip peteretelej.notify; it is the spec. The existing ones mostly send low-context messages (“agent done”), lack per-workspace routing, and handle secrets via environment variables that do not survive herdr’s invocation environment. Read the closest existing plugin, list what it does poorly, and make those your requirements. The same held for pane-topic-sync before it existed: naming plugins were common, disciplined ones were not.
Checklist for each new plugin
- Collision check:
peteretelej.<name>and the display name against index.json (see maintenance.md). - Manifest with
sh -c execcommands, lowmin_herdr_version,platformsset. - State in
$HERDR_PLUGIN_STATE_DIR, config in$HERDR_PLUGIN_CONFIG_DIR, nothing inHERDR_PLUGIN_ROOT. - Event handlers idempotent, never subscribed to verbs they emit.
CHANGELOG.mdentry per version; version bumped inherdr-plugin.toml.- Tested via
plugin link+plugin action invoke+plugin log list(see debug-plugins.md). - Ship: public repo +
herdr-plugintopic, then verify indexing within ~30 minutes (see ship-to-marketplace.md).