Plugin Ideas From OpenCode

Status: design report, not a V1 commitment

Stacy V1 explicitly excludes a plugin framework in doc/SPEC-implementation.md, but the long-horizon spec says the architecture should leave room for extensions. This report studies the opencode plugin system and translates the useful patterns into a Stacy-shaped design.

Assumption for this document: Stacy is a single-tenant operator-controlled instance. Plugin installation should therefore be global across the instance. "Companies" are still first-class Stacy objects, but they are organizational records, not tenant-isolation boundaries for plugin trust or installation.

Executive Summary

opencode has a real plugin system already. It is intentionally low-friction:

plugins are plain JS/TS modules
they load from local directories and npm packages
they can hook many runtime events
they can add custom tools
they can extend provider auth flows
they run in-process and can mutate runtime behavior directly

That model works well for a local coding tool. It should not be copied literally into Stacy.

The main conclusion is:

Stacy should copy opencode's typed SDK, deterministic loading, low authoring friction, and clear extension surfaces.
Stacy should not copy opencode's trust model, project-local plugin loading, "override by name collision" behavior, or arbitrary in-process mutation hooks for core business logic.
Stacy should use multiple extension classes instead of one generic plugin bag:
- trusted in-process modules for low-level platform concerns like agent adapters, storage providers, secret providers, and possibly run-log backends
- out-of-process plugins for most third-party integrations like Linear, GitHub Issues, Grafana, Stripe, and schedulers
- plugin-contributed agent tools (namespaced, not override-by-collision)
- plugin-shipped React UI loaded into host extension slots via a typed bridge
- a typed event bus with server-side filtering and plugin-to-plugin events, plus scheduled jobs for automation

If Stacy does this well, the examples you listed become straightforward:

file browser / terminal / git workflow / child process tracking become workspace plugins that resolve paths from the host and handle OS operations directly
Linear / GitHub / Grafana / Stripe become connector plugins
future knowledge base and accounting features can also fit the same model

Sources Examined

I cloned anomalyco/opencode and reviewed commit:

a965a062595403a8e0083e85770315d5dc9628ab

Primary files reviewed:

https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/plugin/src/index.ts
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/plugin/src/tool.ts
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/plugin/index.ts
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/config/config.ts
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/tool/registry.ts
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/opencode/src/provider/auth.ts
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/plugins.mdx
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/custom-tools.mdx
https://github.com/anomalyco/opencode/blob/a965a062595403a8e0083e85770315d5dc9628ab/packages/web/src/content/docs/ecosystem.mdx

Relevant Stacy files reviewed for current extension seams:

What OpenCode Actually Implements

1. Plugin authoring API

opencode exposes a small package, @opencode-ai/plugin, with a typed Plugin function and a typed tool() helper.

Core shape:

a plugin is an async function that receives a context object
the plugin returns a Hooks object
hooks are optional
plugins can also contribute tools and auth providers

The plugin init context includes:

an SDK client
current project info
current directory
current git worktree
server URL
Bun shell access

That is important: opencode gives plugins rich runtime power immediately, not a narrow capability API.

2. Hook model

The hook set is broad. It includes:

event subscription
config-time hook
message hooks
model parameter/header hooks
permission decision hooks
shell env injection
tool execution before/after hooks
tool definition mutation
compaction prompt customization
text completion transforms

The implementation pattern is very simple:

core code constructs an output object
each matching plugin hook runs sequentially
hooks mutate the output
final mutated output is used by core

This is elegant and easy to extend.

It is also extremely powerful. A plugin can change auth headers, model params, permission answers, tool inputs, tool descriptions, and shell environment.

3. Plugin discovery and load order

opencode supports two plugin sources:

local files
npm packages

Local directories:

~/.config/opencode/plugins/
.opencode/plugins/

Npm plugins:

listed in config under plugin: []

Load order is deterministic and documented:

global config
project config
global plugin directory
project plugin directory

Important details:

config arrays are concatenated rather than replaced
duplicate plugin names are deduplicated with higher-precedence entries winning
internal first-party plugins and default plugins are also loaded through the plugin pipeline

This gives opencode a real precedence model rather than "whatever loaded last by accident."

4. Dependency handling

For local config/plugin directories, opencode will:

ensure a package.json exists
inject @opencode-ai/plugin
run bun install

That lets local plugins and local custom tools import dependencies.

This is excellent for local developer ergonomics.

It is not a safe default for an operator-controlled control plane server.

5. Error handling

Plugin load failures do not hard-crash the runtime by default.

Instead, opencode:

logs the error
publishes a session error event
continues loading other plugins

That is a good operational pattern. One bad plugin should not brick the entire product unless the operator has explicitly configured it as required.

6. Tools are a first-class extension point

opencode has two ways to add tools:

export tools directly from a plugin via hook.tool
define local files in .opencode/tools/ or global tools directories

The tool API is strong:

tools have descriptions
tools have Zod schemas
tool execution gets context like session ID, message ID, directory, and worktree
tools are merged into the same registry as built-in tools
tool definitions themselves can be mutated by a tool.definition hook

The most aggressive part of the design:

custom tools can override built-in tools by name

That is very powerful for a local coding assistant. It is too dangerous for Stacy core actions.

However, the concept of plugins contributing agent-usable tools is very valuable for Stacy — as long as plugin tools are namespaced (cannot shadow core tools) and capability-gated.

7. Auth is also a plugin surface

opencode allows plugins to register auth methods for providers.

A plugin can contribute:

auth method metadata
prompt flows
OAuth flows
API key flows
request loaders that adapt provider behavior after auth succeeds

This is a strong pattern worth copying. Integrations often need custom auth UX and token handling.

8. Ecosystem evidence

The ecosystem page is the best proof that the model is working in practice. Community plugins already cover:

sandbox/workspace systems
auth providers
session headers / telemetry
memory/context features
scheduling
notifications
worktree helpers
background agents
monitoring

That validates the main thesis: a simple typed plugin API can create real ecosystem velocity.

What OpenCode Gets Right

1. Separate plugin SDK from host runtime

This is one of the best parts of the design.

plugin authors code against a clean public package
host internals can evolve behind the loader
runtime code and plugin code have a clean contract boundary

Stacy should absolutely do this.

2. Deterministic loading and precedence

opencode is explicit about:

where plugins come from
how config merges
what order wins

Stacy should copy this discipline.

3. Low-ceremony authoring

A plugin author does not have to learn a giant framework.

export async function
return hooks
optionally export tools

That simplicity matters.

4. Typed tool definitions

The tool() helper is excellent:

typed
schema-based
easy to document
easy for runtime validation

Stacy should adopt this style for plugin actions, automations, and UI schemas.

