markitect-main/CAPABILITY_REGISTRY.md

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

# Issue management
cd issue-facade && python -m cli.main list

# Documentation updates
cd wiki && git pull origin main

Local Capability Integration

# Content processing
from capabilities.markitect_content import ContentParser
parser = ContentParser()

# Utilities
from capabilities.markitect_utils import helper_function

External Dependency Integration

# 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