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: capabilities/issue-facade/
• Repository: coulomb/issue-facade
• Purpose: Backend-agnostic issue tracking with unified CLI
• Interfaces:
  • CLI: cd capabilities/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 capabilities/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 capabilities/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