Plugin System Architecture | Bootspring Docs

How to extend Bootspring with custom plugins.

Overview#

The plugin system allows extending Bootspring with:

Custom agents
Custom skills
Custom workflows
CLI commands
Integrations

Plugin Architecture#

┌─────────────────────────────────────────────────────────────────────┐
│                       PLUGIN SYSTEM                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    Plugin Manager                            │   │
│  │        Load | Register | Lifecycle | Dependencies           │   │
│  └──────────────────────────┬──────────────────────────────────┘   │
│                             │                                       │
│          ┌──────────────────┼──────────────────┐                   │
│          ▼                  ▼                  ▼                   │
│    ┌──────────┐       ┌──────────┐       ┌──────────┐             │
│    │  Agent   │       │  Skill   │       │ Workflow │             │
│    │ Registry │       │ Registry │       │ Registry │             │
│    └──────────┘       └──────────┘       └──────────┘             │
│          │                  │                  │                   │
│          ▼                  ▼                  ▼                   │
│    ┌──────────┐       ┌──────────┐       ┌──────────┐             │
│    │ Command  │       │   Tool   │       │  Hook    │             │
│    │ Registry │       │ Registry │       │ Registry │             │
│    └──────────┘       └──────────┘       └──────────┘             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Plugin Interface#

Core Interface#

// @bootspring/plugin-sdk

export interface Plugin {
  // Metadata
  name: string;
  version: string;
  description?: string;
  author?: string;

  // Dependencies
  dependencies?: PluginDependency[];

  // Lifecycle hooks
  activate(context: PluginContext): Promise<void>;
  deactivate(): Promise<void>;
}

export interface PluginContext {
  // Registration
  registerAgent(profile: AgentProfile): void;
  registerSkill(skill: SkillDefinition): void;
  registerWorkflow(workflow: WorkflowDefinition): void;
  registerCommand(name: string, handler: CommandHandler): void;
  registerTool(tool: ToolDefinition): void;
  registerHook(event: string, handler: HookHandler): void;

  // Services
  getService<T>(name: string): T;
  getConfig<T>(key: string): T;

  // Storage
  getStorage(): PluginStorage;

  // Logging
  getLogger(): Logger;
}

Example Plugin#

// my-plugin/src/index.ts

import { Plugin, PluginContext } from '@bootspring/plugin-sdk';

export default class MyPlugin implements Plugin {
  name = 'my-plugin';
  version = '1.0.0';
  description = 'Example Bootspring plugin';

  private context!: PluginContext;

  async activate(context: PluginContext): Promise<void> {
    this.context = context;
    const logger = context.getLogger();

    logger.info('Activating my-plugin');

    // Register custom agent
    context.registerAgent({
      name: 'my-custom-agent',
      displayName: 'My Custom Agent',
      description: 'A custom agent for specific tasks',
      category: 'development',
      tier: 'pro',
      systemPrompt: 'You are a specialized assistant...',
      capabilities: ['custom-capability'],
    });

    // Register custom command
    context.registerCommand('my-command', this.handleMyCommand.bind(this));

    // Register hook
    context.registerHook('agent.invoked', this.onAgentInvoked.bind(this));

    logger.info('my-plugin activated');
  }

  async deactivate(): Promise<void> {
    const logger = this.context.getLogger();
    logger.info('Deactivating my-plugin');
    // Cleanup resources
  }

  private async handleMyCommand(args: string[]): Promise<void> {
    console.log('My command executed with:', args);
  }

  private async onAgentInvoked(event: AgentInvokedEvent): Promise<void> {
    console.log(`Agent ${event.agent} was invoked`);
  }
}

Plugin Manager#

Manager Implementation#

// core/plugins/manager.ts

export class PluginManager {
  private plugins: Map<string, LoadedPlugin> = new Map();
  private context: PluginContext;

  async loadPlugin(pluginPath: string): Promise<void> {
    // Import plugin module
    const PluginClass = await import(pluginPath);
    const plugin: Plugin = new PluginClass.default();

    // Check dependencies
    await this.checkDependencies(plugin);

    // Create context
    const context = this.createContext(plugin);

    // Activate plugin
    await plugin.activate(context);

    // Store loaded plugin
    this.plugins.set(plugin.name, {
      plugin,
      context,
      status: 'active',
    });
  }

  async unloadPlugin(name: string): Promise<void> {
    const loaded = this.plugins.get(name);
    if (!loaded) return;

    // Deactivate
    await loaded.plugin.deactivate();

    // Remove registrations
    this.removeRegistrations(name);

    // Remove from map
    this.plugins.delete(name);
  }

  private createContext(plugin: Plugin): PluginContext {
    return {
      registerAgent: (profile) => {
        this.agentRegistry.register({ ...profile, plugin: plugin.name });
      },
      registerSkill: (skill) => {
        this.skillRegistry.register({ ...skill, plugin: plugin.name });
      },
      registerWorkflow: (workflow) => {
        this.workflowRegistry.register({ ...workflow, plugin: plugin.name });
      },
      registerCommand: (name, handler) => {
        this.commandRegistry.register(name, handler, plugin.name);
      },
      registerTool: (tool) => {
        this.toolRegistry.register({ ...tool, plugin: plugin.name });
      },
      registerHook: (event, handler) => {
        this.hookRegistry.register(event, handler, plugin.name);
      },
      getService: (name) => this.serviceContainer.get(name),
      getConfig: (key) => this.configLoader.get(`plugins.${plugin.name}.${key}`),
      getStorage: () => new PluginStorage(plugin.name),
      getLogger: () => new PluginLogger(plugin.name),
    };
  }
}