5. Built-in features and plugins use similar shapes

opencode uses the same hook system for internal and external plugin-style behavior in several places. That reduces special cases.

Stacy can benefit from that with adapters, secret backends, storage providers, and connector modules.

6. Incremental extension, not giant abstraction upfront

opencode did not design a giant marketplace platform first. It added concrete extension points that real features needed.

That is the correct mindset for Stacy too.

What Stacy Should Not Copy Directly

1. In-process arbitrary plugin code as the default

opencode is basically a local agent runtime, so unsandboxed plugin execution is acceptable for its audience.

Stacy is a control plane for an operator-managed instance with company objects. The risk profile is different:

secrets matter
approval gates matter
budgets matter
mutating actions require auditability

Default third-party plugins should not run with unrestricted in-process access to server memory, DB handles, and secrets.

2. Project-local plugin loading

opencode has project-local plugin folders because the tool is centered around a codebase.

Stacy is not project-scoped. It is instance-scoped. The comparable unit is:

instance-installed plugin package

Stacy should not auto-load arbitrary code from a workspace repo like .stacy/plugins or project directories.

3. Arbitrary mutation hooks on core business decisions

Hooks like:

permission.ask
tool.execute.before
chat.headers
shell.env

make sense in opencode.

For Stacy, equivalent hooks into:

approval decisions
issue checkout semantics
activity log behavior
budget enforcement

would be a mistake.

Core invariants should stay in core code, not become hook-rewritable.

4. Override-by-name collision

Allowing a plugin to replace a built-in tool by name is useful in a local agent product.

Stacy should not allow plugins to silently replace:

core routes
core mutating actions
auth behaviors
permission evaluators
budget logic
audit logic

Extension should be additive or explicitly delegated, never accidental shadowing.

5. Auto-install and execute from user config

opencode's "install dependencies at startup" flow is ergonomic. For Stacy it would be risky because it combines:

package installation
code loading
execution

inside the control-plane server startup path.

Stacy should require an explicit operator install step.

Why Stacy Needs A Different Shape

The products are solving different problems.

Topic	OpenCode	Stacy
Primary unit	local project/worktree	single-tenant operator instance with company objects
Trust assumption	local power user on own machine	operator managing one trusted Stacy instance
Failure blast radius	local session/runtime	entire company control plane
Extension style	mutate runtime behavior freely	preserve governance and auditability
UI model	local app can load local behavior	board UI must stay coherent and safe
Security model	host-trusted local plugins	needs capability boundaries and auditability

That means Stacy should borrow the good ideas from opencode but use a stricter architecture.

Stacy Already Has Useful Pre-Plugin Seams

Stacy has several extension-like seams already:

server adapter registry: server/src/adapters/registry.ts
UI adapter registry: ui/src/adapters/registry.ts
storage provider registry: server/src/storage/provider-registry.ts
secret provider registry: server/src/secrets/provider-registry.ts
pluggable run-log store seam: server/src/services/run-log-store.ts
activity log and live event emission: server/src/services/activity-log.ts

This is good news. Stacy does not need to invent extensibility from scratch. It needs to unify and harden existing seams.

Recommended Stacy Plugin Model

1. Use multiple extension classes

Do not create one giant hooks object for everything.

Use distinct plugin classes with different trust models.

Extension class	Examples	Runtime model	Trust level	Why
Platform module	agent adapters, storage providers, secret providers, run-log backends	in-process	highly trusted	tight integration, performance, low-level APIs
Connector plugin	Linear, GitHub Issues, Grafana, Stripe	out-of-process worker or sidecar	medium	external sync, safer isolation, clearer failure boundary
Workspace plugin	file browser, terminal, git workflow, child process/server tracking	out-of-process, direct OS access	medium	resolves workspace paths from host, owns filesystem/git/PTY/process logic directly
UI contribution	dashboard widgets, settings forms, company panels	plugin-shipped React bundles in host extension slots via bridge	medium	plugins own their rendering; host controls slot placement and bridge access
Automation plugin	alerts, schedulers, sync jobs, webhook processors	out-of-process	medium	event-driven automation is a natural plugin fit

This split is the most important design recommendation in this report.

2. Keep low-level modules separate from third-party plugins

Stacy already has this pattern implicitly:

adapters are one thing
storage providers are another
secret providers are another

Keep that separation.

I would formalize it like this:

module means trusted code loaded by the host for low-level runtime services
plugin means integration code that talks to Stacy through a typed plugin protocol and capability model

This avoids trying to force Stripe, a PTY terminal, and a new agent adapter into the same abstraction.

3. Prefer event-driven extensions over core-logic mutation

For third-party plugins, the primary API should be:

subscribe to typed domain events (with optional server-side filtering)
emit plugin-namespaced events for cross-plugin communication
read instance state, including company-bound business records when relevant
register webhooks
run scheduled jobs
contribute tools that agents can use during runs
write plugin-owned state
add additive UI surfaces
invoke explicit Stacy actions through the API

Do not make third-party plugins responsible for:

deciding whether an approval passes
intercepting issue checkout semantics
rewriting activity log behavior
overriding budget hard-stops

Those are core invariants.

4. Plugins ship their own UI

Plugins ship their own React UI as a bundled module inside dist/ui/. The host loads plugin components into designated extension slots (pages, tabs, widgets, sidebar entries) and provides a bridge for the plugin frontend to talk to its own worker backend and to access host context.

How it works:

The plugin's UI exports named components for each slot it fills (e.g. DashboardWidget, IssueDetailTab, SettingsPage).
The host mounts the plugin component into the correct slot, passing a bridge object with hooks like usePluginData(key, params) and usePluginAction(key).
The plugin component fetches data from its own worker via the bridge and renders it however it wants.
The host enforces capability gates through the bridge — if the worker doesn't have a capability, the bridge rejects the call.

What the host controls: where plugin components appear, the bridge API, capability enforcement, and shared UI primitives (@arpanstacy/stacy-plugin-sdk/ui) with design tokens and common components.

What the plugin controls: how to render its data, what data to fetch, what actions to expose, and whether to use the host's shared components or build entirely custom UI.

First version extension slots:

dashboard widgets
settings pages
detail-page tabs (project, issue, agent, goal, run)
sidebar entries
company-context plugin pages

The host SDK ships shared components (MetricCard, DataTable, StatusBadge, LogView, etc.) for visual consistency, but these are optional.

Later, if untrusted third-party plugins become common, the host can move to iframe-based isolation without changing the plugin's source code (the bridge API stays the same).

5. Make installation global and keep mappings/config separate

opencode is mostly user-level local config. Stacy should treat plugin installation as a global instance-level action.

Examples:

