issue-core/ReusableCapabilitiesArchitecture.md

Reusable Capabilities Architecture

A framework for composable, AI-integrated development capabilities

Version: 0.1.0 (Draft) Status: Evolving specification Audience: DevHumans and DevAgents

---

Philosophy

Capabilities are conceptual units of reusable functionality that focus on use-cases and requirements rather than rigid technical interfaces. Unlike traditional libraries or services, capabilities are designed for:

• Natural language integration by coding agents (AI-assisted development)
• Requirements-level reuse not just code-level reuse
• Evolutionary maturity as implementations and patterns emerge
• Human-agent collaboration in understanding and applying capabilities

Capabilities bridge the gap between "what we need" (requirements) and "how we build it" (implementation), enabling both humans and AI agents to discover, understand, and integrate functionality through conceptual understanding rather than just technical contracts.

---

Core Concepts

Capability Family

A Capability Family is an abstract, conceptual grouping of related functionality defined by common use-cases and problem domains, not rigid type systems.

Examples:

• issue-tracking - Managing issues across different platforms
• feedback-collection - Gathering and organizing user feedback
• authentication - User identity and access management
• documentation-generation - Creating docs from code/specs

Characteristics:

• Described in natural language (human and agent readable)
• Focused on what problems it solves (use-cases)
• Allows multiple implementations with varying approaches
• Evolves organically as new use-cases emerge

Why "Family" not "Type"?

• "Type" implies rigid, formal contracts (technical focus)
• "Family" implies related concepts with variation (conceptual focus)
• Capabilities operate at the requirements/discussion level, not just interface level
• AI agents understand families through natural language, not just type signatures

Capability Implementation

A Capability Implementation is a concrete realization of a Capability Family - the actual code, tools, and patterns that provide the functionality.

Examples:

• issue-facade - An implementation of the issue-tracking family
• feedback-tool - An implementation of the feedback-collection family

Characteristics:

• Provides concrete functionality (code, CLI, API)
• May implement multiple backend variants (Gitea, GitHub, local)
• Has maturity levels (experimental, beta, production)
• Can be composed with other capabilities

Repository as Capability Provider

A repository can provide:

• Single capability (common for focused tools)
• Multiple capabilities (common for mature projects)
• Capability variants (different implementations of same family)

---

File and Directory Conventions

Capability Declaration Files

Every capability implementation must declare itself via a specification file:

Format: CAPABILITY-<family-name>.yaml

Examples:

CAPABILITY-issue-tracking.yaml       # Declares issue-tracking capability
CAPABILITY-feedback-collection.yaml  # Declares feedback-collection capability
CAPABILITY-authentication.yaml       # Declares authentication capability

Location: Repository root

Why this format?

• Explicit family declaration even for single-capability repos
• Self-documenting - filename reveals the capability family
• Discoverable - agents can glob CAPABILITY-*.yaml
• Scalable - naturally supports multiple capabilities per repo

Single Capability Repository Structure

issue-facade/                              # Repository name (implementation)
├── CAPABILITY-issue-tracking.yaml         # Declares: provides "issue-tracking"
├── README.md                              # Human-readable documentation
├── feedback/                              # Visible: user interface for feedback
│   ├── inbound/
│   ├── reviewed/
│   └── README.md
├── .capability/                           # Hidden: implementation infrastructure
│   ├── feedback                           # Feedback CLI tool
│   ├── integrate.sh                       # Integration script
│   └── ...
├── issue_tracker/                         # Core implementation code
│   ├── core/
│   ├── backends/
│   └── cli/
├── tests/
└── examples/

Key decisions:

• feedback/ is visible (user-facing interface)
• .capability/ is hidden (evolving implementation details)
• CAPABILITY-issue-tracking.yaml is visible (stable interface/contract)

Multiple Capabilities Repository Structure

unified-devtools/                          # Repository providing multiple capabilities
├── CAPABILITY-issue-tracking.yaml         # First capability
├── CAPABILITY-feedback-collection.yaml    # Second capability
├── CAPABILITY-documentation.yaml          # Third capability
├── README.md
├── feedback/                              # Namespaced by family
│   ├── issue-tracking/
│   │   ├── inbound/
│   │   └── reviewed/
│   ├── feedback-collection/               # Meta: feedback about feedback!
│   │   ├── inbound/
│   │   └── reviewed/
│   └── documentation/
│       ├── inbound/
│       └── reviewed/
├── .capability/                           # Shared or namespaced (implementation choice)
│   ├── issue-tracking/
│   ├── feedback-collection/
│   └── common/
├── src/
│   ├── issue_tracker/
│   ├── feedback_tool/
│   └── doc_generator/
└── tests/