Plugin Types#

Agent Plugin#

// plugins/agent/index.ts

export default class AgentPlugin implements Plugin {
  name = 'my-agent-plugin';
  version = '1.0.0';

  async activate(context: PluginContext): Promise<void> {
    context.registerAgent({
      name: 'specialized-expert',
      displayName: 'Specialized Expert',
      description: 'Expert in a specialized domain',
      category: 'development',
      tier: 'pro',

      systemPrompt: `
        You are an expert in specialized domain X.
        Your expertise includes:
        - Capability 1
        - Capability 2
        - Capability 3

        When helping users, always:
        1. Understand the context
        2. Provide clear explanations
        3. Give working code examples
      `,

      capabilities: [
        'Specialized skill 1',
        'Specialized skill 2',
      ],

      collaborates: ['frontend-expert', 'backend-expert'],
    });
  }

  async deactivate(): Promise<void> {}
}

Skill Plugin#

// plugins/skill/index.ts

export default class SkillPlugin implements Plugin {
  name = 'my-skill-plugin';
  version = '1.0.0';

  async activate(context: PluginContext): Promise<void> {
    context.registerSkill({
      name: 'custom-pattern',
      category: 'patterns',
      description: 'A custom code pattern',
      tier: 'pro',

      files: [
        {
          path: 'components/CustomComponent.tsx',
          template: `
import React from 'react';

interface {{ComponentName}}Props {
  {{#each props}}
  {{name}}: {{type}};
  {{/each}}
}

export function {{ComponentName}}({ {{propNames}} }: {{ComponentName}}Props) {
  return (
    <div>
      {/* Component implementation */}
    </div>
  );
}
          `,
        },
      ],

      variables: [
        { name: 'ComponentName', description: 'Component name', required: true },
        { name: 'props', description: 'Component props', type: 'array' },
      ],
    });
  }

  async deactivate(): Promise<void> {}
}

Integration Plugin#

// plugins/integration/index.ts

export default class IntegrationPlugin implements Plugin {
  name = 'linear-integration';
  version = '1.0.0';

  async activate(context: PluginContext): Promise<void> {
    const config = context.getConfig<LinearConfig>('linear');
    const logger = context.getLogger();

    // Register CLI commands
    context.registerCommand('linear', async (args) => {
      const subcommand = args[0];

      switch (subcommand) {
        case 'sync':
          await this.syncWithLinear(config);
          break;
        case 'import':
          await this.importFromLinear(config);
          break;
        case 'export':
          await this.exportToLinear(config);
          break;
        default:
          console.log('Usage: bootspring linear <sync|import|export>');
      }
    });

    // Register hook for PRD changes
    context.registerHook('prd.updated', async (event) => {
      if (config.autoSync) {
        await this.syncWithLinear(config);
      }
    });

    logger.info('Linear integration activated');
  }

  private async syncWithLinear(config: LinearConfig): Promise<void> {
    // Sync implementation
  }

  async deactivate(): Promise<void> {}
}

Plugin Configuration#

Configuration Schema#

// Plugin config in bootspring.config.js
module.exports = {
  plugins: {
    'linear-integration': {
      apiKey: process.env.LINEAR_API_KEY,
      teamId: 'TEAM',
      autoSync: true,
    },

    'my-agent-plugin': {
      enabled: true,
      customSetting: 'value',
    },
  },
};

Config Access#

// In plugin
const config = context.getConfig<MyPluginConfig>('');
const apiKey = context.getConfig<string>('apiKey');

Plugin Storage#

Storage Interface#

export interface PluginStorage {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
  list(): Promise<string[]>;
}

Storage Usage#

// In plugin
const storage = context.getStorage();

// Store data
await storage.set('lastSync', new Date().toISOString());

// Retrieve data
const lastSync = await storage.get<string>('lastSync');

Hook System#

Available Hooks#

Hook	Event
`agent.invoked`	Agent invocation started
`agent.completed`	Agent invocation finished
`skill.applied`	Skill pattern applied
`workflow.started`	Workflow began
`workflow.completed`	Workflow finished
`context.generated`	Context regenerated
`prd.updated`	PRD changed
`quality.passed`	Quality gate passed
`quality.failed`	Quality gate failed

Hook Handler#

interface HookHandler<T = unknown> {
  (event: T): Promise<void>;
}

// Usage
context.registerHook('agent.completed', async (event: AgentCompletedEvent) => {
  console.log(`Agent ${event.agent} completed in ${event.duration}ms`);

  // Track in external system
  await analytics.track('agent_completed', {
    agent: event.agent,
    duration: event.duration,
  });
});

Publishing Plugins#

Package Structure#

my-plugin/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts        # Plugin entry
│   ├── commands/       # CLI commands
│   ├── agents/         # Agent definitions
│   ├── skills/         # Skill definitions
│   └── hooks/          # Hook handlers
├── templates/          # File templates
├── tests/
└── README.md

Package.json#

{
  "name": "@bootspring/plugin-linear",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "keywords": ["bootspring-plugin"],
  "peerDependencies": {
    "@bootspring/plugin-sdk": "^1.0.0"
  },
  "bootspring": {
    "type": "plugin",
    "category": "integration"
  }
}

Publishing#

# Build
npm run build

# Test locally
bootspring plugin install ./my-plugin

# Publish to npm
npm publish

# Publish to Bootspring registry (optional)
bootspring plugin publish