docs: Add governance model and plugin system

- GOVERNANCE.md: Project structure and module definitions
- plugins/protocol.py: Plugin system protocol

Author: KooshaPari

GOVERNANCE.md

@@ -0,0 +1,115 @@
+# heliosHarness Governance Model
+
+## Purpose
+
+**heliosHarness** is a private research & planning monorepo for developing, analyzing, and organizing the heliosCLI system architecture. It does **not** contain production code - instead, it researches, prototypes, and defines how to extend other projects.
+
+## Project Shelf Model
+
+Like `kush/` - heliosHarness serves as a **project shelf** for organizing dependencies and research.
+
+## Module Categories
+
+### 1. Clones (forked external projects)
+```
+clones/
+├── codex/          # Forked Codex CLI research
+├── goose/           # Forked Goose research  
+├── cline/           # Forked Cline research
+├── aider/           # Forked Aider research
+├── opencode/         # Forked OpenCode research
+└── [other forks/]
+```
+
+### 2. Extensions (plugin systems)
+```
+extensions/
+├── codex-plugins/      # Codex CLI extensibility
+├── harbor-plugins/      # Harbor framework plugins
+├── portage-plugins/     # Portage module system
+└── [project]-plugins/
+```
+
+### 3. Plugins (modular extension system)
+```
+plugins/
+├── protocol/        # Plugin protocol definitions
+├── loader/          # Plugin loader/runtimes
+├── registry/         # Plugin registry
+└── templates/       # Plugin templates
+```
+
+### 4. Submodules (component definitions)
+```
+modules/
+├── harness_core/    # Core harness interfaces
+├── adapters/        # Adapter definitions
+├── handlers/        # Handler specs
+└── validators/      # Validation contracts
+```
+
+### 5. Research & Analysis
+```
+research/
+├── [domain]-analysis/   # Research documents
+├── [project]-specs/     # Specification documents
+└── prototypes/           # Prototype code/tests
+```
+
+## Extension Pattern
+
+### Plugin Contract
+```python
+# plugins/protocol/base.py
+class Plugin(Protocol):
+    name: str
+    version: str
+    
+    def initialize(self, config: dict) -> None: ...
+    def execute(self, ctx: Context) -> Result: ...
+    def shutdown(self) -> None: ...
+```
+
+### Extension Points
+- **codex extensions** → Extend heliosCLI
+- **harbor plugins** → Harbor framework integration
+- **portage modules** → Portage package system
+- **custom adapters** → External system connectors
+
+## Governance Rules
+
+1. **No production code** - Research/prototypes only
+2. **Clear provenance** - Document source projects
+3. **Plugin-first** - Use extension patterns over hardcoded deps
+4. **Modular** - Independent, composable components
+5. **Documented** - ADRs for architectural decisions
+
+## Directory Structure
+
+```
+heliosHarness/
+├── clones/           # Forked external projects
+├── plugins/          # Plugin system
+├── extensions/       # Extension definitions
+├── modules/          # Component interfaces
+├── research/         # Analysis documents
+├── prototypes/       # Experimental code
+├── specs/            # Specification documents  
+└── artifacts/        # Generated artifacts
+```
+
+## Plugin Registry Example
+
+```yaml
+# plugins/registry.yaml
+plugins:
+  - name: codex-extension
+    type: helioscli-extension
+    source: clones/codex
+    path: extensions/codex-plugins/
+    
+  - name: harbor-adapter  
+    type: harbor-plugin
+    source: portage/harbor
+    path: extensions/harbor-plugins/
+```

plugins/protocol.py

@@ -0,0 +1,141 @@
+"""Plugin system for heliosHarness extensions.
+
+Defines the plugin protocol and extension points for modular code.
+"""
+
+from typing import Protocol, runtime_checkable
+from dataclasses import dataclass
+from enum import Enum
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class PluginType(Enum):
+    """Types of plugins."""
+    HELIOS_CLI_EXTENSION = "helioscli_extension"
+    HARBOR_PLUGIN = "harbor_plugin"
+    PORTAGE_MODULE = "portage_module"
+    ADAPTER = "adapter"
+    TEMPLATE = "template"
+
+
+@dataclass
+class PluginMetadata:
+    """Plugin metadata."""
+    name: str
+    version: str
+    plugin_type: PluginType
+    source_project: str
+    description: str = ""
+    author: str = ""
+    tags: list[str] = None
+    
+    def __post_init__(self):
+        if self.tags is None:
+            self.tags = []
+
+
+@dataclass
+class PluginConfig:
+    """Plugin configuration."""
+    enabled: bool = True
+    priority: int = 100
+    settings: dict = None
+    
+    def __post_init__(self):
+        if self.settings is None:
+            self.settings = {}
+
+
+@runtime_checkable
+class Plugin(Protocol):
+    """Base plugin protocol."""
+    
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Plugin metadata."""
+        ...
+    
+    def initialize(self, config: dict) -> None:
+        """Initialize the plugin with configuration."""
+        ...
+    
+    def execute(self, *args, **kwargs):
+        """Execute the plugin."""
+        ...
+    
+    def shutdown(self) -> None:
+        """Cleanup resources."""
+        ...
+
+
+    def validate(self) -> bool:
+        """Validate plugin setup."""
+        return True
+
+
+class PluginLoader:
+    """Loads and manages plugins."""
+    
+    def __init__(self, plugin_dir: Path = None):
+        self.plugin_dir = plugin_dir or Path("plugins")
+        self._plugins: dict[str, Plugin] = {}
+        self._metadata: dict[str, PluginMetadata] = {}
+    
+    def discover(self) -> list[PluginMetadata]:
+        """Discover available plugins."""
+        discovered = []
+        
+        if not self.plugin_dir.exists():
+            return discovered
+            
+        for plugin_path in self.plugin_dir.rglob("plugin.yaml"):
+            with open(plugin_path) as f:
+                # Parse YAML and create metadata
+                pass
+        
+        return discovered
+    
+    def load(self, name: str) -> Plugin:
+        """Load a plugin by name."""
+        if name in self._plugins:
+            return self._plugins[name]
+        
+        # Dynamic import
+        module = __import__(f"plugins.{name}", fromlist=["Plugin"])
+        plugin = module.Plugin()
+        
+        self._plugins[name] = plugin
+        return plugin
+    
+    def unload(self, name: str) -> None:
+        """Unload a plugin."""
+        if name in self._plugins:
+            self._plugins[name].shutdown()
+            del self._plugins[name]
+
+
+class ExtensionRegistry:
+    """Registry for extension points."""
+    
+    def __init__(self):
+        self._extensions: dict[str, list[type] = {}
+    
+    def register(self, extension_point: str, extension: type):
+        """Register an extension for a point."""
+        if extension_point not in self._extensions:
+            self._extensions[extension_point] = []
+        self._extensions[extension_point].append(extension)
+    
+    def get_extensions(self, extension_point: str) -> list[type]:
+        """Get all extensions for a point."""
+        return self._extensions.get(extension_point, [])
+
+
+# Extension points
+EXTENSION_POINTS = {
+    "codex_command": "Codex CLI command extension",
+    "harbor_adapter": "Harbor system adapter",
+    "portage_module": "Portage module extension",
+    "template_renderer": "Template renderer extension",
+}