install @stacy/plugin-linear once
make it available everywhere immediately
optionally store mappings over Stacy objects if one company maps to a different Linear team than another

6. Use project workspaces as the primary anchor for local tooling

Stacy already has a concrete workspace model for projects:

projects expose workspaces and primaryWorkspace
the database already has project_workspaces
project routes already support creating, updating, and deleting workspaces
heartbeat resolution already prefers project workspaces before falling back to task-session or agent-home workspaces

That means local/runtime plugins should generally anchor themselves to projects first, not invent a parallel workspace model.

Practical guidance:

file browser should browse project workspaces first
terminal sessions should be launchable from a project workspace
git should treat the project workspace as the repo root anchor
dev server and child-process tracking should attach to project workspaces
issue and agent views can still deep-link into the relevant project workspace context

In other words:

project is the business object
project_workspace is the local runtime anchor
plugins should build on that instead of creating an unrelated workspace model first

7. Let plugins contribute agent tools

opencode makes tools a first-class extension point. This is one of the highest-value surfaces for Stacy too.

A Linear plugin should be able to contribute a search-linear-issues tool that agents use during runs. A git plugin should contribute create-branch and get-diff. A file browser plugin should contribute read-file and list-directory.

The key constraints:

plugin tools are namespaced by plugin ID (e.g. linear:search-issues) so they cannot shadow core tools
plugin tools require the agent.tools.register capability
tool execution goes through the same worker RPC boundary as everything else
tool results appear in run logs

This is a natural fit — the plugin already has the SDK context, the external API credentials, and the domain logic. Wrapping that in a tool definition is minimal additional work for the plugin author.

8. Support plugin-to-plugin events

Plugins should be able to emit custom events that other plugins can subscribe to. For example, the git plugin detects a push and emits plugin.@stacy/plugin-git.push-detected. The GitHub Issues plugin subscribes to that event and updates PR links.

This avoids plugins needing to coordinate through shared state or external channels. The host routes plugin events through the same event bus with the same delivery semantics as core events.

Plugin events use a plugin.<pluginId>.* namespace so they cannot collide with core events.

9. Auto-generate settings UI from config schema

Plugins that declare an instanceConfigSchema should get an auto-generated settings form for free. The host renders text inputs, dropdowns, toggles, arrays, and secret-ref pickers directly from the JSON Schema.

For plugins that need richer settings UX, they can declare a settingsPage extension slot and ship a custom React component. Both approaches coexist.

This matters because settings forms are boilerplate that every plugin needs. Auto-generating them from the schema that already exists removes a significant chunk of authoring friction.

10. Design for graceful shutdown and upgrade

The spec should be explicit about what happens when a plugin worker stops — during upgrades, uninstalls, or instance restarts.

The recommended policy:

send shutdown() with a configurable deadline (default 10 seconds)
SIGTERM after deadline, SIGKILL after 5 more seconds
in-flight jobs marked cancelled
in-flight bridge calls return structured errors to the UI

For upgrades specifically: the old worker drains, the new worker starts. If the new version adds capabilities, it enters upgrade_pending until the operator approves.

11. Define uninstall data lifecycle

When a plugin is uninstalled, its data (plugin_state, plugin_entities, plugin_jobs, etc.) should be retained for a grace period (default 30 days), not immediately deleted. The operator can reinstall within the grace period and recover state, or force-purge via CLI.

This matters because accidental uninstalls should not cause irreversible data loss.

12. Invest in plugin observability

Plugin logs via ctx.logger should be stored and queryable from the plugin settings page. The host should also capture raw stdout/stderr from the worker process as fallback.

The plugin health dashboard should show: worker status, uptime, recent logs, job success/failure rates, webhook delivery rates, and resource usage. The host should emit internal events (plugin.health.degraded, plugin.worker.crashed) that other plugins or dashboards can consume.

This is critical for operators. Without observability, debugging plugin issues requires SSH access and manual log tailing.

13. Ship a test harness and starter template

A @stacy/plugin-test-harness package should provide a mock host with in-memory stores, synthetic event emission, and getData/performAction/executeTool simulation. Plugin authors should be able to write unit tests without a running Stacy instance.

A create-stacy-plugin CLI should scaffold a working plugin with manifest, worker, UI bundle, test file, and build config.

Low authoring friction was called out as one of opencode's best qualities. The test harness and starter template are how Stacy achieves the same.

14. Support hot plugin lifecycle

Plugin install, uninstall, upgrade, and config changes should take effect without restarting the Stacy server. This is critical for developer workflow and operator experience.

The out-of-process worker architecture makes this natural:

Hot install: spawn a new worker, register its event subscriptions, job schedules, webhook endpoints, and agent tools in live routing tables, load its UI bundle into the extension slot registry.
Hot uninstall: graceful shutdown of the worker, remove all registrations from routing tables, unmount UI components, start data retention grace period.
Hot upgrade: shut down old worker, start new worker, atomically swap routing table entries, invalidate UI bundle cache so the frontend loads the updated bundle.
Hot config change: write new config to plugin_config, notify the running worker via IPC (configChanged). The worker applies the change without restarting. If it doesn't handle configChanged, the host restarts just that worker.

Frontend cache invalidation uses versioned or content-hashed bundle URLs and a plugin.ui.updated event that triggers re-import without a full page reload.

Each worker process is independent — starting, stopping, or replacing one worker never affects any other plugin or the host itself.

15. Define SDK versioning and compatibility

opencode does not have a formal SDK versioning story because plugins run in-process and are effectively pinned to the current runtime. Stacy's out-of-process model means plugins may be built against one SDK version and run on a host that has moved forward. This needs explicit rules.

Recommended approach:

Single SDK package: @arpanstacy/stacy-plugin-sdk with subpath exports — root for worker code, /ui for frontend code. One dependency, one version, one changelog.
SDK major version = API version: @arpanstacy/stacy-plugin-sdk@2.x targets apiVersion: 2. Plugins built with SDK 1.x declare apiVersion: 1 and continue to work.
Host multi-version support: The host supports at least the current and one previous apiVersion simultaneously with separate IPC protocol handlers per version.
sdkVersion in manifest: Plugins declare a semver range (e.g. ">=1.4.0 <2.0.0"). The host validates this at install time.
Deprecation timeline: Previous API versions get at least 6 months of continued support after a new version ships. The host logs deprecation warnings and shows a banner on the plugin settings page.
Migration guides: Each major SDK release ships with a step-by-step migration guide covering every breaking change.
UI surface versioned with worker: Both worker and UI surfaces are in the same package, so they version together. Breaking changes to shared UI components require a major version bump just like worker API changes.
Published compatibility matrix: The host publishes a matrix of supported API versions and SDK ranges, queryable via API.

