markitect-main/docs/CAPABILITIES_QUICK_REFERENCE.md

# 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-main/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-main` |
| **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-main
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-main

# 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-main/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-main

# 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)