diff --git a/docs/CAPABILITIES_QUICK_REFERENCE.md b/docs/CAPABILITIES_QUICK_REFERENCE.md
new file mode 100644
index 00000000..68878d17
--- /dev/null
+++ b/docs/CAPABILITIES_QUICK_REFERENCE.md
@@ -0,0 +1,184 @@
+# Capabilities Quick Reference
+
+**⚠️ Critical:** Read [Capabilities Architecture](architecture/CAPABILITIES_ARCHITECTURE.md) for full details.
+
+## Core Rules
+
+### 🚫 **NEVER** Edit Capabilities from Main Repo
+
+```bash
+# ❌ WRONG - Don't edit capability files from main repo
+cd /home/worsch/markitect_project/capabilities/testdrive-jsui
+vim src/testdrive_jsui/core.py  # DON'T DO THIS!
+
+# ✅ CORRECT - Use separate Claude instance/session
+# Open new terminal/Claude instance:
+git clone http://gitea/coulomb/testdrive-jsui.git /path/to/work
+cd /path/to/work/testdrive-jsui
+# Make changes, commit, push
+```
+
+### 📦 Capabilities are Git Submodules
+
+- Each capability = separate git repository
+- Located in `capabilities/` as submodules
+- Independent development lifecycle
+- Own versioning and releases
+
+### 🔀 Use Separate Claude Instances
+
+| Session | Purpose | Location |
+|---------|---------|----------|
+| **Main Repo** | Integration, configuration | `/home/worsch/markitect_project` |
+| **Capability** | Feature development, bugs | Separate clone or `capabilities/capability-name` |
+
+**Why?** Prevents accidental cross-contamination and respects repository boundaries.
+
+## Common Tasks
+
+### Update Capability After Changes
+
+```bash
+# After pushing changes to capability repo
+cd /home/worsch/markitect_project
+git submodule update --remote capabilities/testdrive-jsui
+git add capabilities/testdrive-jsui
+git commit -m "chore: update testdrive-jsui to latest"
+git push
+```
+
+### Add New Capability
+
+```bash
+cd /home/worsch/markitect_project
+
+# Add as submodule
+git submodule add http://gitea/coulomb/new-capability.git capabilities/new-capability
+
+# Add to pyproject.toml dependencies
+echo '    "new-capability @ file:./capabilities/new-capability",' >> pyproject.toml
+
+# Commit
+git add .gitmodules capabilities/new-capability pyproject.toml
+git commit -m "feat: add new-capability submodule"
+```
+
+### Work on Capability Feature
+
+```bash
+# Option 1: In submodule directory (careful!)
+cd /home/worsch/markitect_project/capabilities/testdrive-jsui
+git checkout -b feature-branch
+# make changes
+git commit -m "feat: new feature"
+git push origin feature-branch
+
+# Option 2: Separate clone (recommended)
+cd ~/projects
+git clone http://gitea/coulomb/testdrive-jsui.git
+cd testdrive-jsui
+git checkout -b feature-branch
+# make changes
+git commit -m "feat: new feature"
+git push origin feature-branch
+```
+
+### Check Capability Status
+
+```bash
+cd /home/worsch/markitect_project
+
+# List all capabilities
+make capabilities-list
+
+# Check submodule status
+git submodule status
+
+# See which commit each capability is at
+git submodule foreach 'git log --oneline -1'
+```
+
+## Integration Patterns
+
+### Python Import
+
+```python
+# ✅ Correct - Import from capability package
+from testdrive_jsui import TestDriveJSUIEngine
+
+engine = TestDriveJSUIEngine()
+```
+
+### Dependency Declaration
+
+```toml
+# pyproject.toml
+dependencies = [
+    "testdrive-jsui @ file:./capabilities/testdrive-jsui",
+]
+```
+
+### Plugin Self-Declaration
+
+```python
+# ✅ Good - Plugin declares its own location
+def get_plugin_source_dir(self) -> Path:
+    return Path(__file__).parent.parent.parent / "capabilities" / "testdrive-jsui"
+
+# ❌ Bad - Hardcoded in main repo
+if plugin_name == 'testdrive-jsui':
+    return Path('capabilities/testdrive-jsui')
+```
+
+## Troubleshooting
+
+### "Submodule not initialized"
+
+```bash
+git submodule update --init --recursive
+```
+
+### "Import error: No module named 'capability_name'"
+
+```bash
+pip install -e ./capabilities/capability-name
+# or
+pip install -e .  # Install all dependencies
+```
+
+### "Merge conflict in submodule"
+
+```bash
+# Don't resolve in main repo!
+# Go to capability repo and resolve there
+cd capabilities/testdrive-jsui
+git pull origin main
+# Resolve conflicts, commit, push
+
+cd ../..
+git submodule update --remote capabilities/testdrive-jsui
+git add capabilities/testdrive-jsui
+git commit -m "chore: update testdrive-jsui after conflict resolution"
+```
+
+## Current Capabilities
+
+| Capability | Type | Repository | Status |
+|------------|------|------------|--------|
+| **testdrive-jsui** | Rendering Engine | `coulomb/testdrive-jsui` | ✅ Submodule |
+| **issue-facade** | CLI Tool | `coulomb/issue-facade` | ✅ Submodule |
+| **kaizen-agentic** | Framework | `coulomb/kaizen-agentic` | ✅ Submodule |
+| **release-management** | Tool | Local | 📦 To migrate |
+| **markitect-content** | Library | Local | 📦 To migrate |
+
+## Key Principles
+
+1. **Separation of Concerns** - Main repo doesn't modify capabilities
+2. **Independent Development** - Each capability has own lifecycle
+3. **Interface-Based Integration** - Use documented APIs only
+4. **Version Control** - Git submodules for dependency management
+5. **Session Isolation** - Separate Claude instances per repository
+
+---
+
+**📖 Full Documentation:** [Capabilities Architecture](architecture/CAPABILITIES_ARCHITECTURE.md)
diff --git a/docs/README.md b/docs/README.md
index 7f6b36ce..c56c15ae 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,8 +7,9 @@ Welcome to the MarkiTect documentation. This directory contains comprehensive do
 ### 📐 Architecture Documentation (`architecture/`)
 Deep technical documentation about system design, performance, and implementation details.
 