A Concrete SDK Shape For Stacy

An intentionally narrow first pass could look like this:

import { definePlugin, z } from "@arpanstacy/stacy-plugin-sdk";

export default definePlugin({
  id: "@stacy/plugin-linear",
  version: "0.1.0",
  categories: ["connector", "ui"],
  capabilities: [
    "events.subscribe",
    "jobs.schedule",
    "http.outbound",
    "instance.settings.register",
    "ui.dashboardWidget.register",
    "secrets.read-ref",
  ],
  instanceConfigSchema: z.object({
    linearBaseUrl: z.string().url().optional(),
    companyMappings: z.array(
      z.object({
        companyId: z.string(),
        teamId: z.string(),
        apiTokenSecretRef: z.string(),
      }),
    ).default([]),
  }),
  async register(ctx) {
    ctx.jobs.register("linear-pull", { cron: "*/5 * * * *" }, async (job) => {
      // sync Linear issues into plugin-owned state or explicit Stacy entities
    });

    // subscribe with optional server-side filter
    ctx.events.on("issue.created", { projectId: "proj-1" }, async (event) => {
      // only receives issue.created events for project proj-1
    });

    // subscribe to events from another plugin
    ctx.events.on("plugin.@stacy/plugin-git.push-detected", async (event) => {
      // react to the git plugin detecting a push
    });

    // contribute a tool that agents can use during runs
    ctx.tools.register("search-linear-issues", {
      displayName: "Search Linear Issues",
      description: "Search for Linear issues by query",
      parametersSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
    }, async (params, runCtx) => {
      // search Linear API and return results
      return { content: JSON.stringify(results) };
    });

    // getData is called by the plugin's own UI components via the host bridge
    ctx.data.register("sync-health", async ({ companyId }) => {
      // return typed JSON that the plugin's DashboardWidget component renders
      return { syncedCount: 142, trend: "+12 today", mappings: [...] };
    });

    ctx.actions.register("resync", async ({ companyId }) => {
      // run sync logic
    });
  },
});

The plugin's UI bundle (separate from the worker) might look like:

// dist/ui/index.tsx
import { usePluginData, usePluginAction, MetricCard, ErrorBoundary } from "@arpanstacy/stacy-plugin-sdk/ui";

export function DashboardWidget({ context }: PluginWidgetProps) {
  const { data, loading, error } = usePluginData("sync-health", { companyId: context.companyId });
  const resync = usePluginAction("resync");

  if (loading) return <Spinner />;
  if (error) return <div>Plugin error: {error.message} ({error.code})</div>;

  return (
    <ErrorBoundary fallback={<div>Widget failed to render</div>}>
      <MetricCard label="Synced Issues" value={data.syncedCount} trend={data.trend} />
      <button onClick={() => resync({ companyId: context.companyId })}>Resync Now</button>
    </ErrorBoundary>
  );
}

The important point is not the exact syntax. The important point is the contract shape:

typed manifest
explicit capabilities
explicit global config with optional company mappings
event subscriptions with optional server-side filtering
plugin-to-plugin events via namespaced event types
agent tool contributions
jobs
plugin-shipped UI that communicates with its worker through the host bridge
structured error propagation from worker to UI

Recommended Core Extension Surfaces

1. Platform module surfaces

These should stay close to the current registry style.

Candidates:

registerAgentAdapter()
registerStorageProvider()
registerSecretProvider()
registerRunLogStore()

These are trusted platform modules, not casual plugins.

2. Connector plugin surfaces

These are the best near-term plugin candidates.

Capabilities:

subscribe to domain events
define scheduled sync jobs
expose plugin-specific API routes under /api/plugins/:pluginId/...
use company secret refs
write plugin state
publish dashboard data
log activity through core APIs

Examples:

Linear issue sync
GitHub issue sync
Grafana dashboard cards
Stripe MRR / subscription rollups

3. Workspace-runtime surfaces

Workspace plugins handle local tooling directly:

file browser
terminal
git workflow
child process tracking
local dev server tracking

Plugins resolve workspace paths through host APIs (ctx.projects provides workspace metadata including cwd, repoUrl, etc.) and then operate on the filesystem, spawn processes, shell out to git, or open PTY sessions using standard Node APIs or any libraries they choose.

The host does not wrap or proxy these operations. This keeps the core lean — no need to maintain a parallel API surface for every OS-level operation a plugin might need. Plugins own their own implementations.

Governance And Safety Requirements

Any Stacy plugin system has to preserve core control-plane invariants from the repo docs.

That means:

plugin install is global to the instance
"companies" remain business objects in the API and data model, not tenant boundaries
approval gates remain core-owned
budget hard-stops remain core-owned
mutating actions are activity-logged
secrets remain ref-based and redacted in logs

I would require the following for every plugin:

1. Capability declaration

Every plugin declares a static capability set such as:

companies.read
issues.read
issues.write
events.subscribe
events.emit
jobs.schedule
http.outbound
webhooks.receive
assets.read
assets.write
secrets.read-ref
agent.tools.register
plugin.state.read
plugin.state.write

The board/operator sees this before installation.

2. Global installation

A plugin is installed once and becomes available across the instance. If it needs mappings over specific Stacy objects, those are plugin data, not enable/disable boundaries.

3. Activity logging

Plugin-originated mutations should flow through the same activity log mechanism, with a dedicated plugin actor type:

actor_type = plugin
actor_id = <plugin-id> (e.g. @stacy/plugin-linear)

4. Health and failure reporting

Each plugin should expose:

enabled/disabled state
last successful run
last error
recent webhook/job history

One broken plugin must not break the rest of the company.

5. Secret handling

Plugins should receive secret refs, not raw secret values in config persistence. Resolution should go through the existing secret provider abstraction.

6. Resource limits

Plugins should have:

timeout limits
concurrency limits
retry policies
optional per-plugin budgets

This matters especially for sync connectors and workspace plugins.

Data Model Additions To Consider

I would avoid "arbitrary third-party plugin-defined SQL migrations" in the first version. That is too much power too early.

The right mental model is:

reuse core tables when the data is clearly part of Stacy itself
use generic extension tables for most plugin-owned state
only allow plugin-specific tables later, and only for trusted platform modules or a tightly controlled migration workflow

Suggested baseline extension tables

1. `plugins`

Instance-level installation record.

Suggested fields:

id
package_name
version
categories
manifest_json
installed_at
status

2. `plugin_config`

Instance-level plugin config.

Suggested fields:

id
plugin_id
config_json
created_at
updated_at
last_error

3. `plugin_state`

Generic key/value state for plugins.

Suggested fields:

id
plugin_id
scope_kind (instance | company | project | project_workspace | agent | issue | goal | run)
scope_id nullable
namespace
state_key
value_json
updated_at

This is enough for many connectors before allowing custom tables.

Examples:

Linear external IDs keyed by issue
GitHub sync cursors keyed by project
file browser preferences keyed by project_workspace
git branch metadata keyed by project_workspace
process metadata keyed by project_workspace or run

4. `plugin_jobs`

Scheduled job and run tracking.

Suggested fields:

id
plugin_id
scope_kind nullable
scope_id nullable
job_key
status
last_started_at
last_finished_at
last_error

5. `plugin_webhook_deliveries`

If plugins expose webhooks, delivery history is worth storing.

Suggested fields:

id
plugin_id
scope_kind nullable
scope_id nullable
endpoint_key
status
received_at
response_code
error

6. Maybe later: `plugin_entities`

If generic plugin state becomes too limiting, add a structured, queryable entity table for connector records before allowing arbitrary plugin migrations.

Suggested fields:

id
plugin_id
entity_type
scope_kind
scope_id
external_id
title
status
data_json
updated_at

This is a useful middle ground:

much more queryable than opaque key/value state
still avoids letting every plugin create its own relational schema immediately

How The Requested Examples Map To This Model

Use case	Best fit	Host primitives needed	Notes
File browser	workspace plugin	project workspace metadata	plugin owns filesystem ops directly
Terminal	workspace plugin	project workspace metadata	plugin spawns PTY sessions directly
Git workflow	workspace plugin	project workspace metadata	plugin shells out to git directly
Linear issue tracking	connector plugin	jobs, webhooks, secret refs, issue sync API	very strong plugin candidate
GitHub issue tracking	connector plugin	jobs, webhooks, secret refs	very strong plugin candidate
Grafana metrics	connector plugin + dashboard widget	outbound HTTP	probably read-only first
Child process/server tracking	workspace plugin	project workspace metadata	plugin manages processes directly
Stripe revenue tracking	connector plugin	secret refs, scheduled sync, company metrics API	strong plugin candidate

Plugin Examples

Workspace File Browser

Package idea: @stacy/plugin-workspace-files

This plugin lets the board inspect project workspaces, agent workspaces, generated artifacts, and issue-related files without dropping to the shell. It is useful for:

browsing files inside project workspaces
debugging what an agent changed
reviewing generated outputs before approval
attaching files from a workspace to issues
understanding repo layout for a company
inspecting agent home workspaces in local-trusted mode

UX

Settings page: /settings/plugins/workspace-files
Main page: /:companyPrefix/plugins/workspace-files
Project tab: /:companyPrefix/projects/:projectId?tab=files
Optional issue tab: /:companyPrefix/issues/:issueId?tab=files
Optional agent tab: /:companyPrefix/agents/:agentId?tab=workspace

Main screens and interactions:

Plugin settings:
- choose whether the plugin defaults to project.primaryWorkspace
- choose which project workspaces are visible
- choose whether file writes are allowed or read-only
- choose whether hidden files are visible
Main explorer page:
- project picker at the top
- workspace picker scoped to the selected project's workspaces
- tree view on the left
- file preview pane on the right
- search box for filename/path search
- actions: copy path, download file, attach to issue, open diff
Project tab:
- opens directly into the project's primary workspace
- lets the board switch among all project workspaces
- shows workspace metadata like cwd, repoUrl, and repoRef
Issue tab:
- resolves the issue's project and opens that project's workspace context
- shows files linked to the issue
- lets the board pull files from the project workspace into issue attachments
- shows the path and last modified info for each linked file
Agent tab:
- shows the agent's current resolved workspace
- if the run is attached to a project, links back to the project workspace view
- lets the board inspect files the agent is currently touching

Core workflows:

Board opens a project and browses its primary workspace files.
Board switches from one project workspace to another when a project has multiple checkouts or repo references.
Board opens an issue, attaches a generated artifact from the file browser, and leaves a review comment.
Board opens an agent detail page to inspect the exact files behind a failing run.

Hooks needed

Recommended capabilities and extension points:

instance.settings.register
ui.sidebar.register
ui.page.register
ui.detailTab.register for project, issue, and agent
projects.read
project.workspaces.read
optional assets.write
activity.log.write

The plugin resolves workspace paths through ctx.projects and handles all filesystem operations (read, write, stat, search, list directory) directly using Node APIs.

Optional event subscriptions:

events.subscribe(agent.run.started)
events.subscribe(agent.run.finished)
events.subscribe(issue.attachment.created)

Workspace Terminal

Package idea: @stacy/plugin-terminal

This plugin gives the board a controlled terminal UI for project workspaces and agent workspaces. It is useful for:

debugging stuck runs
verifying environment state
running targeted manual commands
watching long-running commands
pairing a human operator with an agent workflow

UX

Settings page: /settings/plugins/terminal
Main page: /:companyPrefix/plugins/terminal
Project tab: /:companyPrefix/projects/:projectId?tab=terminal
Optional agent tab: /:companyPrefix/agents/:agentId?tab=terminal
Optional run tab: /:companyPrefix/agents/:agentId/runs/:runId?tab=terminal

Main screens and interactions:

Plugin settings:
- allowed shells and shell policy
- whether commands are read-only, free-form, or allow-listed
- whether terminals require an explicit operator confirmation before launch
- whether new terminal sessions default to the project's primary workspace
Terminal home page:
- list of active terminal sessions
- button to open a new session
- project picker, then workspace picker from that project's workspaces
- optional agent association
- terminal panel with input, resize, and reconnect support
- controls: interrupt, kill, clear, save transcript
Project terminal tab:
- opens a session already scoped to the project's primary workspace
- lets the board switch among the project's configured workspaces
- shows recent commands and related process/server state for that project
Agent terminal tab:
- opens a session already scoped to the agent's workspace
- shows recent related runs and commands
Run terminal tab:
- lets the board inspect the environment around a specific failed run

Core workflows:

Board opens a terminal against an agent workspace to reproduce a failing command.
Board opens a project page and launches a terminal directly in that project's primary workspace.
Board watches a long-running dev server or test command from the terminal page.
Board kills or interrupts a runaway process from the same UI.

Hooks needed

Recommended capabilities and extension points:

instance.settings.register
ui.sidebar.register
ui.page.register
ui.detailTab.register for project, agent, and run
projects.read
project.workspaces.read
activity.log.write

The plugin resolves workspace paths through ctx.projects and handles PTY session management (open, input, resize, terminate, subscribe) directly using Node PTY libraries.

Optional event subscriptions:

events.subscribe(agent.run.started)
events.subscribe(agent.run.failed)
events.subscribe(agent.run.cancelled)

