Plugin Authoring

---
name: plugin-authoring
description: "Create or change Cloudroom plugins and Plugin SDK extensions, including CLI commands, agent tools, providers, and UI surfaces."
---

# Author Cloudroom plugins

A Cloudroom plugin is a TypeScript package that can add server behavior, agent
capabilities, host-rendered UI, or a frontend bundle.

Use the current SDK types and repository source as the contract. This skill
routes to detailed references, but the installed Cloudroom version decides the exact
API.

## Implement and verify

Inspect the affected package and current SDK declarations to select backend,
frontend, or both. Build the plugin and verify the affected contracts and user
workflow. Install or reload when a live check is needed for the requested work.

Use room-cli plugin new <name> for a new plugin. The scaffold includes frontend files.
Remove `bb.app` and those files when the plugin is headless.

Every new public Plugin SDK surface starts with an experimental\_ prefix and an
entry in docs/api_to_audit.md. Add its Plugin Guide card and API inventory in
the same change.

## Read only the relevant reference

### Start, package, and release

- Read references/quickstart.md for package structure, manifest fields,
  scaffold output, build, install, and the first plugin.
- Read references/distribution.md for exact API lookup, Git or npm release,
  multi-plugin repositories, and custom marketplaces.

### Backend

- Read references/backend-foundation.md for the factory, logging, settings,
  storage, server information, and host access.
- Read references/backend-sdk.md for projects, environments, threads,
  interactions, provider models, browser sessions, and event history.
- Read references/backend-api-index.md to check every public backend, host,
  AI-service, and test export.
- Read references/backend-events.md for lifecycle events, environment providers,
  HTTP, RPC, realtime, background services, and schedules.
- Read references/backend-machines.md for machine providers, core project source
  setup, enrollment/bootstrap helpers, and server access.
- Read references/backend-cli-agents.md for CLI commands, input forms, agent
  tools, agent configuration, and helper AI services.
- Read references/providers.md only when the plugin registers an agent provider.
- Read references/provider-bridge-api-index.md to check every public provider
  bridge, bridge-test, and ACP export.
- Read references/backend-ui-lifecycle.md for host-rendered UI, status, cleanup,
  and reload behavior.

### Frontend

- Read references/frontend-registration.md for definePluginApp, thread header,
  sidebar replacement, providers, and top-level registration.
- Read references/frontend-api-index.md to check every public frontend
  runtime value and type export.
- Read references/frontend-core-slots.md for trusted content scripts, homepage,
  settings, navigation, thread panels, interactions, sidebar actions, and file
  openers.
- Read references/frontend-renderer-slots.md for source, diff, message,
  timeline, palette, and provider-icon renderers or actions.
- Read references/frontend-components.md for ThreadChat, provider controls,
  source and diff viewers, links, panels, and the new-thread composer.
- Read references/frontend-hooks-and-ui.md for hooks, composer customization,
  vendored components, runtime shims, styling, and crash isolation.

### Testing

- Read references/frontend-testing-api-index.md to check every frontend test
  runtime value and type export.
- Read references/testing.md before you add tests or run a live plugin loop.

## Contract rules

- Parse freeform input at the boundary and pass typed values internally.
- Declare only manifest fields and settings that the plugin implements.
- Keep secret settings on the server.
- Treat frontend parameters and persisted values as untrusted input.
- Return bounded CLI and agent-tool output.
- Document plugin commands, settings, and operating constraints in the plugin's
  own `skills/` directory. The core CLI skill owns generic plugin management,
  not individual plugin behavior.
- Dispose every service, schedule, listener, content script, and resource.
- Use SDK host components and navigation for host-owned behavior.
- Use vendored UI source for plugin-owned controls.
- Keep experimental names until the public API audit stabilizes them.
- Use current names. Compatibility aliases can warn and can expire after one
  release. Removed APIs can throw.
- Run room-cli plugin types when SDK declaration versions can drift.
- Run room-cli plugin build before install, release, or marketplace submission.

## Verification

Confirm the backend contract, frontend contract, manifest, generated bundle,
and live behavior that the change affects. Use focused tests for failure-prone
policy and lifecycle behavior.