Notes:

• Each capability gets its own CAPABILITY-<family>.yaml
• Feedback is namespaced by family name
• .capability/ organization is implementation detail (can be shared or separated)

---

Integrating Capabilities into Projects

The Directory Depth Problem

Traditional approaches create deep directory trees:

my-project/
└── capabilities/
    └── issue-facade/
        └── issue_tracker/
            └── backends/
                └── gitea/
                    └── backend.py    # 6 levels deep!

Proposed Solution: Underscore Prefix

Use underscore-prefixed directories at the repository root to signal "integrated capability, not core code":

Option A: Implementation-Based (Recommended)

my-project/
├── _issue-facade/                  # Integrated capability (flat!)
│   └── issue_tracker/              # Only 2-3 levels deep
│       └── backends/
├── _feedback-tool/                 # Another integrated capability
├── src/                            # Core project code
│   └── my_app/
├── tests/
└── README.md

Option B: Family-Based

my-project/
├── _issue-tracking/                # Capability family
│   └── issue-facade/               # Implementation (if multiple needed)
├── _feedback-collection/
│   └── feedback-tool/
└── src/

Option C: Short Alias

my-project/
├── c/                              # "c" for capabilities
│   ├── issue-facade/
│   └── feedback-tool/
└── src/

Recommendation: Option A (Implementation-Based)

Rationale:

• Flatter hierarchy - _issue-facade/issue_tracker/... (3 levels vs 6)
• Clear signal - underscore means "integrated, not core"
• Discoverable - ls _*/ shows all integrated capabilities
• No ambiguity - implementation name is explicit
• Scales well - multiple implementations of same family coexist naturally

Example:

my-project/
├── _issue-facade/              # Issue tracking via issue-facade
├── _auth-service/              # Authentication via auth-service
├── _postgres-tools/            # Database tools
├── src/                        # Core project code
│   └── my_app/
│       ├── api/
│       ├── models/
│       └── main.py
├── tests/
├── README.md
└── requirements.txt

Discovery:

# List all integrated capabilities
ls -d _*/

# Read capability specs
cat _issue-facade/CAPABILITY-*.yaml
cat _auth-service/CAPABILITY-*.yaml

Important: The underscore prefix is local convention for integrated capabilities, not part of the upstream git repository name. When integrating github.com/markitect/issue-facade, it becomes _issue-facade/ in your project.

---

CAPABILITY Specification Format

Minimal Example

# CAPABILITY-issue-tracking.yaml
metadata:
  family: issue-tracking
  implementation: issue-facade
  version: 1.0.0
  description: >
    Unified interface for issue tracking across Gitea, GitHub, GitLab.
    Enables agent coordination via standardized issue operations.

purpose:
  use_cases:
    - "Create and manage issues programmatically"
    - "Coordinate multi-agent workflows via issue states"
    - "Offline issue tracking with sync to remote platforms"

  problems_solved:
    - "Platform-specific API differences"
    - "Credential management across multiple backends"
    - "Offline/online workflow complexity"

integration:
  methods:
    python_api: true
    cli: true
    mcp_server: false  # planned

  installation:
    command: "pip install -e _issue-facade/"
    verify: "issue --version"

documentation:
  readme: "README.md"
  integration_guide: "AGENT_INTEGRATION.md"
  examples: "examples/"

feedback:
  enabled: true
  directory: "feedback/"

Comprehensive Example

# CAPABILITY-issue-tracking.yaml
metadata:
  family: issue-tracking
  implementation: issue-facade
  version: 1.0.0
  maturity: production  # experimental, beta, production

  description: >
    Universal CLI for issue tracking that provides a unified interface
    to multiple issue tracking backends. Designed for agent coordination
    via standardized issue operations across platforms.