Git Workflow

Package idea: @stacy/plugin-git

This plugin adds repo-aware workflow tooling around issues and workspaces. It is useful for:

branch creation tied to issues
quick diff review
commit and worktree visibility
PR preparation
treating the project's primary workspace as the canonical repo anchor
seeing whether an agent's workspace is clean or dirty

UX

Settings page: /settings/plugins/git
Main page: /:companyPrefix/plugins/git
Project tab: /:companyPrefix/projects/:projectId?tab=git
Optional issue tab: /:companyPrefix/issues/:issueId?tab=git
Optional agent tab: /:companyPrefix/agents/:agentId?tab=git

Main screens and interactions:

Plugin settings:
- branch naming template
- optional remote provider token secret ref
- whether write actions are enabled or read-only
- whether the plugin always uses project.primaryWorkspace unless a different project workspace is chosen
Git overview page:
- project picker and workspace picker
- current branch
- ahead/behind status
- dirty files summary
- recent commits
- active worktrees
- actions: refresh, create branch, create worktree, stage all, commit, open diff
Project tab:
- opens in the project's primary workspace
- shows workspace metadata and repo binding (cwd, repoUrl, repoRef)
- shows branch, diff, and commit history for that project workspace
Issue tab:
- resolves the issue's project and uses that project's workspace context
- "create branch from issue" action
- diff view scoped to the project's selected workspace
- link branch/worktree metadata to the issue
Agent tab:
- shows the agent's branch, worktree, and dirty state
- shows recent commits produced by that agent
- if the agent is working inside a project workspace, links back to the project git tab

Core workflows:

Board creates a branch from an issue and ties it to the project's primary workspace.
Board opens a project page and reviews the diff for that project's workspace without leaving Stacy.
Board reviews the diff after a run without leaving Stacy.
Board opens a worktree list to understand parallel branches across agents.

Hooks needed

Recommended capabilities and extension points:

instance.settings.register
ui.sidebar.register
ui.page.register
ui.detailTab.register for project, issue, and agent
ui.action.register
projects.read
project.workspaces.read
optional agent.tools.register (e.g. create-branch, get-diff, get-status)
optional events.emit (e.g. plugin.@stacy/plugin-git.push-detected)
activity.log.write

The plugin resolves workspace paths through ctx.projects and handles all git operations (status, diff, log, branch create, commit, worktree create, push) directly using git CLI or a git library.

Optional event subscriptions:

events.subscribe(issue.created)
events.subscribe(issue.updated)
events.subscribe(agent.run.finished)

The git plugin can emit plugin.@stacy/plugin-git.push-detected events that other plugins (e.g. GitHub Issues) subscribe to for cross-plugin coordination.

Note: GitHub/GitLab PR creation should likely live in a separate connector plugin rather than overloading the local git plugin.

Linear Issue Tracking

Package idea: @stacy/plugin-linear

This plugin syncs Stacy work with Linear. It is useful for:

importing backlog from Linear
linking Stacy issues to Linear issues
syncing status, comments, and assignees
mapping company goals/projects to external product planning
giving board operators a single place to see sync health

UX

Settings page: /settings/plugins/linear
Main page: /:companyPrefix/plugins/linear
Dashboard widget: /:companyPrefix/dashboard
Optional issue tab: /:companyPrefix/issues/:issueId?tab=linear
Optional project tab: /:companyPrefix/projects/:projectId?tab=linear

Main screens and interactions:

Plugin settings:
- Linear API token secret ref
- workspace/team/project mappings
- status mapping between Stacy and Linear
- sync direction: import only, export only, bidirectional
- comment sync toggle
Linear overview page:
- sync health card
- recent sync jobs
- mapped projects and teams
- unresolved conflicts queue
- import actions for teams, projects, and issues
Issue tab:
- linked Linear issue key and URL
- sync status and last synced time
- actions: link existing, create in Linear, resync now, unlink
- timeline of synced comments/status changes
Dashboard widget:
- open sync errors
- imported vs linked issues count
- recent webhook/job failures

Core workflows:

Board enables the plugin, maps a Linear team, and imports a backlog into Stacy.
Stacy issue status changes push to Linear and Linear comments arrive back through webhooks.
Board resolves mapping conflicts from the plugin page instead of silently drifting state.

Hooks needed

Recommended capabilities and extension points:

instance.settings.register
ui.sidebar.register
ui.page.register
ui.dashboardWidget.register
ui.detailTab.register for issue and project
events.subscribe(issue.created)
events.subscribe(issue.updated)
events.subscribe(issue.comment.created)
events.subscribe(project.updated)
jobs.schedule
webhooks.receive
http.outbound
secrets.read-ref
plugin.state.read
plugin.state.write
optional issues.create
optional issues.update
optional issue.comments.create
optional agent.tools.register (e.g. search-linear-issues, get-linear-issue)
activity.log.write

Important constraint:

webhook processing should be idempotent and conflict-aware
external IDs and sync cursors belong in plugin-owned state, not inline on core issue rows in the first version

GitHub Issue Tracking

Package idea: @stacy/plugin-github-issues

This plugin syncs Stacy issues with GitHub Issues and optionally links PRs. It is useful for:

importing repo backlogs
mirroring issue status and comments
linking PRs to Stacy issues
tracking cross-repo work from inside one company view
bridging engineering workflow with Stacy task governance

UX

Settings page: /settings/plugins/github-issues
Main page: /:companyPrefix/plugins/github-issues
Dashboard widget: /:companyPrefix/dashboard
Optional issue tab: /:companyPrefix/issues/:issueId?tab=github
Optional project tab: /:companyPrefix/projects/:projectId?tab=github

Main screens and interactions:

Plugin settings:
- GitHub App or PAT secret ref
- org/repo mappings
- label/status mapping
- whether PR linking is enabled
- whether new Stacy issues should create GitHub issues automatically
GitHub overview page:
- repo mapping list
- sync health and recent webhook events
- import backlog action
- queue of unlinked GitHub issues
Issue tab:
- linked GitHub issue and optional linked PRs
- actions: create GitHub issue, link existing issue, unlink, resync
- comment/status sync timeline
Dashboard widget:
- open PRs linked to active Stacy issues
- webhook failures
- sync lag metrics

Core workflows:

Board imports GitHub Issues for a repo into Stacy.
GitHub webhooks update status/comment state in Stacy.
A PR is linked back to the Stacy issue so the board can follow delivery status.

Hooks needed

Recommended capabilities and extension points:

