docs: add comprehensive capabilities architecture documentation
Created detailed documentation for capabilities concept and integration: - CAPABILITIES_ARCHITECTURE.md: Full guide on separation of concerns - CAPABILITIES_QUICK_REFERENCE.md: Quick reference for common tasks - Updated docs/README.md to reference new documentation Ensures future sessions respect capability boundaries and use separate Claude instances for capability development. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
184
docs/CAPABILITIES_QUICK_REFERENCE.md
Normal file
184
docs/CAPABILITIES_QUICK_REFERENCE.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user