# What problems this capability solves
purpose:
  primary: "Agent coordination via issue tracking"

  use_cases:
    - "Create, update, query issues across platforms"
    - "Multi-agent task coordination through issue states"
    - "Offline development with sync to remote backends"
    - "Unified issue management for polyglot platform environments"

  problems_solved:
    - "Direct API calls to GitHub/GitLab/Gitea (avoids credential sprawl)"
    - "Inconsistent issue tracking access patterns"
    - "Platform-specific code in agents"
    - "Offline/online workflow synchronization"

# When to use this capability
usage_rules:
  MUST_USE_INSTEAD_OF:
    - "Direct Gitea/GitHub/GitLab API calls"
    - "Platform-specific CLIs (gh, glab)"
    - "Python libraries (PyGithub, python-gitlab)"

  USE_WHEN:
    - "Creating, updating, or querying issues"
    - "Multi-agent coordination needed"
    - "Offline work with sync required"
    - "Cross-platform issue management"

# How to integrate this capability
integration:
  methods:
    python_api:
      available: true
      import: "from issue_tracker.backends.gitea import GiteaBackend"
      docs: "AGENT_INTEGRATION.md"

    cli:
      available: true
      command: "issue"
      subcommands: ["list", "create", "show", "edit", "close", "comment"]
      json_output: true

    mcp_server:
      available: false
      status: planned
      version: "2.0.0"

  installation:
    method: pip
    command: "pip install -e _issue-facade/"
    verify: "issue --version"

  configuration:
    required: true
    method: manual  # auto-detection planned for v1.1
    steps:
      - "Export GITEA_API_TOKEN environment variable"
      - "Run: issue backend add myproject gitea"
      - "Provide: URL, owner, repo when prompted"
      - "Run: issue backend set-default myproject"

# API surface for agents
api:
  core_operations:
    - name: list_issues
      description: "Query issues with filtering"
      python: "backend.list_issues(IssueFilter(state='open', labels=['bug']))"
      cli: "issue list --state=open --label=bug --format=json"

    - name: create_issue
      description: "Create new issue"
      python: "backend.create_issue(Issue(...))"
      cli: "issue create 'Title' --label=bug --assignee=agent"

    - name: update_issue
      description: "Update existing issue"
      python: "backend.update_issue(issue)"
      cli: "issue edit 42 --state=in_progress"

# Backend variants provided
backends:
  - name: gitea
    status: production
    features: [crud, sync, labels, milestones, comments]

  - name: local-sqlite
    status: production
    features: [crud, offline, sync]

  - name: github
    status: planned
    target_version: "1.1.0"

# Depends on other capabilities
dependencies:
  capabilities:
    - family: feedback-collection
      optional: true
      reason: "Integrated feedback system for continuous improvement"

# Performance characteristics
efficiency:
  local_caching: true
  offline_mode: true
  batch_operations: false  # v1.0 limitation
  rate_limiting: automatic

# Credentials and security
credentials:
  method: environment_variables
  variables:
    - GITEA_API_TOKEN
    - GITEA_URL  # optional with config

  security:
    - "Tokens never in code or logs"
    - "Config stored in ~/.config/issue-facade/"
    - "Per-repo config in .issue-facade/ (gitignored)"

# Documentation references
documentation:
  readme: "README.md"
  integration_guide: "AGENT_INTEGRATION.md"
  development_guide: "CLAUDE.md"
  roadmap: "ROADMAP.md"
  examples: "examples/agents/"
  api_docs: null  # not yet available

# Feedback system
feedback:
  enabled: true
  directory: "feedback/"
  cli_tool: ".capability/feedback"

  for_users: |
    Submit feedback: ./.capability/feedback submit "Your feedback"

  for_maintainers: |
    Review feedback: ./.capability/feedback list

# Testing and validation
testing:
  test_command: "make test"
  coverage: 61%
  test_count: 109

  verify_installation: |
    issue backend list
    issue list --format=json | jq 'length'

# Current limitations
limitations:
  - "Manual backend configuration required (auto-detect in v1.1)"
  - "No built-in issue locking (workaround via assignee + comment)"
  - "Basic conflict resolution (advanced in v2.0)"

# Roadmap
roadmap:
  v1.1:
    - "Auto-detection from git remotes"
    - "GitHub backend support"
  v1.2:
    - "Agent identity management"
    - "Issue claiming/locking API"
  v2.0:
    - "Issue dependencies"
    - "Distributed locking"
    - "MCP server integration"

