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/

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

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

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

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

# 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

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

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

Local Capability Usage

# Content processing
from capabilities.markitect_content import ContentParser

# Utilities
from capabilities.markitect_utils import helper_function

Error Prevention

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