instance.settings.register
ui.sidebar.register
ui.page.register
ui.dashboardWidget.register
ui.detailTab.register for issue and project
events.subscribe(issue.created)
events.subscribe(issue.updated)
events.subscribe(issue.comment.created)
events.subscribe(plugin.@stacy/plugin-git.push-detected) (cross-plugin coordination)
jobs.schedule
webhooks.receive
http.outbound
secrets.read-ref
plugin.state.read
plugin.state.write
optional issues.create
optional issues.update
optional issue.comments.create
activity.log.write

Important constraint:

keep "local git state" and "remote GitHub issue state" in separate plugins even if they work together — cross-plugin events handle coordination

Grafana Metrics

Package idea: @stacy/plugin-grafana

This plugin surfaces external metrics and dashboards inside Stacy. It is useful for:

company KPI visibility
infrastructure/incident monitoring
showing deploy, traffic, latency, or revenue charts next to work
creating Stacy issues from anomalous metrics

UX

Settings page: /settings/plugins/grafana
Main page: /:companyPrefix/plugins/grafana
Dashboard widgets: /:companyPrefix/dashboard
Optional goal tab: /:companyPrefix/goals/:goalId?tab=metrics

Main screens and interactions:

Plugin settings:
- Grafana base URL
- service account token secret ref
- dashboard and panel mappings
- refresh interval
- optional alert threshold rules
Dashboard widgets:
- one or more metric cards on the main dashboard
- quick trend view and last refresh time
- link out to Grafana and link in to the full Stacy plugin page
Full metrics page:
- selected dashboard panels embedded or proxied
- metric selector
- time range selector
- "create issue from anomaly" action
Goal tab:
- metric cards relevant to a specific goal or project

Core workflows:

Board sees service degradation or business KPI movement directly on the Stacy dashboard.
Board clicks into the full metrics page to inspect the relevant Grafana panels.
Board creates a Stacy issue from a threshold breach with a metric snapshot attached.

Hooks needed

Recommended capabilities and extension points:

instance.settings.register
ui.dashboardWidget.register
ui.page.register
ui.detailTab.register for goal or project
jobs.schedule
http.outbound
secrets.read-ref
plugin.state.read
plugin.state.write
optional issues.create
optional assets.write
activity.log.write

Optional event subscriptions:

events.subscribe(goal.created)
events.subscribe(project.updated)

Important constraint:

start read-only first
do not make Grafana alerting logic part of Stacy core; keep it as additive signal and issue creation

Child Process / Server Tracking

Package idea: @stacy/plugin-runtime-processes

This plugin tracks long-lived local processes and dev servers started in project workspaces. It is useful for:

seeing which agent started which local service
tracking ports, health, and uptime
restarting failed dev servers
exposing process state alongside issue and run state
making local development workflows visible to the board

UX

Settings page: /settings/plugins/runtime-processes
Main page: /:companyPrefix/plugins/runtime-processes
Dashboard widget: /:companyPrefix/dashboard
Process detail page: /:companyPrefix/plugins/runtime-processes/:processId
Project tab: /:companyPrefix/projects/:projectId?tab=processes
Optional agent tab: /:companyPrefix/agents/:agentId?tab=processes

Main screens and interactions:

Plugin settings:
- whether manual process registration is allowed
- health check behavior
- whether operators can stop/restart processes
- log retention preferences
Process list page:
- status table with name, command, cwd, owner agent, port, uptime, and health
- filters for running/exited/crashed processes
- actions: inspect, stop, restart, tail logs
Project tab:
- filters the process list to the project's workspaces
- shows which workspace each process belongs to
- groups processes by project workspace
Process detail page:
- process metadata
- live log tail
- health check history
- links to associated issue or run
Agent tab:
- shows processes started by or assigned to that agent

Core workflows:

An agent starts a dev server; the plugin detects and tracks it.
Board opens a project and immediately sees the processes attached to that project's workspace.
Board sees a crashed process on the dashboard and restarts it from the plugin page.
Board attaches process logs to an issue when debugging a failure.

Hooks needed

Recommended capabilities and extension points:

instance.settings.register
ui.sidebar.register
ui.page.register
ui.dashboardWidget.register
ui.detailTab.register for project and agent
projects.read
project.workspaces.read
plugin.state.read
plugin.state.write
activity.log.write

The plugin resolves workspace paths through ctx.projects and handles process management (register, list, terminate, restart, read logs, health probes) directly using Node APIs.

Optional event subscriptions:

events.subscribe(agent.run.started)
events.subscribe(agent.run.finished)

Stripe Revenue Tracking

Package idea: @stacy/plugin-stripe

This plugin pulls Stripe revenue and subscription data into Stacy. It is useful for:

showing MRR and churn next to company goals
tracking trials, conversions, and failed payments
letting the board connect revenue movement to ongoing work
enabling future financial dashboards beyond token costs

UX

Settings page: /settings/plugins/stripe
Main page: /:companyPrefix/plugins/stripe
Dashboard widgets: /:companyPrefix/dashboard
Optional company/goal metric tabs if those surfaces exist later

Main screens and interactions:

Plugin settings:
- Stripe secret key secret ref
- account selection if needed
- metric definitions such as MRR treatment and trial handling
- sync interval
- webhook signing secret ref
Dashboard widgets:
- MRR card
- active subscriptions
- trial-to-paid conversion
- failed payment alerts
Stripe overview page:
- time series charts
- recent customer/subscription events
- webhook health
- sync history
- action: create issue from billing anomaly

Core workflows:

Board enables the plugin and connects a Stripe account.
Webhooks and scheduled reconciliation keep plugin state current.
Revenue widgets appear on the main dashboard and can be linked to company goals.
Failed payment spikes or churn events can generate Stacy issues for follow-up.

Hooks needed

Recommended capabilities and extension points:

instance.settings.register
ui.dashboardWidget.register
ui.page.register
jobs.schedule
webhooks.receive
http.outbound
secrets.read-ref
plugin.state.read
plugin.state.write
metrics.write
optional issues.create
activity.log.write

Important constraint:

Stripe data should stay additive to Stacy core
it should not leak into core budgeting logic, which is specifically about model/token spend in V1

Specific Patterns From OpenCode Worth Adopting

Adopt

separate SDK package from runtime loader
deterministic load order and precedence
very small authoring API
typed schemas for plugin inputs/config/tools
tools as a first-class plugin extension point (namespaced, not override-by-collision)
internal extensions using the same registration shapes as external ones when reasonable
plugin load errors isolated from host startup when possible
explicit community-facing plugin docs and example templates
test harness and starter template for low authoring friction
hot plugin lifecycle without server restart (enabled by out-of-process workers)
formal SDK versioning with multi-version host support

Adapt, not copy

local path loading
dependency auto-install
hook mutation model
built-in override behavior
broad runtime context objects

