herdr-plugins

name	herdr-plugins
description	Create, revise, review, test, package, or prepare publication of executable Herdr plugins, including herdr-plugin.toml manifests, actions, startup and event hooks, terminal panes, link handlers, runtime context, storage, and marketplace readiness.
license	MIT
compatibility	Requires a Herdr version that supports plugins for live validation; most authoring and isolated tests can run without a Herdr server.

Authoring Herdr Plugins

Treat a Herdr plugin as executable code plus a declarative herdr-plugin.toml, not as an SDK integration. Prefer the installed Herdr CLI through HERDR_BIN_PATH over raw socket code unless direct request control or long-lived subscriptions are required.

Choose the Mode

• Use Build to create, revise, or fix a plugin and its local tests.
• Use Review for read-only findings unless the user also requests changes.
• Use Prepare Distribution to check a releasable repository or artifact without publishing it.
• Use Publish only with authorization for the exact repository, revision or release, and marketplace changes.

Establish the Contract

1. Read the request, repository rules, existing manifest, implementation, tests, and setup documentation before choosing a structure.
2. Check the installed binary with herdr --version and version-sensitive command syntax with herdr plugin --help and narrower help commands when available.
3. Consult the current plugin documentation for manifest behavior and the CLI reference for commands the plugin will call.
4. Read the v1 reference when selecting manifest entrypoints, environment variables, storage, pane behavior, or validation checks.
5. Define the workflow, invocation context, supported platforms, dependencies, configuration, durable state, failure behavior, and oldest compatible Herdr version.
6. Use one or more manifest actions for discrete workflows, events for reactions, startup hooks for one-shot restoration, panes for terminal interfaces, and link handlers only to route matching URLs to declared actions.
7. Keep runtime registration and native non-terminal UI out of a v1 design because v1 requires manifest-declared actions, hooks, panes, and link handlers.

Review

1. Trace each manifest entrypoint into its command, Herdr calls, context handling, storage, side effects, tests, and setup documentation.
2. Check manifest validity, version and platform claims, argv portability, trust boundaries, secret handling, idempotence, error propagation, and cleanup.
3. Lead with actionable findings ordered by impact, and give each finding a location, evidence, consequence, and focused fix.
4. Keep assumptions, unavailable platform checks, and documentation drift separate from confirmed defects.
5. Do not edit, link, enable, invoke, install, publish, or otherwise execute plugin code during a review unless the user explicitly expands the request.

Build or Revise

1. Keep herdr-plugin.toml at the plugin root and declare the required id, name, version, and min_herdr_version fields.
2. Declare top-level platforms unless an intentional local-only experiment accepts the link warning.
3. Express every command as an argv array and put shell expansion or pipelines inside an explicitly launched shell only when they are actually needed.
4. Resolve Herdr as HERDR_BIN_PATH with herdr as a development fallback, and propagate stdout, stderr, and nonzero status accurately.
5. Parse HERDR_PLUGIN_CONTEXT_JSON defensively and handle absent optional workspace, tab, pane, worktree, agent, selection, and link fields.
6. Store user-editable settings and secrets under HERDR_PLUGIN_CONFIG_DIR, durable runtime state under HERDR_PLUGIN_STATE_DIR, and neither under HERDR_PLUGIN_ROOT.
7. Make startup hooks idempotent, bounded, and one-shot because they are not supervised daemons and may run again after live handoff.
8. Validate external input, quote or encode values at process boundaries, avoid logging secrets or full sensitive context, and give failures actionable stderr messages.
9. Document required tools, configuration, supported platforms, entrypoints, state ownership, and cleanup without claiming Herdr installs dependencies or sandboxes the plugin.
10. Add only implementation-language files and tests that serve the selected workflow.

Verify Safely

1. Review the manifest and every build or runtime command before executing plugin code.
2. Run implementation-formatting, lint, unit, and integration checks required by the repository.
3. Test commands in isolation with temporary config and state directories, representative context JSON, and a stub HERDR_BIN_PATH that records argv and returns controlled JSON or failures.
4. Cover missing optional context, malformed input, dependency absence, Herdr CLI failure, nonzero exit propagation, repeat startup execution, and supported platform branches that can be exercised locally.
5. Do not install or run untrusted third-party plugin code merely to review it.
6. Treat plugin link, enable or disable, action invocation, pane opening, install, uninstall, and unlink as changes to user-global Herdr state, and obtain authorization for the exact live operations before running them.
7. For an approved local live test, prefer herdr plugin link <path> --disabled, inspect herdr plugin list --plugin <id> --json for warnings, then enable and invoke only the agreed entrypoints.
8. Inspect herdr plugin log list --plugin <id> after runtime checks and verify observable effects rather than relying only on exit status.
9. Close test panes, disable the plugin when needed, and use herdr plugin unlink <id> after an approved temporary link while leaving source files intact.
10. Report checks that were skipped because Herdr, a server, a platform, a dependency, or live-state authorization was unavailable.

Prepare Distribution When Requested

1. Confirm that generated artifacts needed at runtime are produced by declared build commands and that local linking instructions tell authors to build manually.
2. Recheck the manifest after the production build because an install aborts if a build changes herdr-plugin.toml after preview.
3. Verify from a clean checkout or equivalent artifact that commands, relative paths, dependency instructions, configuration setup, and platform declarations are complete.
4. Treat repository publication, releases, GitHub topic changes, and marketplace submission as external writes requiring exact authorization.
5. For an authorized marketplace release, publish a public GitHub repository containing herdr-plugin.toml, add the herdr-plugin topic, and verify installation using the intended owner/repo[/subdir] shorthand and pinned revision when reproducibility matters.

Stop when the requested plugin behavior is implemented, isolated checks pass, every authorized live check is verified and cleaned up, and unavailable checks or remaining compatibility limits are explicit.