# Priority for agent integration
priority:
  score: 95  # 0-100, where 100 = critical
  reasoning: >
    Critical for agent coordination. Bypassing this capability leads to
    credential sprawl, inconsistent state, and race conditions.

---

Discovery and Integration Patterns

For DevHumans

Discover capabilities in a repository:

# List all capability declarations
ls CAPABILITY-*.yaml

# Read a specific capability
cat CAPABILITY-issue-tracking.yaml

# View feedback
ls feedback/
cat feedback/README.md

Integrate a capability:

# Clone/copy into underscore-prefixed directory
git clone https://github.com/markitect/issue-facade _issue-facade

# Or use git submodule
git submodule add https://github.com/markitect/issue-facade _issue-facade

# Install
pip install -e _issue-facade/

# Verify
issue --version

For DevAgents

Discover capabilities programmatically:

import glob
import yaml
from pathlib import Path

def discover_capabilities(repo_path):
    """Discover all capabilities provided by a repository."""
    capabilities = []

    for spec_file in glob.glob(f"{repo_path}/CAPABILITY-*.yaml"):
        with open(spec_file) as f:
            spec = yaml.safe_load(f)
            capabilities.append(spec)

    return capabilities

def find_capability_family(repo_path, family_name):
    """Find a specific capability family implementation."""
    spec_file = f"{repo_path}/CAPABILITY-{family_name}.yaml"

    if Path(spec_file).exists():
        with open(spec_file) as f:
            return yaml.safe_load(f)

    return None

# Usage
capabilities = discover_capabilities("_issue-facade")
# Returns: [{'metadata': {'family': 'issue-tracking', ...}}]

issue_cap = find_capability_family("_issue-facade", "issue-tracking")
print(f"Found: {issue_cap['metadata']['implementation']}")
# Output: Found: issue-facade

Use capability via natural language understanding:

# Agent reads capability spec
spec = find_capability_family("_issue-facade", "issue-tracking")

# Agent understands use-cases
use_cases = spec['purpose']['use_cases']
# ["Create and manage issues programmatically", ...]

# Agent discovers integration methods
if spec['integration']['methods']['python_api']['available']:
    import_statement = spec['integration']['methods']['python_api']['import']
    # "from issue_tracker.backends.gitea import GiteaBackend"

    # Agent can now integrate programmatically
    exec(import_statement)

# Or use CLI
if spec['integration']['methods']['cli']['available']:
    cli_command = spec['integration']['methods']['cli']['command']
    # "issue"

    # Agent executes CLI commands
    os.system(f"{cli_command} list --format=json")

Provide feedback:

# Agent encounters issue, submits feedback
feedback_dir = spec['feedback']['directory']
feedback_file = f"{feedback_dir}/inbound/{timestamp}-{hash}.md"

with open(feedback_file, 'w') as f:
    f.write(f"""---
timestamp: {now}
source: agent
category: bug
---

Encountered error when syncing 5000+ issues: TimeoutError
Suggest implementing batch processing.
""")

---

Capability Composition

Capabilities Using Capabilities

Capabilities can depend on other capabilities:

# CAPABILITY-project-management.yaml
metadata:
  family: project-management
  implementation: pm-tool
  version: 1.0.0

# This capability integrates other capabilities
integrates:
  - family: issue-tracking
    implementation: issue-facade
    version: ">=1.0.0"
    reason: "Uses issue tracking for task management"

  - family: feedback-collection
    implementation: feedback-tool
    version: ">=1.0.0"
    reason: "Collects user feedback about project"

  - family: documentation
    implementation: doc-gen
    version: ">=0.5.0"
    reason: "Generates project documentation"

Repository structure:

pm-tool/
├── CAPABILITY-project-management.yaml
├── _issue-facade/                    # Integrated capability
├── _feedback-tool/                   # Integrated capability
├── _doc-gen/                         # Integrated capability
├── src/
│   └── pm/
│       ├── tasks.py                  # Uses issue-facade
│       ├── feedback.py               # Uses feedback-tool
│       └── docs.py                   # Uses doc-gen
└── README.md

Capability Families as Contracts

