markitect-main/CAPABILITY_REGISTRY.md

# MarkiTect External Capability Registry

> **Registry of all capabilities USED BY MarkiTect (external dependencies, submodules, extracted components)**

## Overview

This registry documents all **external capabilities** that MarkiTect depends on - functionality that MarkiTect **uses** rather than **provides**. This includes git submodules, extracted local capabilities, and package dependencies.

> **Note**: For capabilities that MarkiTect **provides** to the world, see `CAPABILITIES.md`. For complete architecture understanding, see `CAPABILITY_INCLUSION_GUIDE.md`.

## Capability Inclusion Patterns

### 1. **Submodule Capabilities** (External Repositories)
Full repositories included as git submodules for independent development and versioning.

### 2. **Local Capabilities** (Extracted Components)
Self-contained capabilities extracted from the main codebase but maintained locally.

### 3. **External Dependencies** (Package Dependencies)
Third-party packages providing specific capabilities via pip/pypi.

---

## 🔍 **ACTIVE CAPABILITIES REGISTRY**

### Universal Issue Management
- **Type**: Submodule Capability
- **Location**: `issue-facade/`
- **Repository**: `coulomb/issue-facade`
- **Purpose**: Backend-agnostic issue tracking with unified CLI
- **Interfaces**:
  - CLI: `cd issue-facade && python -m cli.main [command]`
  - API: Core models, backends (local SQLite, Gitea, GitHub, GitLab)
- **Usage Guidelines**:
  - ✅ **USE**: For all issue management tasks
  - ❌ **DON'T**: Implement custom issue tracking, duplicate CLI commands
  - 🔧 **Integration**: Reference submodule for issue operations

### Content Processing Capability
- **Type**: Local Capability
- **Location**: `capabilities/markitect-content/`
- **Purpose**: MarkdownMatters content parsing without frontmatter/tailmatter
- **Interfaces**:
  - `ContentParser` class for content extraction
  - `ContentStats` for document statistics
  - CLI commands for content operations
- **Usage Guidelines**:
  - ✅ **USE**: For content extraction and analysis
  - ❌ **DON'T**: Reimplement markdown content parsing
  - 🔧 **Integration**: Import from `capabilities.markitect_content`

### Utility Functions Capability
- **Type**: Local Capability
- **Location**: `capabilities/markitect-utils/`
- **Purpose**: Common utility functions and helpers
- **Interfaces**: Shared utilities and helper functions
- **Usage Guidelines**:
  - ✅ **USE**: For common operations and utilities
  - ❌ **DON'T**: Duplicate utility functions
  - 🔧 **Integration**: Import from `capabilities.markitect_utils`

### Documentation and Knowledge Base
- **Type**: Submodule Capability
- **Location**: `wiki/`
- **Repository**: `coulomb/markitect_project.wiki`
- **Purpose**: Comprehensive project documentation and knowledge base
- **Interfaces**: Markdown documentation files
- **Usage Guidelines**:
  - ✅ **USE**: For project documentation, architectural decisions
  - ❌ **DON'T**: Create duplicate documentation
  - 🔧 **Integration**: Reference wiki for authoritative documentation

---

## 🚫 **CAPABILITY CONFLICT PREVENTION**

### Before Implementing New Functionality:

1. **Check This Registry**: Verify no existing capability provides the functionality
2. **Search Submodules**: Check `issue-facade/`, `wiki/` for existing solutions
3. **Check Local Capabilities**: Review `capabilities/` directory
4. **Consult Documentation**: Check capability READMEs for interface details

### Implementation Guidelines:

- **Extend, Don't Duplicate**: If functionality exists, extend or interface with it
- **Clear Boundaries**: New code should complement, not replace, existing capabilities
- **Interface Respect**: Use documented interfaces rather than reimplementing
- **Separation of Concerns**: Maintain clear boundaries between core MarkiTect and capabilities

---

## 🔧 **INTEGRATION PATTERNS**

### Submodule Integration
```bash
# Issue management
cd issue-facade && python -m cli.main list

# Documentation updates
cd wiki && git pull origin main
```

### Local Capability Integration
```python
# Content processing
from capabilities.markitect_content import ContentParser
parser = ContentParser()

# Utilities
from capabilities.markitect_utils import helper_function
```

### External Dependency Integration
```python
# Standard package imports
import click  # CLI framework
import pytest  # Testing framework
```

---

## 📋 **CLAUDE USAGE GUIDELINES**

### When Asked to Implement Functionality:

1. **First**: Check this registry for existing capabilities
2. **If Exists**: Use/extend the existing capability rather than reimplementing
3. **If Missing**: Implement new functionality with clear separation from existing capabilities
4. **Document**: Update this registry when adding new capabilities

### Capability Respect Rules:

- **Issue Management**: Always use `issue-facade` submodule, never implement custom issue tracking
- **Content Processing**: Use `markitect-content` capability for MarkdownMatters parsing
- **Documentation**: Reference `wiki` submodule for authoritative project information
- **Utilities**: Check `markitect-utils` before creating new utility functions

### Integration Commands:
- **Issue Operations**: `cd issue-facade && python -m cli.main [command]`
- **Content Analysis**: Import from `capabilities.markitect_content`
- **Utility Functions**: Import from `capabilities.markitect_utils`
- **Documentation**: Reference files in `wiki/`

---

## 🔄 **CAPABILITY LIFECYCLE MANAGEMENT**

### Adding New Capabilities

1. **Evaluate**: Does this warrant capability extraction?
2. **Choose Pattern**: Submodule (external repo) vs Local capability vs External dependency
3. **Implement**: Follow capability inclusion patterns
4. **Document**: Update this registry with interface details
5. **Update Agents**: Inform specialized agents of new capability

### Updating Existing Capabilities

1. **Submodules**: Update submodule reference (`git submodule update`)
2. **Local Capabilities**: Update local code and interfaces
3. **External Dependencies**: Update package versions in `pyproject.toml`
4. **Registry**: Update interface documentation if changed

### Removing Capabilities

1. **Deprecation Notice**: Document deprecation timeline
2. **Migration Path**: Provide alternative solutions
3. **Remove References**: Update all code using the capability
4. **Clean Registry**: Remove from this registry
5. **Update Documentation**: Update all relevant documentation

---

## 📊 **CAPABILITY METRICS**

- **Total Capabilities**: 4 active capabilities
- **Submodule Capabilities**: 2 (issue-facade, wiki)
- **Local Capabilities**: 2 (markitect-content, markitect-utils)
- **External Dependencies**: Multiple (see pyproject.toml)
- **Coverage**: Issue management, content processing, utilities, documentation

---

## 🎯 **SUCCESS CRITERIA**

### For Developers:
- [ ] Zero accidental functionality duplication
- [ ] Clear interface boundaries respected
- [ ] Efficient capability discovery and usage
- [ ] Proper separation of concerns maintained

### For Claude:
- [ ] Registry consulted before implementing new functionality
- [ ] Existing capabilities used when available
- [ ] Clear understanding of capability boundaries
- [ ] Proper integration patterns followed

### For the Project:
- [ ] Modular architecture maintained
- [ ] Easy capability extension and bugfixing
- [ ] Clean separation between core and capabilities
- [ ] Scalable capability inclusion patterns