Plugin Cookbook

Practical recipes for adding common plugin types to Clawback.

Audience: Contributors who want concrete examples, not just architecture theory.

What This Guide Is For

Use this guide when you want to add one of the common extension types:

• a new connection provider
• a new ingress adapter
• a new action executor
• a new worker pack

This is a cookbook, not a full reference.

For concepts, read:

• Writing Plugins
• Plugins & Providers

Before You Start

Clawback plugins are currently:

• typed
• first-party
• monorepo-based

That means the usual flow is:

1. add or update a manifest in packages/plugin-manifests
2. wire runtime behavior in services/control-plane if needed
3. verify shared contracts still hold
4. check the console picks it up correctly

If you are adding a worker pack, remember the two-layer rule:

• manifest = metadata
• runtime pack = execution logic

Recipe 1: Add A "Coming Soon" Connection Provider

This is the safest first contribution.

Goal

Make a provider show up in Connections and Setup with the right labels and badges, without making it actually usable yet.

Files to touch

• packages/plugin-manifests/src/connection-providers/<provider>.ts
• packages/plugin-manifests/src/index.ts

Example shape

Use the existing providers as examples:

• gmail-read-only.ts
• drive.ts

Minimal checklist

• choose a stable manifest id
• choose the correct provider
• set stability to experimental if it is not ready
• add category and priority
• define accessModes
• define capabilities
• define setupSteps
• export it from the package index

Result

If you did it correctly:

• it appears in the registry response
• it appears on Connections
• it is grouped under the right category
• it renders with the generic fallback card
• it shows Coming soon

Good use case

Add a future notion or hubspot provider as a visible placeholder before the runtime integration exists.

Recipe 2: Add A Real Connection Provider With Custom Setup UI

Use this when the provider needs a first-party operator flow.

Goal

Add a provider that:

• appears in the generic provider list automatically
• uses a custom panel when the operator opens it

Files to touch

• manifest:
  • packages/plugin-manifests/src/connection-providers/<provider>.ts
• console registry:
  • apps/console/app/workspace/_lib/provider-panel-registry.ts
  • apps/console/app/workspace/connections/panel-registrations.ts
• custom panel:
  • apps/console/app/workspace/connections/<provider>-onboarding-card.tsx

Existing examples

• gmail-onboarding-card.tsx
• smtp-onboarding-card.tsx
• panel-registrations.ts

Important rule

Do not add UI-specific fields to the manifest.

The console panel registry is keyed by the existing manifest id.

Minimal checklist

• add the provider manifest
• export it
• add the custom panel component
• register the panel by manifest id
• pass any required panel props through the connections page plumbing
• verify the provider still renders through the generic shell entry point

Result

The provider now:

• appears in Connections automatically from registry data
• mounts a custom panel when needed
• still uses generic metadata for grouping, ordering, and high-level framing

Recipe 3: Add An Ingress Adapter

Use this when an external system needs to send events into Clawback.

Goal

Normalize an inbound event into Clawback’s existing route/source-event model.

Files to touch

• manifest:
  • packages/plugin-manifests/src/ingress-adapters/<adapter>.ts
• runtime ingress code:
  • services/control-plane/src/integrations/...
• tests:
  • provider parsing
  • auth
  • idempotency

Existing examples

• postmark-inbound.ts
• gmail-watch.ts

Minimal checklist

• define the adapter manifest
• define authentication type
• define compatible route kinds
• wire or reuse the ingress endpoint
• normalize the inbound payload into existing internal event shapes
• add tests for good/bad payloads and auth failure

Anti-pattern

Do not invent a new inbox or work-item lifecycle inside the adapter. The adapter should translate and normalize, not redefine core product semantics.

Recipe 4: Add An Action Executor

Use this when Clawback needs to carry out an approved action.

Goal

Add a new outbound action path without breaking approval truth.

Files to touch

• manifest:
  • packages/plugin-manifests/src/action-executors/<executor>.ts
• runtime behavior:
  • reviewed-send or other executor logic in services/control-plane