When one capability depends on a family (not a specific implementation), it creates a flexible contract:

# pm-tool requires "issue-tracking" family
integrates:
  - family: issue-tracking    # Any implementation works!
    version: ">=1.0.0"

Multiple valid integrations:

pm-tool/
├── _issue-facade/            # Option 1: issue-facade implementation
└── ...

pm-tool/
├── _github-native/           # Option 2: github-native implementation
└── ...

pm-tool/
├── _jira-bridge/             # Option 3: jira-bridge implementation
└── ...

All three satisfy the issue-tracking family contract!

---

Maturity Levels

Capabilities evolve through maturity stages:

Experimental

• Purpose: Exploring concepts, validating ideas
• Stability: APIs may change drastically
• Testing: Minimal, proof-of-concept level
• Documentation: Basic README
• Use case: Research, prototyping, learning

metadata:
  maturity: experimental
  version: 0.1.0

Beta

• Purpose: Solidifying patterns, gathering feedback
• Stability: Core APIs stabilizing, minor changes possible
• Testing: Comprehensive tests, some production use
• Documentation: Complete user guide, examples
• Use case: Early adopters, non-critical projects

metadata:
  maturity: beta
  version: 0.9.0

Production

• Purpose: Stable, reliable, widely used
• Stability: Semantic versioning, backward compatibility
• Testing: Extensive tests, battle-tested
• Documentation: Complete docs, tutorials, troubleshooting
• Use case: Production systems, critical workflows

metadata:
  maturity: production
  version: 1.0.0

---

Evolution and Governance

How Capability Families Emerge

1. Pattern Recognition - Similar needs across multiple projects
2. Natural Language Discussion - DevHumans and agents discuss requirements
3. Prototype Implementation - First experimental implementation
4. Specification Emergence - Common use-cases documented
5. Multiple Implementations - Different approaches to same family
6. Standardization - Family contract stabilizes

Example: The issue-tracking family

Project A needs GitHub issues
Project B needs GitLab issues
Project C needs Gitea issues

→ Pattern: "We need issue tracking"
→ Family: "issue-tracking"
→ Implementation 1: issue-facade (multi-backend)
→ Implementation 2: github-native (GitHub-only, optimized)
→ Implementation 3: jira-bridge (JIRA connector)

All implement "issue-tracking" family with different trade-offs

Versioning Strategy

Capability Family Versions:

• Families evolve slowly (conceptual stability)
• Major version when use-cases fundamentally change
• Example: issue-tracking@1.x vs issue-tracking@2.x

Implementation Versions:

• Implementations evolve independently
• Follow semantic versioning (semver)
• Example: issue-facade@1.2.3, github-native@0.5.0

Compatibility:

# Implementation declares family version compatibility
metadata:
  family: issue-tracking
  family_version: "1.x"           # Compatible with v1 family spec
  implementation: issue-facade
  version: 1.2.3                  # Implementation version

---

Best Practices

For Capability Developers

1. Start with Use-Cases - What problems are you solving?
2. Write for Agents - Natural language descriptions, clear contracts
3. Provide Feedback Mechanism - feedback/ directory from day one
4. Document Integration Paths - Python API, CLI, future MCP
5. Test Thoroughly - Both unit tests and integration scenarios
6. Evolve Gradually - Experimental → Beta → Production
7. Semantic Versioning - Breaking changes = major version bump

For Capability Users (Integrators)

1. Prefer Families over Implementations - Depend on issue-tracking, not issue-facade
2. Pin Versions Loosely - >=1.0.0, <2.0.0 allows updates
3. Use Underscore Prefix - _issue-facade/ signals "integrated"
4. Provide Feedback - Use feedback/ to guide improvement
5. Read the Spec - CAPABILITY-*.yaml is the contract
6. Check Maturity - Match capability maturity to your needs

For AI Agents

1. Parse CAPABILITY-*.yaml - Structured data about capabilities
2. Understand Natural Language - Use-cases, descriptions, reasoning
3. Discover Programmatically - Glob patterns, YAML parsing
4. Integrate Flexibly - Python API, CLI, or direct file access
5. Submit Feedback Automatically - Report issues, suggest improvements
6. Respect Maturity Levels - Experimental = expect changes

---

Migration Guide

