# PROP: Plugin System for Extensible Provider/Adapter/Agent Integration

## Source
- **URL**: https://code.claude.com/docs/en/plugins (Claude Code plugin architecture), https://modelcontextprotocol.io/ (MCP standard), https://github.com/danielmiessler/Fabric (Fabric patterns -- file-based plugins), https://agents.md/ (AGENTS.md standard)
- **Author**: Anthropic (Claude Code plugins, MCP), danielmiessler (Fabric), AAIF (AGENTS.md)
- **Date**: 2025-2026

## Summary
Design a plugin system for iEvo with five contribution points: providers, adapters, agents, skills, and hooks. Plugins are directories with a `plugin.yaml` manifest and typed Python modules. The system uses Python Protocols for type-safe contracts, entry-point discovery, and versioned API. Modeled after Claude Code's plugin architecture (bundles agents + commands + MCP + hooks) and VS Code's contribution-point pattern, but adapted for Python and iEvo's domain.

## Relevance to iEvo
The "Android vs iPhone" problem: without a plugin system, every new provider, channel, or agent type requires core code changes. With plugins, the community can add Telegram support, Groq provider, or specialized agent types without touching iEvo core. Claude Code's plugin ecosystem (9,000+ extensions) proves the pattern works. iEvo's plugin system is simpler (five well-defined contribution points) and Python-native.

## Proposed Change

### 1. Plugin manifest
```yaml
# plugin.yaml
name: ievo-telegram
version: 0.1.0
description: Telegram channel adapter for iEvo
author: community
min_ievo_version: 0.5.0

contributions:
  adapters:
    - name: telegram
      module: telegram_adapter
      class: TelegramAdapter
  agents:
    - file: agents/telegram-moderator.md
```

### 2. Plugin discovery
- Search paths: `~/.ievo/plugins/`, `.ievo/plugins/`, installed pip packages with `ievo.plugins` entry point
- Discovery at startup: scan for `plugin.yaml`, validate manifest, register contributions
- Lazy loading: plugin code loaded only when its contribution is used

### 3. Contribution points

| Type | Protocol | Registration | Example |
|------|----------|-------------|---------|
| Provider | `ProviderPlugin` | `router.register_provider(name, plugin)` | Groq, Together AI |
| Adapter | `IOAdapter` | `adapters.register(name, plugin)` | Telegram, Discord |
| Agent | UAF `.md` file | Auto-discovered from `agents/` in plugin dir | Specialized agents |
| Skill | Skill `.md` file | Auto-discovered from `skills/` in plugin dir | Custom workflows |
| Hook | `HookPlugin` | `hooks.register(event, plugin)` | Custom pre/post actions |

### 4. Plugin API versioning
- Semantic versioning on the plugin API
- `min_ievo_version` in plugin manifest ensures compatibility
- Deprecation warnings for outdated plugin APIs

### 5. Built-in plugins (bundled)
Current marketplace content becomes the "official" plugin:
```
src/ievo/plugins/official/
  plugin.yaml
  agents/     # current marketplace agents
  skills/     # current marketplace skills
```

## Affected Components
- New: `src/ievo/plugins/` (package: loader, registry, manifest model)
- New: `src/ievo/plugins/official/` (bundled marketplace as plugin)
- Modified: `src/ievo/core/config.py` (plugin paths, enabled plugins)
- Modified: `src/ievo/marketplace/` (refactor to be discoverable as a plugin)
- Modified: `src/ievo/cli.py` (plugin discovery at startup)

## Scores
- Applicability: 4/5 (infrastructure investment that pays off when community grows)
- Effort: medium (plugin discovery and loading is well-understood; contribution points are clean)
- Impact: quality (extensibility without core changes), UX (community ecosystem)