• tests:
  • success
  • failure
  • retry
  • truthful status transitions

Existing example

• smtp-send.ts

Minimal checklist

• define the manifest
• wire destination provider compatibility
• preserve separation between:
  • review approved
  • execution requested
  • execution completed
  • execution failed
• test retry behavior

Anti-pattern

Do not mark work as sent before the external provider confirms success.

Recipe 5: Add A Worker Pack

This is the most common extension pattern.

Goal

Add a new installable worker template that appears in the UI and installs correctly.

Files to touch

• manifest:
  • packages/plugin-manifests/src/worker-packs/<pack>.ts
• runtime pack:
  • services/control-plane/src/worker-packs/<pack>-pack.ts
• runtime pack exports:
  • services/control-plane/src/worker-packs/index.ts
• app assembly:
  • services/control-plane/src/app.ts

Existing examples

• follow-up manifest
• proposal manifest
• follow-up runtime pack
• proposal runtime pack

Minimal checklist

• create the manifest
• create the runtime pack
• keep workerPackId aligned with runtime id
• export the runtime pack
• add it to the app’s available worker packs
• confirm the install dialog shows it
• confirm manifest/runtime alignment tests pass

The fastest sanity check

After wiring it:

1. open Workers
2. open the install dialog
3. confirm the pack appears with the right labels
4. install it
5. confirm the created worker has the right routes and action capabilities

Recipe 6: Add Setup Guidance For A Plugin

Use this when the plugin is already real, but operators need clearer setup guidance.

Goal

Improve setup without changing runtime semantics.

Files to touch

• the plugin manifest’s setupSteps
• optionally the setup evaluator registry if the step should become automatically checkable

Existing evaluator code

• evaluator-registrations.ts

Important rule

Setup steps are matched by:

• pluginId
• stepId

Not by array position.

Minimal checklist

• add or refine setupSteps in the manifest
• if a step should be computed automatically, register an evaluator for ${pluginId}:${stepId}
• verify the step shows up in /workspace/setup

Recipe 7: Verify "Add Manifest -> It Shows Up"

Use this when you want to prove the plugin-native contract still holds.

Existing verification

• console-native-contract.test.ts

What to check

• the manifest passes shared contract validation
• it flows through the registry response
• category and priority are preserved
• generic fallback behavior still works for a provider without a custom panel

Good extension

Add a fake experimental provider manifest in a test and verify it would show up correctly in the grouped provider list.

Common Decision Guide

If you are unsure what to build, use this quick map:

Common Mistakes

Mistake 1: Adding only the manifest

If the feature needs runtime behavior, the manifest alone is not enough.

Mistake 2: Putting runtime logic into the manifest

Keep prompts, install side effects, and execution logic out of shared manifests.

Mistake 3: Reintroducing hardcoded console branching

Use:

• registry metadata
• provider panel registry
• setup evaluator registry

Do not fall back to page-specific hardcoded logic unless absolutely necessary.

Mistake 4: Changing core lifecycle semantics during plugin work

Plugins should not silently redefine:

• work item states
• review states
• inbox rules
• activity meaning

Suggested First Contributions

If you want something low-risk:

• add a new experimental provider manifest
• improve setup step copy on an existing manifest
• add alignment or verification tests
• add grouping/order metadata for an existing provider

If you want something medium-risk:

• add a new worker pack manifest and runtime pack
• add a provider with a custom panel

If you want something high-risk:

• change reviewed execution behavior
• change Gmail/OAuth trust semantics
• change core lifecycle or product object contracts

Those should be reviewed more tightly.

Starter Templates

Copy-paste starter files live in docs/guides/plugin-templates/. Each one is a minimal, commented TypeScript file ready to rename and customize.

How to use them

1. Copy the relevant .example file(s) into the correct source directory
2. Rename to .ts and update all placeholder values
3. Export from packages/plugin-manifests/src/index.ts
4. For worker packs: create both the manifest and the runtime pack, then add the runtime to the alignment test
5. Run the test suite to confirm everything links up

Related Docs

• Writing Plugins
• Plugins & Providers
• API Reference