Avoid

project-local arbitrary code loading
implicit trust of npm packages at startup
plugins overriding core invariants
unsandboxed in-process execution as the default extension model

Suggested Rollout Plan

Phase 0: Harden the seams that already exist

formalize adapter/storage/secret/run-log registries as "platform modules"
remove ad-hoc fallback behavior where possible
document stable registration contracts

Phase 1: Add connector plugins first

This is the highest-value, lowest-risk plugin category.

Build:

plugin manifest
global install/update lifecycle
global plugin config and optional company-mapping storage
secret ref access
typed domain event subscription
scheduled jobs
webhook endpoints
activity logging helpers
plugin UI bundle loading, host bridge, @arpanstacy/stacy-plugin-sdk/ui
extension slot mounting for pages, tabs, widgets, sidebar entries
auto-generated settings form from instanceConfigSchema
bridge error propagation (PluginBridgeError)
plugin-contributed agent tools
plugin-to-plugin events (plugin.<pluginId>.* namespace)
event filtering (server-side, per-subscription)
graceful shutdown with configurable deadlines
plugin logging and health dashboard
uninstall with data retention grace period
@stacy/plugin-test-harness and create-stacy-plugin starter template
hot plugin lifecycle (install, uninstall, upgrade, config change without server restart)
SDK versioning with multi-version host support and deprecation policy

This phase would immediately cover:

Linear
GitHub
Grafana
Stripe
file browser
terminal
git workflow
child process/server tracking

Workspace plugins do not require additional host APIs — they resolve workspace paths through ctx.projects and handle filesystem, git, PTY, and process operations directly.

Phase 2: Consider richer UI and plugin packaging

Only after Phase 1 is stable:

iframe-based isolation for untrusted third-party plugin UI bundles
signed/verified plugin packages
plugin marketplace
optional custom plugin storage backends or migrations

Recommended Architecture Decision

If I had to collapse this report into one architectural decision, it would be:

Stacy should not implement "an OpenCode-style generic in-process hook system." Stacy should implement "a plugin platform with multiple trust tiers":

trusted platform modules for low-level runtime integration
typed out-of-process plugins for instance-wide integrations and automation
plugin-contributed agent tools (namespaced, capability-gated)
plugin-shipped UI bundles rendered in host extension slots via a typed bridge with structured error propagation
plugin-to-plugin events for cross-plugin coordination
auto-generated settings UI from config schema
core-owned invariants that plugins can observe and act around, but not replace
plugin observability, graceful lifecycle management, and a test harness for low authoring friction
hot plugin lifecycle — no server restart for install, uninstall, upgrade, or config changes
SDK versioning with multi-version host support and clear deprecation policy

That gets the upside of opencode's extensibility without importing the wrong threat model.

Concrete Next Steps I Would Take In Stacy

Write a short extension architecture RFC that formalizes the distinction between platform modules and plugins.
Introduce a small plugin manifest type in packages/shared and a plugins install/config section in the instance config.
Build a typed domain event bus around existing activity/live-event patterns, with server-side event filtering and a plugin.* namespace for cross-plugin events. Keep core invariants non-hookable.
Implement plugin MVP: global install/config, secret refs, jobs, webhooks, plugin UI bundles, extension slots, auto-generated settings forms, bridge error propagation.
Add agent tool contributions — plugins register namespaced tools that agents can call during runs.
Add plugin observability: structured logging via ctx.logger, health dashboard, internal health events.
Add graceful shutdown policy and uninstall data lifecycle with retention grace period.
Ship @stacy/plugin-test-harness and create-stacy-plugin starter template.
Implement hot plugin lifecycle — install, uninstall, upgrade, and config changes without server restart.
Define SDK versioning policy — semver, multi-version host support, deprecation timeline, migration guides, published compatibility matrix.
Build workspace plugins (file browser, terminal, git, process tracking) that resolve workspace paths from the host and handle OS-level operations directly.

Uh oh!

FilesExpand file tree

ideas-from-opencode.md

Latest commit

History

ideas-from-opencode.md

File metadata and controls

Plugin Ideas From OpenCode

Executive Summary

Sources Examined

What OpenCode Actually Implements

1. Plugin authoring API

2. Hook model

3. Plugin discovery and load order

4. Dependency handling

5. Error handling

6. Tools are a first-class extension point

7. Auth is also a plugin surface

8. Ecosystem evidence

What OpenCode Gets Right

1. Separate plugin SDK from host runtime

2. Deterministic loading and precedence

3. Low-ceremony authoring

4. Typed tool definitions

5. Built-in features and plugins use similar shapes

6. Incremental extension, not giant abstraction upfront

What Stacy Should Not Copy Directly

1. In-process arbitrary plugin code as the default

2. Project-local plugin loading

3. Arbitrary mutation hooks on core business decisions

4. Override-by-name collision

5. Auto-install and execute from user config

Why Stacy Needs A Different Shape

Stacy Already Has Useful Pre-Plugin Seams

Recommended Stacy Plugin Model

1. Use multiple extension classes

2. Keep low-level modules separate from third-party plugins

3. Prefer event-driven extensions over core-logic mutation

4. Plugins ship their own UI

5. Make installation global and keep mappings/config separate

6. Use project workspaces as the primary anchor for local tooling

7. Let plugins contribute agent tools

8. Support plugin-to-plugin events

9. Auto-generate settings UI from config schema

10. Design for graceful shutdown and upgrade

11. Define uninstall data lifecycle

12. Invest in plugin observability

13. Ship a test harness and starter template

14. Support hot plugin lifecycle

15. Define SDK versioning and compatibility

A Concrete SDK Shape For Stacy

Recommended Core Extension Surfaces

1. Platform module surfaces

2. Connector plugin surfaces

3. Workspace-runtime surfaces

Governance And Safety Requirements

1. Capability declaration

2. Global installation

3. Activity logging

4. Health and failure reporting

5. Secret handling

6. Resource limits

Data Model Additions To Consider

Recommended Postgres Strategy For Extensions

1. Core tables stay core

2. Most plugins should start in generic extension tables

3. Scope plugin data to Stacy objects before adding custom schemas

4. Add trusted module migrations later, not arbitrary plugin migrations now

Suggested baseline extension tables

1. plugins

2. plugin_config

3. plugin_state

4. plugin_jobs

5. plugin_webhook_deliveries

6. Maybe later: plugin_entities

How The Requested Examples Map To This Model

Plugin Examples

Workspace File Browser

UX

Hooks needed

1. `plugins`

2. `plugin_config`

3. `plugin_state`

4. `plugin_jobs`

5. `plugin_webhook_deliveries`

6. Maybe later: `plugin_entities`