From Current (hidden feedback) to Architecture v0.1

Changes:

1. Rename feedback/ → feedback/ (visible)
2. Keep .capability/ (hidden infrastructure)
3. Rename CAPABILITY-issue-tracking.yaml → CAPABILITY-<family>.yaml

Steps:

# 1. Rename feedback directory
mv .feedback feedback

# 2. Rename capability spec
mv CAPABILITY-issue-tracking.yaml CAPABILITY-issue-tracking.yaml

# 3. Update references in code/docs
grep -r "\.feedback" . | # Find references
sed -i 's/\.feedback/feedback/g' **/*.md

# 4. Update .gitignore if needed
# Remove .feedback from ignore, keep .capability

Commit:

git add feedback/ CAPABILITY-issue-tracking.yaml
git rm -r .feedback/
git commit -m "refactor: align with ReusableCapabilitiesArchitecture v0.1"

---

FAQ

Why underscore prefix for integrated capabilities?

Problem: Deep directory trees, unclear what's "yours" vs "integrated"

Solution: Underscore signals "used by this repo, not core to it"

Benefits:

• Visual distinction: _issue-facade/ vs src/
• Flatter hierarchy: 2-3 levels vs 5-6 levels
• Easy discovery: ls _*/ lists all integrations
• Works with tab completion: cd _<tab> shows capabilities

Trade-off: Prefix is local convention, not in upstream repo name

Why "Family" instead of "Type"?

Type implies:

• Rigid, formal contracts
• Technical focus (interfaces, signatures)
• Compile-time checking

Family implies:

• Conceptual grouping
• Natural language understanding
• Evolutionary, organic development
• AI-friendly (agents understand families through discussion)

Capabilities operate at the requirements level where natural language and flexible understanding matter more than rigid types.

Can one repo provide multiple implementations of the same family?

Yes! Example:

multi-backend-tool/
├── CAPABILITY-issue-tracking-v1.yaml      # Stable, production backend
├── CAPABILITY-issue-tracking-v2.yaml      # Experimental, next-gen backend
├── src/
│   ├── v1/                                # issue-facade-classic
│   └── v2/                                # issue-facade-next
└── README.md

Both implement issue-tracking family with different approaches.

How do agents choose between multiple implementations?

Agents consider:

1. Maturity - Production > Beta > Experimental
2. Version compatibility - Match required version range
3. Features - Does it support needed backends?
4. Context - User preferences, existing config
5. Natural language - Description match to requirements

# Agent logic
capabilities = discover_capabilities(".")
issue_trackers = [c for c in capabilities if c['metadata']['family'] == 'issue-tracking']

# Filter by maturity
production_ready = [c for c in issue_trackers if c['metadata']['maturity'] == 'production']

# Choose highest version
best = max(production_ready, key=lambda c: c['metadata']['version'])

What about backward compatibility?

Capability Family:

• Maintain backward compatibility within major version
• issue-tracking@1.x stays stable
• issue-tracking@2.x can break compatibility

Implementation:

• Semantic versioning (semver)
• 1.2.3 → 1.3.0 = backward compatible
• 1.3.0 → 2.0.0 = breaking changes

Contract:

# Implementation declares compatibility
metadata:
  family: issue-tracking
  family_version: "1.x"      # Works with v1 family specs
  version: 1.2.3             # Implementation version

How do I create a new capability family?

1. Identify the pattern - Multiple projects need similar functionality
2. Write use-cases - What problems does it solve?
3. Create first implementation - Experimental, version 0.1.0
4. Write CAPABILITY-.yaml - Document contract
5. Gather feedback - Use feedback/ from early users
6. Iterate - Refine based on real-world usage
7. Stabilize - Reach beta/production maturity

No central registry required! Families emerge organically through use.

---

Examples

Example 1: Simple Single Capability

password-generator/
├── CAPABILITY-password-generation.yaml
├── README.md
├── feedback/
│   ├── inbound/
│   └── README.md
├── .capability/
│   └── feedback
├── src/
│   └── pwgen/
│       ├── generator.py
│       ├── strength.py
│       └── cli.py
└── tests/

Example 2: Multiple Capabilities

