markitect-main/CLAUDE_CAPABILITY_REFERENCE.md

# Claude Capability Reference - Quick Lookup

> **Essential reference for Claude to prevent code duplication and ensure proper capability usage**

## 🚨 **BEFORE IMPLEMENTING: CHECK EXISTING CAPABILITIES**

### Issue Management ➜ USE `issue-facade/`
```bash
# ✅ DO: Use existing issue facade
cd issue-facade && python -m cli.main list
cd issue-facade && python -m cli.main show 42
cd issue-facade && python -m cli.main create "Title" "Description"

# ❌ DON'T: Implement custom issue tracking
# ❌ DON'T: Create new CLI commands for issues
# ❌ DON'T: Build custom Gitea/GitHub API clients
```

### Content Processing ➜ USE `capabilities/markitect-content/`
```python
# ✅ DO: Use existing content capability
from capabilities.markitect_content import ContentParser, ContentStats
parser = ContentParser()
stats = ContentStats()

# ❌ DON'T: Reimplement markdown parsing
# ❌ DON'T: Create new content statistics functions
# ❌ DON'T: Duplicate frontmatter/tailmatter handling
```

### Utilities ➜ USE `capabilities/markitect-utils/`
```python
# ✅ DO: Use existing utilities
from capabilities.markitect_utils import utility_function

# ❌ DON'T: Recreate common utility functions
# ❌ DON'T: Duplicate helper functions
```

### Documentation ➜ USE `wiki/`
```markdown
# ✅ DO: Reference existing documentation
See wiki/ComposableRepositoryParadigm.md
See wiki/MarkdownMatters.md

# ❌ DON'T: Create duplicate documentation
# ❌ DON'T: Rewrite architectural decisions
```

## 🔍 **CAPABILITY DISCOVERY COMMANDS**

### Quick Capability Check
```bash
# Check all capabilities
ls -la capabilities/     # Local capabilities
ls -la issue-facade/     # Issue management capability
ls -la wiki/             # Documentation capability
cat CAPABILITY_REGISTRY.md  # Full registry

# Verify functionality exists
grep -r "function_name" capabilities/
grep -r "class_name" issue-facade/
```

### Interface Documentation
- **Issue Facade**: `issue-facade/README.md`
- **Content Processing**: `capabilities/markitect-content/README.md`
- **Utilities**: `capabilities/markitect-utils/README.md`
- **Documentation**: `wiki/` (multiple files)

## ⚡ **QUICK DECISION TREE**

1. **Need Issue Management?** ➜ Use `issue-facade/`
2. **Need Content Parsing?** ➜ Use `capabilities/markitect-content/`
3. **Need Utility Functions?** ➜ Check `capabilities/markitect-utils/`
4. **Need Documentation?** ➜ Reference `wiki/`
5. **Something New?** ➜ Check `CAPABILITY_REGISTRY.md` first

## 🎯 **CLAUDE IMPLEMENTATION RULES**

### Rule 1: Registry First
- **Always check** `CAPABILITY_REGISTRY.md` before implementing
- **Search existing** capabilities for similar functionality
- **Extend, don't duplicate** existing capabilities

### Rule 2: Use Documented Interfaces
- **Follow interface patterns** documented in capability READMEs
- **Use provided CLI commands** rather than reimplementing
- **Import from documented modules** rather than copying code

### Rule 3: Maintain Separation
- **Core MarkiTect**: Focus on markdown processing and database operations
- **Capabilities**: Use for specialized functionality (issues, content, utils)
- **Clear boundaries**: Don't mix core and capability concerns

### Rule 4: Update Registry
- **When adding capabilities**: Update `CAPABILITY_REGISTRY.md`
- **When changing interfaces**: Update documentation
- **When removing capabilities**: Clean up references

## 📋 **COMMON INTEGRATION PATTERNS**

### Submodule Usage
```bash
# Issue management via submodule
cd issue-facade && python -m cli.main [command]

# Update submodule
git submodule update --remote issue-facade
```

### Local Capability Usage
```python
# Content processing
from capabilities.markitect_content import ContentParser

# Utilities
from capabilities.markitect_utils import helper_function
```

### Error Prevention
```python
# ❌ BAD: Duplicating functionality
def create_issue(title, body):
    # Custom implementation

# ✅ GOOD: Using existing capability
import subprocess
result = subprocess.run(['python', '-m', 'cli.main', 'create', title, body],
                       cwd='issue-facade')
```

---

**💡 Remember: When in doubt, check the registry first!**