Community plugins
What you'll find here
Safe metadata and review boundaries for community plugins — descriptors, probation, capabilities, receipts, reference integrations, and security boundaries. Treat all community plugins as untrusted until descriptor, provenance, review state, grants, and receipts have been inspected.
Post-MVP scope.
Broad plugin marketplace and community ecosystem workflows are post-MVP scope. This guide describes safe metadata and review boundaries — it does not imply a supported public marketplace or runtime authority. See Post-MVP Scope.
Authoring
A community plugin should include:
Governed plugin descriptor
Versioned entrypoints
Declared capability needs
Compatibility metadata
Docs and security notes
Provenance
For copied, generated, or external material.
Examples or fixtures
That can be checked locally.
Use craik.plugin_descriptor
for plugin identity, entrypoints, declared capabilities, docs,
security metadata, and compatibility. Descriptors declare needs;
they do not grant runtime authority.
Descriptors must declare a trust boundary and semantic-version-like plugin and Craik compatibility versions. Grant-required capabilities must name concrete operations and targets so review can compare the descriptor request to the eventual grant.
Review and probation
New or changed community plugins should start in probation. Use
craik.plugin_probation to
record review criteria, compatibility checks, evidence, receipts, and
promotion / rejection / expiration decisions.
Preserve denials.
Promotion requires passing required criteria and compatibility checks. Rejected and expired plugins must preserve the decision rationale so later agents don't repeat the same review. Decisions require evidence, and criteria marked as passed require evidence links before a plugin can be promoted.
Capabilities
Plugin capability grants must be explicit and least-privilege. Use
craik.plugin_capability_grant
to scope authority to a plugin descriptor, target paths, operations,
approval requirements, and expiry.
Authority comes from grants, not descriptors.
Do not infer authority from descriptor metadata, package names, docs, or prior successful runs. Capability grants and policy envelopes decide what a plugin may do in the current run. Grants must name explicit operations and scoped targets. Denied, expired, and approval-required grants must not be treated as ambient authority; runtime callers should check the current operation and expiry before execution.
Receipts
Every meaningful plugin action leaves a redacted receipt. Use
craik.plugin_receipt to link
plugin actions to descriptors, capability grants, evidence, handoffs,
trust boundaries, and results.
Receipts summarize passed, failed, and denied actions without storing raw secrets or unredacted plugin output. Receipt result metadata must not contradict the receipt redaction flag, and probation links should be preserved while a plugin is under review.
Adapters
Adapter packages are distribution metadata for runner integrations,
not authority grants. Use
craik.adapter_package to record
adapter entrypoints, capability surfaces, supported runner modes,
Python versions, platforms, linked plugin descriptors, docs, and
provenance. Adapter compatibility should be treated as a hard
execution boundary.
Reference paths
Use craik.reference_integration
to publish safe, reproducible examples that link docs, fixtures,
checks, receipts, and compatibility notes. Reference integrations
are examples, not trust grants.
Security boundaries
No secrets in any plugin artifact.
Do not include secrets in plugin docs, fixtures, descriptors, receipts, or examples. Persist only redacted outputs and evidence-linked summaries.