# Plugin System API Specification

**Version**: v1.2.3 | **Status**: Stable | **Last Updated**: March 2026

## 1. Overview
The `plugin_system` module enables dynamic extension of Codomyrmex capabilities. It discovers, validates, and loads extensions at runtime.

## 2. Core Components

### 2.1 Management
- **`PluginManager`**: High-level orchestrator.
- **`PluginLoader`**: Handles file system scanning and import.
- **`PluginRegistry`**: Tracks active plugins.
- **`PluginValidator`**: Ensures plugins meet safety and interface requirements.

### 2.2 Data Structures
- **`Plugin`**: Represents a loaded plugin instance.
- **`PluginInfo`**: Metadata (name, version, author).
- **`PluginType` (Enum)**: Categorization of extensions.
- **`PluginState` (Enum)**: Lifecycle status (LOADED, ACTIVE, ERROR).

## 3. Usage Example

```python
from codomyrmex.plugin_system import PluginManager

manager = PluginManager(plugin_dirs=["./plugins"])
manager.discover_plugins()
manager.load_all()

# Access extension
ext = manager.get_extension("my_plugin")
```
