# MarkiTect Capability Registry

> **Unified registry for all included capabilities to prevent code duplication and ensure proper separation of concerns**

## Overview

This registry documents all capabilities included in the MarkiTect project, whether as git submodules, local capabilities, or external dependencies. It serves as the authoritative source for Claude and developers to understand available functionality.

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