markitect-main/docs/CAPABILITIES_QUICK_REFERENCE.md

Capabilities Quick Reference

⚠️ Critical: Read Capabilities Architecture for full details.

Core Rules

🚫 NEVER Edit Capabilities from Main Repo

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

# 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

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

# 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

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

# ✅ Correct - Import from capability package
from testdrive_jsui import TestDriveJSUIEngine

engine = TestDriveJSUIEngine()

Dependency Declaration

# pyproject.toml
dependencies = [
    "testdrive-jsui @ file:./capabilities/testdrive-jsui",
]

Plugin Self-Declaration

# ✅ 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"

git submodule update --init --recursive

"Import error: No module named 'capability_name'"

pip install -e ./capabilities/capability-name
# or
pip install -e .  # Install all dependencies

"Merge conflict in submodule"

# 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