tegwick
62e7d13d7e
Added systematic approach to manage capability inclusion via subrepos and prevent code duplication. This addresses the architectural challenge of ensuring Claude recognizes, uses, and respects included capabilities. New Capability Management System: - CAPABILITY_REGISTRY.md: Complete registry of all included capabilities - CLAUDE_CAPABILITY_REFERENCE.md: Quick lookup guide for Claude to prevent duplication - tools/capability_discovery.py: Automated discovery and validation tool - Makefile targets: capability-report, capability-search, capability-validate Registry Coverage: - Submodule capabilities: issue-facade (universal issue tracking), wiki (documentation) - Local capabilities: markitect-content (content parsing), markitect-utils (utilities) - External dependencies: Click, pytest, SQLAlchemy, requests Agent Integration: - Updated project-management and tdd-workflow agents with capability awareness - Clear guidelines for checking existing functionality before implementing - Integration patterns for using capabilities properly Discovery & Validation: - Automated capability discovery across submodules and local directories - Search functionality to find existing implementations - Validation tools to detect potential code duplication - Claude-readable interfaces and usage patterns Benefits: - Prevents accidental functionality duplication - Ensures proper separation of concerns - Provides easy capability extension and bugfixing - Maintains clean interfaces between core and capabilities - Guides Claude to use existing capabilities efficiently Usage: - make capability-report: Generate complete capability overview - make capability-search TERM=xyz: Find existing implementations - make capability-validate FILE=path: Check for proper capability usage 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
# 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!** |