Plugin Developer Guide — documentation for creating external plugins #31

New issue

Open

opened 2026-02-20 10:57:12 +00:00 by doxios · 0 comments

doxios commented

2026-02-20 10:57:12 +00:00

Collaborator

Summary

Comprehensive documentation for developers creating cobot plugins, covering the full plugin lifecycle from skeleton to distribution.

Background

From discussion (2026-02-13): As we move plugins to external repos (like cobot-telegram), we need clear documentation for:

How the plugin system works
How to create a new plugin
How to extend the CLI
How to participate in the wizard
How to publish/distribute plugins

Proposed Sections

1. Plugin Basics

PluginMeta fields (id, version, capabilities, dependencies)
Lifecycle: configure() → start() → stop()
Hooks: on_message_received, on_before_llm_call, etc.

2. Extension Points

Defining extension points: extension_points=["myPlugin.on_event"]
Implementing extension points: implements={"other.point": "my_method"}
The communication → session → channel pattern

3. CLI Extension

def register_commands(self, cli: click.Group) -> None:
    @cli.group()
    def myplugin():
        """My plugin commands."""
        pass
    
    @myplugin.command()
    def status(self):
        click.echo("Running!")

4. Wizard Integration

def wizard_section(self) -> dict | None:
    return {
        "key": "myplugin",
        "name": "My Plugin",
        "description": "Does something cool"
    }

def wizard_configure(self, config: dict) -> dict:
    token = click.prompt("API token")
    return {"token": token}

5. External Plugin Distribution

Repo structure (cobot_myplugin/plugin.py)
pyproject.toml with entry points
Installation: pip install git+https://...
Plugin discovery mechanism

6. Testing Plugins

Mocking the registry
Testing hooks
Integration test patterns

Location

docs/plugin-development.md in ultanio/cobot

PR #1 (CLI extension + wizard)
bridio/cobot-telegram as reference implementation

Filed by Doxios 🦊

## Summary Comprehensive documentation for developers creating cobot plugins, covering the full plugin lifecycle from skeleton to distribution. ## Background From discussion (2026-02-13): As we move plugins to external repos (like `cobot-telegram`), we need clear documentation for: - How the plugin system works - How to create a new plugin - How to extend the CLI - How to participate in the wizard - How to publish/distribute plugins ## Proposed Sections ### 1. Plugin Basics - `PluginMeta` fields (id, version, capabilities, dependencies) - Lifecycle: `configure()` → `start()` → `stop()` - Hooks: `on_message_received`, `on_before_llm_call`, etc. ### 2. Extension Points - Defining extension points: `extension_points=["myPlugin.on_event"]` - Implementing extension points: `implements={"other.point": "my_method"}` - The communication → session → channel pattern ### 3. CLI Extension ```python def register_commands(self, cli: click.Group) -> None: @cli.group() def myplugin(): """My plugin commands.""" pass @myplugin.command() def status(self): click.echo("Running!") ``` ### 4. Wizard Integration ```python def wizard_section(self) -> dict | None: return { "key": "myplugin", "name": "My Plugin", "description": "Does something cool" } def wizard_configure(self, config: dict) -> dict: token = click.prompt("API token") return {"token": token} ``` ### 5. External Plugin Distribution - Repo structure (`cobot_myplugin/plugin.py`) - `pyproject.toml` with entry points - Installation: `pip install git+https://...` - Plugin discovery mechanism ### 6. Testing Plugins - Mocking the registry - Testing hooks - Integration test patterns ## Location `docs/plugin-development.md` in ultanio/cobot ## Related - PR #1 (CLI extension + wizard) - `bridio/cobot-telegram` as reference implementation --- *Filed by Doxios 🦊*