+- **[Capabilities Architecture](architecture/CAPABILITIES_ARCHITECTURE.md)** - **Critical:** How capabilities work as independent git submodules and separation of concerns
 - **[Caching System](architecture/caching-system.md)** - Why and how MarkiTect's AST caching delivers 60-85% performance improvements
-- *Coming soon: Database Schema, CLI Architecture, Plugin System*
+- *Coming soon: Database Schema, CLI Architecture*
 
 ### 👥 User Guides (`user-guides/`)
 End-user documentation for working with MarkiTect CLI and features.
diff --git a/docs/architecture/CAPABILITIES_ARCHITECTURE.md b/docs/architecture/CAPABILITIES_ARCHITECTURE.md
new file mode 100644
index 00000000..c1f19fa2
--- /dev/null
+++ b/docs/architecture/CAPABILITIES_ARCHITECTURE.md
@@ -0,0 +1,453 @@
+# Capabilities Architecture
+
+## Overview
+
+MarkiTect uses a **capabilities-based architecture** where functionality is organized into independent, reusable packages called **capabilities**. Each capability is a self-contained git submodule with its own repository, enabling independent development, versioning, and reuse across projects.
+
+## Core Principles
+
+### 1. **Separation of Concerns**
+
+**Critical Rule:** The main repository (`markitect_project`) **MUST NOT** directly modify capability code.
+
+- ✅ **DO**: Use capabilities as dependencies
+- ✅ **DO**: Configure capabilities through documented interfaces
+- ✅ **DO**: Report issues and feature requests to capability repos
+- ❌ **DON'T**: Edit capability code from the main repo
+- ❌ **DON'T**: Make commits directly in capability subdirectories
+- ❌ **DON'T**: Bypass the submodule boundary
+
+**Why?** Capabilities are independent repositories. Direct modifications create:
+- Merge conflicts when syncing with upstream
+- Broken dependency management
+- Loss of independent versioning
+- Confusion about source of truth
+
+### 2. **Git Submodule Architecture**
+
+Capabilities are integrated as **git submodules**, not regular directories:
+
+```
+markitect_project/
+├── .gitmodules                    # Submodule configuration
+├── capabilities/
+│   ├── testdrive-jsui/           # Git submodule → separate repo
+│   ├── issue-facade/             # Git submodule → separate repo
+│   ├── kaizen-agentic/           # Git submodule → separate repo
+│   ├── markitect-content/        # Local capability (legacy)
+│   └── release-management/       # Local capability (legacy)
+```
+
+**Submodule vs Local Capabilities:**
+- **Submodules**: Independent git repositories, separate development lifecycle
+- **Local**: Part of main repo, shared lifecycle (being phased out)
+
+**Target State:** All capabilities should eventually be submodules.
+
+### 3. **Independent Development Lifecycle**
+
+Each capability has its own:
+- ✅ Git repository on gitea
+- ✅ Version numbering (semantic versioning)
+- ✅ Issue tracking and roadmap
+- ✅ Testing and CI/CD pipeline
+- ✅ Documentation and README
+- ✅ Contributors and maintainers
+
+### 4. **Interface-Based Integration**
+
+Capabilities expose **stable interfaces** to the main project:
+
+```python
+# markitect uses capability through documented interface
+from testdrive_jsui import TestDriveJSUIEngine
+
+engine = TestDriveJSUIEngine()
+engine.render_document(content, mode='edit', config=config)
+```
+
+**Integration Points:**
+1. **Python Package Interface**: Clean import and API
+2. **Configuration**: Via `pyproject.toml` dependencies
+3. **Plugin System**: Via plugin registration and metadata
+4. **Makefile Targets**: Via capability discovery system
+
+## Development Workflow
+
+### Working on Capabilities
+
+**Rule:** Each capability is developed in **its own Claude Code session**.
+
+#### Main Repository Session
+```bash
+# In markitect_project/
+cd /home/worsch/markitect_project
+
+# Main repo tasks:
+# - Integrate capabilities
+# - Update dependencies
+# - Configure capability usage
+# - Test integration points
+```
+
+#### Capability Session
+```bash
+# In capability repository
+cd /home/worsch/markitect_project/capabilities/testdrive-jsui
+
+# OR clone separately
+git clone http://gitea/coulomb/testdrive-jsui.git
+cd testdrive-jsui
+
+# Capability tasks:
+# - Implement features
+# - Fix bugs
+# - Write tests
+# - Update documentation
+# - Make releases
+```
+
+### Recommended Session Pattern
+
+**Scenario: Need to add feature to testdrive-jsui**
+
+1. **Open separate Claude instance** for testdrive-jsui
+   ```bash
+   # In new terminal/session
+   cd /path/to/testdrive-jsui
+   # Work on feature
+   git commit -m "feat: new feature"
+   git push origin main
+   ```
+
+2. **Update main project** (different Claude instance)
+   ```bash
+   cd /home/worsch/markitect_project
+   git submodule update --remote capabilities/testdrive-jsui
+   git commit -m "chore: update testdrive-jsui submodule"
+   ```
+
+**Why separate instances?**
+- Clear context boundaries
+- Prevents accidental cross-contamination
+- Respects repository independence
+- Better commit hygiene
+
+### Updating Submodules
+
+When a capability releases a new version:
+
+```bash
+# In main repo
+cd /home/worsch/markitect_project
+
+# Update specific capability
+cd capabilities/testdrive-jsui
+git pull origin main
+cd ../..
+git add capabilities/testdrive-jsui
+git commit -m "chore: update testdrive-jsui to v1.2.0"
+
+# Or update all capabilities
+git submodule update --remote
+git commit -am "chore: update all capabilities"
+```
+
+### Adding New Capabilities
+
+```bash
+# 1. Create capability repository on gitea
+# http://gitea/coulomb/new-capability
+
+# 2. Add as submodule to main repo
+cd /home/worsch/markitect_project
+git submodule add http://gitea/coulomb/new-capability.git capabilities/new-capability
+
+# 3. Add dependency to pyproject.toml
+# dependencies = [
+#     "new-capability @ file:./capabilities/new-capability"
+# ]
+
+# 4. Commit submodule addition
+git commit -m "feat: add new-capability as submodule"
+```
+
+## Dependency Management
+
+Capabilities are declared in `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    # Core dependencies
+    "markdown-it-py",
+    "click>=8.0.0",
+
+    # Capabilities (file-based dependencies)
+    "release-management @ file:./capabilities/release-management",
+    "testdrive-jsui @ file:./capabilities/testdrive-jsui",
+    "issue-facade @ file:./capabilities/issue-facade",
+]
+```
+
+**Pattern for Capabilities:**
+```toml
+"capability-name @ file:./capabilities/capability-name"
+```
+
+This enables:
+- ✅ pip install with editable dependencies
+- ✅ Proper package resolution
+- ✅ Clean imports in code
+- ✅ Development mode support
+
+## Capability Structure
+
+Each capability should follow this structure:
+
+```
+capability-name/
+├── README.md                      # Comprehensive documentation
+├── pyproject.toml                 # Package configuration
+├── Makefile                       # Build and test automation
+├── .gitignore                     # Git ignore rules
+├── src/capability_name/           # Python package source
+│   ├── __init__.py
+│   ├── core/                      # Core functionality
+│   ├── utils/                     # Utilities
+│   └── testing/                   # Testing infrastructure
+├── js/                            # JavaScript (if applicable)
+│   ├── components/
+│   ├── controls/
+│   └── tests/
+├── static/                        # Static assets (if applicable)
+│   ├── css/
+│   ├── images/
+│   └── templates/
+├── tests/                         # Python tests
+│   └── test_*.py
+└── docs/                          # Additional documentation
+    ├── API.md
+    └── USAGE.md
+```
+
+### Required Files
+
+1. **README.md** - Must include:
+   - Purpose and description
+   - Installation instructions
+   - Usage examples
+   - API documentation
+   - Integration guide
+
+2. **pyproject.toml** - Must define:
+   - Package metadata
+   - Dependencies
+   - Build system
+   - Entry points
+
+3. **Makefile** - Should include:
+   - help target
+   - test targets
+   - install/setup targets
+   - capability-info target (for discovery)
+
+## Plugin System Integration
+
+For capabilities that provide plugins (like testdrive-jsui):
+
+### Plugin Self-Declaration
+
+```python
+class TestDriveJSUIEngine(RenderingEnginePlugin):
+    """Plugin declares its own location - no hardcoded paths."""
+
+    def get_plugin_source_dir(self) -> Path:
+        """Plugin knows where it lives."""
+        return Path(__file__).parent.parent.parent / "capabilities" / "testdrive-jsui"
+
+    def get_asset_paths(self) -> Dict[str, Path]:
+        """Plugin declares its asset structure."""
+        base = self.get_plugin_source_dir()
+        return {
+            'js': base / 'js',
+            'css': base / 'static' / 'css',
+            'templates': base / 'static' / 'templates',
+        }
+```
+
+### Plugin Discovery
+
+The main repo uses **generic discovery** - no hardcoded capability names:
+
+```python
+# ✅ Good: Generic discovery
+if hasattr(engine, 'get_plugin_source_dir'):
+    source_dir = engine.get_plugin_source_dir()
+
+# ❌ Bad: Hardcoded capability names
+if engine_name == 'testdrive-jsui':
+    source_dir = Path('capabilities/testdrive-jsui')
+```
+
+## Testing Strategy
+
+### Capability Tests
+Each capability tests **in isolation**:
+
+```bash
+cd capabilities/testdrive-jsui
+pytest tests/
+npm test
+```
+
+### Integration Tests
+Main repo tests **integration points**:
+
+```python
+# tests/integration/test_capabilities.py
+def test_testdrive_jsui_integration():
+    """Test that testdrive-jsui integrates correctly."""
+    engine = TestDriveJSUIEngine()
+    result = engine.render_document(sample_content, 'edit', config)
+    assert result is not None
+```
+
+### Test Boundaries
+- **Capability tests**: Internal functionality, unit tests, component tests
+- **Main repo tests**: Integration, configuration, plugin discovery
+
+## Migration Path
+
+### Converting Local Capability to Submodule
+
+1. **Create separate git repo**
+   ```bash
+   cd /tmp
+   cp -r markitect_project/capabilities/capability-name capability-name
+   cd capability-name
+   git init
+   git add .
+   git commit -m "Initial commit"
+   git remote add origin http://gitea/coulomb/capability-name.git
+   git push -u origin main
+   ```
+
+2. **Remove from main repo**
+   ```bash
+   cd markitect_project
+   git rm -rf capabilities/capability-name
+   git commit -m "chore: remove capability-name for submodule conversion"
+   ```
+
+3. **Add as submodule**
+   ```bash
+   git submodule add http://gitea/coulomb/capability-name.git capabilities/capability-name
+   git commit -m "feat: add capability-name as submodule"
+   ```
+
+## Best Practices
+
+### DO ✅
+
+1. **Develop capabilities independently**
+   - Use separate Claude instances
+   - Maintain clear context boundaries
+   - Follow semantic versioning
+
+2. **Use documented interfaces**
+   - Import via Python packages
+   - Use plugin APIs
+   - Follow configuration patterns
+
+3. **Test integration points**
+   - Verify capability imports
+   - Test plugin discovery
+   - Validate configurations
+
+4. **Update submodules explicitly**
+   - Pull capability changes deliberately
+   - Review updates before committing
+   - Update main repo pointer
+
+5. **Document integration**
+   - How to use the capability
+   - Configuration options
+   - Example usage
+
+### DON'T ❌
+
+1. **Edit capability code from main repo**
+   - Opens separate repo/instance instead
+   - Respects submodule boundary
+   - Maintains clean separation
+
+2. **Hardcode capability paths**
+   - Use self-declaration instead
+   - Generic discovery patterns
+   - Interface-based access
+
+3. **Create circular dependencies**
+   - Main depends on capabilities
+   - Capabilities should NOT depend on main
+   - Keep dependency graph acyclic
+
+4. **Bypass submodule system**
+   - Don't manually copy files
+   - Use git submodule commands
+   - Respect version control
+
+## Troubleshooting
+
+### Submodule not updated
+
+```bash
+# Pull latest from capability repo
+cd capabilities/testdrive-jsui
+git pull origin main
+
+# Update main repo pointer
+cd ../..
+git add capabilities/testdrive-jsui
+git commit -m "chore: update testdrive-jsui"
+```
+
+### Import errors
+
+```bash
+# Reinstall capabilities
+pip install -e .
+
+# Or specific capability
+pip install -e ./capabilities/testdrive-jsui
+```
+
+### Merge conflicts in submodules
+
+```bash
+# Don't merge in submodule from main repo!
+# Instead, go to capability repo directly
+
+cd /path/to/separate/testdrive-jsui
+# or
+cd capabilities/testdrive-jsui
+
+# Resolve conflicts there
+git pull origin main
+# fix conflicts
+git push origin main
+
+# Then update main repo
+cd ../../
+git submodule update --remote
+```
+
+## See Also
+
+- [Agent: Capability Manager](../../agents/agent-capability-manager.md) - Automated capability management
+- [Plugin System](../PLUGIN_SYSTEM.md) - Plugin architecture documentation
+- [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) - Official git submodules guide
+
+---
+
+**Remember:** Capabilities are **independent projects**. Treat them with the same respect you'd give any external dependency - use their interfaces, don't modify their internals.