The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
docs: update plugin authoring guide for managed resources (#6261)
Dotta8f45d1244735
diff --git a/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md b/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.mdindex 18b033e3a2..3bf7b00945 100644--- a/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md+++ b/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md@@ -2,7 +2,12 @@This is the short happy-path guide for developing a Paperclip plugin from a folder on your machine. You will scaffold a plugin, run it in watch mode, install it into a running Paperclip instance from an absolute local path, and edit code with the plugin worker reloading after each rebuild.-For the full alpha surface — manifest fields, capabilities, managed agents/projects/routines, UI slots, scoped API routes — see [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md).+For the full alpha surface — manifest fields, capabilities, managed agents/projects/routines/skills, UI slots, scoped API routes — see [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md).++If your plugin has background-like recurring work, model it as managed resources:+declare managed routines plus managed agents/projects/skills, then reconcile those+resources in worker actions. This gives operators visible work items, budgets,+pause controls, and consistent audits instead of hidden daemon behavior.## Prerequisites@@ -126,7 +131,8 @@ When you are done iterating locally, publish the package and reinstall the npm-p- **Restart cleanly:** `paperclipai plugin disable <key>` pauses the plugin without removing it. `paperclipai plugin enable <key>` brings it back. `paperclipai plugin uninstall <key>` removes the install record; add `--force` to also purge plugin state and settings.- **Browse examples:** `paperclipai plugin examples` lists the bundled example plugins that ship with the repo, each with a ready-to-run `paperclipai plugin install <path>` line.-- **Go deeper:** [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md) covers worker capabilities, managed agents/projects/routines, plugin database namespaces, scoped API routes, and the shared UI components in `@paperclipai/plugin-sdk/ui`. [`PLUGIN_SPEC.md`](./PLUGIN_SPEC.md) is the longer-form specification, including future ideas that are not yet implemented.+- **Go deeper:** [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md) covers worker capabilities, managed agents/projects/routines/skills, plugin database namespaces, scoped API routes, and the shared UI components in `@paperclipai/plugin-sdk/ui`. [`PLUGIN_SPEC.md`](./PLUGIN_SPEC.md) is the longer-form specification, including future ideas that are not yet implemented.+- **Routine-first automation:** If your plugin should produce periodic issue work, prefer managed routines and `ctx.routines.managed` reconciliation over custom process loops or unobserved cron code.## Troubleshootingdiff --git a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md b/doc/plugins/PLUGIN_AUTHORING_GUIDE.mdindex eb20163b17..dca3ec6246 100644--- a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md+++ b/doc/plugins/PLUGIN_AUTHORING_GUIDE.md@@ -13,6 +13,8 @@ It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec i- Worker-side host APIs are capability-gated.- Plugin UI is not sandboxed by manifest capabilities.- Plugin database migrations are restricted to a host-derived plugin namespace.+- Plugin-managed surfaces are first-class records (agents, projects, routines, and+ skills) rather than private plugin-only state.- Plugin-owned JSON API routes must be declared in the manifest and are mountedonly under `/api/plugins/:pluginId/api/*`.- The host provides a small shared React component kit through@@ -74,6 +76,7 @@ Worker:- issues, comments, namespaced `plugin:<pluginKey>` origins, blocker relations, checkout assertions, assignment wakeups, and orchestration summaries- agents, plugin-managed agents, and agent sessions- plugin-managed routines+- plugin-managed skills- goals- data/actions- streams@@ -134,11 +137,16 @@ paths; they always remain under `/api/plugins/:pluginId/api/*`.Plugins that provide durable Paperclip business objects should declare them inthe manifest and let the host create or relink the actual records per company.-Do this for plugin-owned agents, plugin-owned projects, and recurring automation.+Do this for plugin-owned agents, projects, routines, and skills.Do not hide long-lived work behind private plugin state when it should be visibleto the board, scoped to a company, audited, budgeted, and assigned like normalPaperclip work.+Content-oriented plugins, such as LLM Wiki-style ingestion or durable knowledge+systems, should use the same pattern: managed projects for operation issues,+managed agents plus managed skills for LLM work, and managed routines for+ingest, lint, refresh, or maintenance runs.+Use these surfaces:- Managed agents: declare top-level `agents[]` and require@@ -155,10 +163,14 @@ Use these surfaces:jobs that should create visible Paperclip issues. Prefer managed routines overplugin `jobs[]` for recurring business work; plugin jobs are for pluginruntime maintenance that does not need a board-visible task trail.+- Managed skills: declare top-level `skills[]` and require `skills.managed`.+ Use this for reusable plugin capabilities that should be surfaced to operators and+ synced into Paperclip managed agents.Managed resources are resolved by stable plugin keys, not hardcoded databaseids. In a worker action or data handler, call `ctx.agents.managed.reconcile()`,-`ctx.projects.managed.reconcile()`, and `ctx.routines.managed.reconcile()` for+`ctx.projects.managed.reconcile()`, `ctx.routines.managed.reconcile()`, and+`ctx.skills.managed.reconcile()` forthe current `companyId`. `reconcile()` creates the missing resource, relinks arecoverable binding, or returns the existing resource. `reset()` reapplies themanifest defaults when the operator wants to restore the plugin's suggested@@ -185,6 +197,7 @@ const manifest: PaperclipPluginManifestV1 = {"agents.managed","projects.managed","routines.managed",+ "skills.managed","instance.settings.register",],entrypoints: {@@ -231,6 +244,13 @@ const manifest: PaperclipPluginManifestV1 = {],},],+ skills: [+ {+ skillKey: "weekly-brief-skills",+ displayName: "Weekly Briefer",+ description: "Reusable skill for the managed research workflow.",+ },+ ],ui: {slots: [{@@ -261,8 +281,9 @@ export default definePlugin({const project = await ctx.projects.managed.reconcile("research", companyId);const agent = await ctx.agents.managed.reconcile("researcher", companyId);const routine = await ctx.routines.managed.reconcile("weekly-brief", companyId);+ const skill = await ctx.skills.managed.reconcile("weekly-brief-skills", companyId);- return { project, agent, routine };+ return { project, agent, routine, skill };});},});@@ -270,14 +291,18 @@ export default definePlugin({Authoring rules:-- Keep keys stable once published. Renaming `agentKey`, `projectKey`, or- `routineKey` creates a new managed resource from the host's point of view.+- Keep keys stable once published. Renaming `agentKey`, `projectKey`,+ `routineKey`, or `skillKey` creates a new managed resource from the host's+ point of view.- Use managed agents for plugin-provided labor. Use `ctx.agents.invoke()` or`ctx.agents.sessions` only after you have a real agent id, either selected bythe operator or resolved from `ctx.agents.managed`.- Use managed routines for recurring or externally triggered work that shouldproduce tasks. Schedule, webhook, and API triggers are visible routinetriggers, and each run has the normal Paperclip issue/audit trail.+- Use managed skills for reusable operator-visible capabilities that are shared+ by managed agents. Reconcile skill declarations by `skillKey` and keep the+ declared skill markdown and files in sync with agent behavior.- Use managed projects to keep plugin-generated work organized and to giveproject-scoped plugin UI a stable home. For filesystem access inside aproject, still resolve project workspaces through `ctx.projects`.@@ -300,6 +325,7 @@ Mount surfaces currently wired in the host include:- `settingsPage`- `dashboardWidget`- `sidebar`+- `routeSidebar`- `sidebarPanel`- `detailTab`- `taskDetailView`@@ -317,6 +343,10 @@ Paperclip-native control. The host owns the implementation, so plugins inheritthe board's current styling, ordering, recent selections, and dark-mode behaviorwithout importing `ui/src` internals.+Prefer shared components for common Paperclip UX patterns to reduce drift and+deprecation risk, especially for task/assignment flows and routine or sidebar-like+plugin screens.+Currently exposed components include:- `MarkdownBlock` and `MarkdownEditor` for rendered and editable markdown.diff --git a/doc/plugins/PLUGIN_SPEC.md b/doc/plugins/PLUGIN_SPEC.mdindex 31b9c9d0d7..c8080e56b9 100644--- a/doc/plugins/PLUGIN_SPEC.md+++ b/doc/plugins/PLUGIN_SPEC.md@@ -319,7 +319,10 @@ export interface PaperclipPluginManifestV1 {version: string;displayName: string;description: string;+ author: string;categories: Array<"connector" | "workspace" | "automation" | "ui">;+ minimumHostVersion?: string;+ /** @deprecated Use `minimumHostVersion` instead. Retained for backwards compatibility. */minimumPaperclipVersion?: string;capabilities: string[];entrypoints: {@@ -335,9 +338,33 @@ export interface PaperclipPluginManifestV1 {description: string;parametersSchema: JsonSchema;}>;+ database?: PluginDatabaseDeclaration;+ apiRoutes?: PluginApiRouteDeclaration[];+ environmentDrivers?: PluginEnvironmentDriverDeclaration[];+ agents?: PluginManagedAgentDeclaration[];+ projects?: PluginManagedProjectDeclaration[];+ routines?: PluginManagedRoutineDeclaration[];+ skills?: PluginManagedSkillDeclaration[];+ localFolders?: PluginLocalFolderDeclaration[];+ /** Legacy top-level launcher declarations. Prefer `ui.launchers` for new manifests. */+ launchers?: PluginLauncherDeclaration[];ui?: {+ launchers?: PluginLauncherDeclaration[];slots: Array<{- type: "page" | "detailTab" | "dashboardWidget" | "sidebar" | "settingsPage";+ type: "page"+ | "detailTab"+ | "taskDetailView"+ | "dashboardWidget"+ | "sidebar"+ | "routeSidebar"+ | "sidebarPanel"+ | "projectSidebarItem"+ | "globalToolbarButton"+ | "toolbarButton"+ | "contextMenuItem"+ | "commentAnnotation"+ | "commentContextMenuItem"+ | "settingsPage";id: string;displayName: string;/** Which export name in the UI bundle provides this component */@@ -354,10 +381,17 @@ Rules:- `id` must be globally unique- `id` should normally equal the npm package name- `apiVersion` must match the host-supported plugin API version+- `minimumHostVersion` is preferred, with `minimumPaperclipVersion` retained for+ backwards compatibility- `capabilities` must be static and install-time visible- config schema must be JSON Schema compatible- `entrypoints.ui` points to the directory containing the built UI bundle- `ui.slots` declares which extension slots the plugin fills, so the host knows what to mount without loading the bundle eagerly; each slot references an `exportName` from the UI bundle+- declare managed declarations with the matching `*.managed` capability:+ - `agents` → `agents.managed`+ - `projects` → `projects.managed`+ - `routines` → `routines.managed`+ - `skills` → `skills.managed`## 11. Agent Tools@@ -631,6 +665,22 @@ Plugins that need filesystem, git, terminal, or process operations handle thoseTrusted orchestration plugins can create and update Paperclip issues through `ctx.issues` instead of importing server internals. The public issue contract includes parent/project/goal links, board or agent assignees, blocker IDs, labels, billing code, request depth, execution workspace inheritance, and plugin origin metadata.+Plugins that perform durable work should declare managed Paperclip resources rather than using private plugin state:++- `agents` + `ctx.agents.managed.*` for named, invokable operators (`agents.managed` required)+- `projects` + `ctx.projects.managed.*` for stable, scoped issue/workspace ownership (`projects.managed` required)+- `routines` + `ctx.routines.managed.*` for schedule/webhook/manual execution with issue trails (`routines.managed` required)+- `skills` + `ctx.skills.managed.*` for reusable agent capabilities (`skills.managed` required)++The LLM Wiki plugin is the current reference for this pattern: it declares managed+agents, projects, routines, and skills in manifest, reconciles them per company,+and uses managed routines for periodic wiki maintenance and ingest operations.+Content-oriented plugins should follow the same model instead of running+unmanaged background loops: make the LLM-facing worker an operator-visible+managed agent, attach reusable prompt/tool guidance as managed skills, keep+operation issues in a managed project, and drive recurring work through managed+routines.+Origin rules:- Built-in core issues keep built-in origins such as `manual` and `routine_execution`.@@ -746,20 +796,38 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr- `activity.read`- `costs.read`- `issues.orchestration.read`+- `database.namespace.read`### Data Write- `issues.create`- `issues.update`- `issue.comments.create`+- `issue.interactions.create`- `issue.documents.write`- `issue.relations.write`- `issues.checkout`- `issues.wakeup`-- `assets.write`-- `assets.read`- `activity.log.write`- `metrics.write`+- `telemetry.track`+- `assets.read`+- `assets.write`+- `database.namespace.migrate`+- `database.namespace.write`+- `goals.create`+- `goals.update`+- `projects.managed`+- `routines.managed`+- `skills.managed`+- `agents.managed`+- `agents.pause`+- `agents.resume`+- `agents.invoke`+- `agent.sessions.create`+- `agent.sessions.list`+- `agent.sessions.send`+- `agent.sessions.close`### Plugin State@@ -772,8 +840,10 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr- `events.emit`- `jobs.schedule`- `webhooks.receive`+- `local.folders`- `http.outbound`- `secrets.read-ref`+- `environment.drivers.register`### Agent Tools@@ -786,6 +856,7 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr- `ui.page.register`- `ui.detailTab.register`- `ui.dashboardWidget.register`+- `ui.commentAnnotation.register`- `ui.action.register`## 15.2 Forbidden Capabilities@@ -894,6 +965,7 @@ Job rules:3. The host prevents overlapping execution of the same plugin/job combination unless explicitly allowed later.4. Every job run is recorded in Postgres.5. Failed jobs are retryable.+6. For recurring business workflows that should create visible Paperclip work, prefer managed routines and managed resources over jobs. Jobs remain useful for private plugin-runtime maintenance tasks.## 18. Webhooks