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:**
```bash
# 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

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

```yaml
# 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:**
```bash
# 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:**
```bash
# 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:**
```python
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:**
```python
# 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:**
```python
# 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:

```yaml
# 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:

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

```yaml
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

```yaml
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

```yaml
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:**
```yaml
# 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:**
```bash
# 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:**
```bash
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

```python
# 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:**
```yaml
# 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-<family>.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:**
```bash
# 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

```yaml
# 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:

```bash
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!**