docs: Add extension contracts and ADRs

- extensions/EXTENSIONS.md: Extension system definition
- modules/CONTRACTS.md: Module interfaces
- modules/ADRS: Architectural decisions

Author: KooshaPari

extensions/EXTENSIONS.md

@@ -0,0 +1,115 @@
+# Extension Points for heliosCLI System
+
+## Overview
+
+Extensions allow heliosCLI (and harbor framework) to be extended without modifying core code. This document defines the extension system.
+
+## Extension Types
+
+### 1. CLI Commands
+
+```yaml
+# Extension point: codex_command
+# Location: clones/codex/cli/extensions/
+command:
+  name: my-extension
+  description: "My custom command"
+  arguments:
+    - name: input
+      type: string
+      required: true
+  handler: extensions.commands.my_extension
+```
+
+### 2. Harbor Adapters
+
+```yaml
+# Extension point: harbor_adapter  
+# Location: portage/harbor/adapters/
+adapter:
+  name: custom-backend
+  type: http
+  config:
+    base_url: https://api.example.com
+  handlers:
+    - on_request
+    - on_response
+```
+
+### 3. Portage Modules
+
+```python
+# Extension point: portage_module
+# Location: portage/portage_modules/
+class MyModule(PortageModule):
+    name = "my_module"
+    version = "1.0.0"
+    
+    def process(self, context):
+        pass
+```
+
+### 4. Template Renderers
+
+```python
+# Extension point: template_renderer
+class CustomRenderer(TemplateRenderer):
+    extensions = [".custom"]
+    
+    def render(self, template, context):
+        pass
+```
+
+## Extension Discovery
+
+Extensions are discovered via:
+1. `pyproject.toml` entry points
+2. Extension directories (configurable)
+3. External plugin registries
+
+## Loading Order
+
+1. Core extensions (built-in)
+2. System extensions (`~/.helios/extensions/`)
+3. Project extensions (`./helios_extensions/`)
+4. Dynamic (runtime loaded)
+
+## Example Extension Structure
+
+```
+extensions/
+├── pyproject.toml
+├── src/
+│   └── my_extension/
+│       ├── __init__.py
+│       ├── plugin.yaml
+│       ├── handlers.py
+│       └── tests/
+└── README.md
+```
+
+## plugin.yaml Schema
+
+```yaml
+name: my-extension
+version: 1.0.0
+helios_version: ">=2.0.0"
+entry_points:
+  commands:
+    - my-command
+  adapters:
+    - my-adapter
+dependencies:
+  - package>=1.0
+  - another-package
+```
+
+## Publishing Extensions
+
+```bash
+# Publish to PyPI
+helios extension publish
+
+# Install from PyPI
+helios extension install my-extension
+```

modules/ADRS.md

@@ -0,0 +1,43 @@
+# Architectural Decision Records
+
+## ADR-001: Plugin-Based Extension System
+
+**Status:** Proposed
+
+**Context:** heliosCLI needs to support extensions without core changes
+
+**Decision:** Use plugin architecture with entry points
+
+**Consequences:**
+- Extensions load at runtime
+- Clear contracts for extensions
+- Version compatibility checking
+
+---
+
+## ADR-002: Async-First Handlers
+
+**Status:** Proposed
+
+**Context:** I/O-bound operations require async support
+
+**Decision:** All handlers must support async execution
+
+**Consequences:**
+- Use asyncio throughout
+- Provide sync wrappers for compatibility
+
+---
+
+## ADR-003: Configuration-Driven Modules
+
+**Status:** Proposed
+
+**Context:** Modules need flexible configuration
+
+**Decision:** YAML/JSON config with validation
+
+**Consequences:**
+- Schema validation on load
+- Hot reload support
+- Environment variable interpolation

modules/CONTRACTS.md

@@ -0,0 +1,128 @@
+# Module Contracts
+
+## Base Module Interface
+
+All modules must implement this interface:
+
+```python
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+class Module(ABC):
+    """Base module interface."""
+    
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Module name."""
+        pass
+    
+    @property
+    @abstractmethod
+    def version(self) -> str:
+        """Module version."""
+        pass
+    
+    @property
+    def dependencies(self) -> list[str]:
+        """Module dependencies."""
+        return []
+    
+    @abstractmethod
+    def initialize(self, config: Dict[str, Any]) -> None:
+        """Initialize module with configuration."""
+        pass
+    
+    @abstractmethod
+    def execute(self, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute module logic."""
+        pass
+    
+    @abstractmethod
+    def shutdown(self) -> None:
+        """Cleanup resources."""
+        pass
+    
+    def validate(self) -> bool:
+        """Validate module configuration."""
+        return True
+```
+
+## Handler Contract
+
+```python
+class Handler(ABC):
+    """Handler interface for processing requests."""
+    
+    @property
+    def event_types(self) -> list[str]:
+        """Events this handler subscribes to."""
+        return []
+    
+    async def handle(self, event: Event) -> Response:
+        """Process event and return response."""
+        pass
+    
+    def cleanup(self) -> None:
+        """Release resources."""
+        pass
+```
+
+## Adapter Contract
+
+```python
+class Adapter(ABC):
+    """Adapter for external systems."""
+    
+    @property
+    def name(self) -> str:
+        pass
+    
+    async def connect(self) -> None:
+        pass
+    
+    async def disconnect(self) -> None:
+        pass
+    
+    async def send(self, message: Message) -> Response:
+        pass
+    
+    def health_check(self) -> HealthStatus:
+        pass
+```
+
+## Validator Contract
+
+```python
+class Validator(ABC):
+    """Input/output validation."""
+    
+    @property
+    def schema(self) -> dict:
+        pass
+    
+    def validate(self, data: Any) -> ValidationResult:
+        pass
+    
+    def validate_response(self, response: Any) -> bool:
+        pass
+```
+
+## Registry Pattern
+
+```python
+class ModuleRegistry:
+    """Central module registration."""
+    
+    def register(self, module: Module) -> None:
+        ...
+    
+    def get(self, name: str) -> Module:
+        ...
+    
+    def list_modules(self) -> list[str]:
+        ...
+    
+    def unregister(self, name: str) -> None:
+        ...
+```