devtools-suite/
├── CAPABILITY-issue-tracking.yaml
├── CAPABILITY-code-review.yaml
├── CAPABILITY-deployment.yaml
├── README.md
├── feedback/
│   ├── issue-tracking/
│   ├── code-review/
│   └── deployment/
├── .capability/
│   ├── common/
│   └── feedback
└── src/
    ├── issues/
    ├── review/
    └── deploy/

Example 3: Project Integrating Capabilities

my-saas-app/
├── _issue-facade/              # Issue tracking capability
├── _auth-service/              # Authentication capability
├── _feedback-tool/             # Feedback collection capability
├── src/
│   └── myapp/
│       ├── api/
│       │   ├── issues.py       # Uses _issue-facade
│       │   └── auth.py         # Uses _auth-service
│       ├── models/
│       └── main.py
├── tests/
├── README.md
└── requirements.txt

Installation:

# Clone integrated capabilities
git submodule add https://github.com/markitect/issue-facade _issue-facade
git submodule add https://github.com/markitect/auth-service _auth-service
git submodule add https://github.com/markitect/feedback-tool _feedback-tool

# Install
pip install -e _issue-facade/ -e _auth-service/ -e _feedback-tool/

# Use in code
from issue_tracker.backends.gitea import GiteaBackend
from auth_service import AuthManager

---

Appendix: Complete CAPABILITY-*.yaml Template

# CAPABILITY-<family-name>.yaml
# Complete template with all optional fields

metadata:
  family: <family-name>
  implementation: <implementation-name>
  version: 1.0.0
  maturity: production  # experimental, beta, production
  description: >
    One-paragraph description of this capability implementation.
    Focus on what it does and why it's useful.

purpose:
  primary: "Main use-case in one sentence"

  use_cases:
    - "Specific use-case 1"
    - "Specific use-case 2"
    - "Specific use-case 3"

  problems_solved:
    - "Problem 1 this capability addresses"
    - "Problem 2 this capability addresses"

usage_rules:
  MUST_USE_INSTEAD_OF:
    - "Anti-pattern 1 this replaces"
    - "Anti-pattern 2 this replaces"

  PREFER_OVER:
    - "Alternative 1"

  USE_WHEN:
    - "Situation 1"
    - "Situation 2"

integration:
  methods:
    python_api:
      available: true
      import: "from module import Class"
      docs: "path/to/docs.md"

    cli:
      available: true
      command: "command-name"
      subcommands: ["sub1", "sub2"]
      json_output: true

    mcp_server:
      available: false
      status: planned

  installation:
    method: pip
    command: "pip install -e _implementation/"
    verify: "command --version"

  configuration:
    required: true
    method: manual
    steps:
      - "Step 1"
      - "Step 2"

api:
  core_operations:
    - name: operation_name
      description: "What this operation does"
      python: "code.example()"
      cli: "command example"

backends:
  - name: backend1
    status: production
    features: [feature1, feature2]

dependencies:
  capabilities:
    - family: other-family
      version: ">=1.0.0"
      optional: false
      reason: "Why this dependency exists"

efficiency:
  local_caching: true
  offline_mode: false
  batch_operations: true
  rate_limiting: automatic

credentials:
  method: environment_variables
  variables:
    - ENV_VAR_1
    - ENV_VAR_2
  security:
    - "Security practice 1"

documentation:
  readme: "README.md"
  integration_guide: "INTEGRATION.md"
  examples: "examples/"

feedback:
  enabled: true
  directory: "feedback/"
  cli_tool: ".capability/feedback"

testing:
  test_command: "make test"
  coverage: 85%
  test_count: 150

limitations:
  - "Limitation 1"
  - "Limitation 2"

roadmap:
  v1.1:
    - "Feature 1"
  v2.0:
    - "Breaking change 1"

priority:
  score: 80
  reasoning: >
    Why this capability is important for agents to use.

---

Changelog

• v0.1.0 (2025-12-17) - Initial draft
  • Core concepts defined
  • File conventions established
  • Integration patterns documented
  • Examples provided

---

License

This architecture document is part of the MarkiTect project and is licensed under MIT License.

Contributing

This architecture is evolving. Feedback is essential:

cd /path/to/capability-repo
./.capability/feedback submit "Architecture feedback: ..."

Or open an issue/PR in the MarkiTect project repository.

---

Thank you for building reusable capabilities!