issue-core/.capability/README.md

# Capability Bootstrap System

**How coding agents discover and integrate the issue-facade capability.**

## Design Philosophy

**Problem:** Coding agents might bypass capabilities and use direct API calls, causing:
- Credential management chaos
- Token waste
- Platform lock-in
- Race conditions
- Inconsistent state

**Solution:** Make capabilities **self-describing** and **easy to discover**, so agents naturally prefer them over alternatives.

## Architecture

### 1. Self-Description (Machine-Readable)

**File:** `CAPABILITY.yaml`

Contains machine-readable metadata that agents and tooling can parse:
- What the capability does
- When to use it vs. alternatives
- How to integrate it
- API surface
- Priority score (how critical it is)

**Usage:**
```bash
# Tools can parse this to understand capabilities
yq eval '.purpose.primary' CAPABILITY.yaml
# Output: "Agent coordination via issue tracking"
```

### 2. Agent Context (Human + AI Readable)

**File:** `.capability/agent-context.md`

Comprehensive guide for coding agents:
- Quick reference API
- Common patterns
- Critical "DO NOT bypass" warnings
- Error handling
- Examples

**Injected into:** `.claude/capabilities/issue-facade.md` in main project

### 3. Integration Automation

**File:** `.capability/integrate.sh`

Interactive script that:
- Installs the capability
- Configures backends
- Injects context into Claude Code
- Creates slash commands
- Verifies setup

**Usage:**
```bash
make integrate
# or
cd capabilities/issue-facade && ./.capability/integrate.sh
```

### 4. Integration Checklist

**File:** `.capability/integration-checklist.md`

Step-by-step checklist for humans integrating the capability:
- Pre-integration checks
- Installation steps
- Verification tests
- Security review
- Troubleshooting

## Integration Flow

### For Main Project (One-Time Setup)

```
Main Project Setup
├── 1. Human runs: cd capabilities/issue-facade && make integrate
├── 2. Script installs capability
├── 3. Script configures backend (prompts for credentials)
├── 4. Script copies agent-context.md → .claude/capabilities/
├── 5. Script creates .claude/commands/use-issues.md
└── 6. Script verifies setup
```

**Result:**
- `issue` command available system-wide
- Backend configured with tokens
- Claude Code knows about capability
- Agents can discover via context files

### For Coding Agents (Automatic)

```
Agent Workflow
├── 1. Agent receives task involving issues
├── 2. Agent checks .claude/capabilities/ for relevant docs
├── 3. Agent finds issue-facade.md with comprehensive guide
├── 4. Agent uses Python API or CLI as documented
└── 5. Agent avoids direct API calls (warned in docs)
```

**Key Files Agent Reads:**
- `.claude/capabilities/issue-facade.md` - Complete usage guide
- `.claude/context/capabilities.md` - High-level capability list
- `.claude/commands/use-issues.md` - Slash command for context injection

## Main Project Structure (After Integration)

```
project-root/
├── capabilities/
│   └── issue-facade/              # Capability code
│       ├── CAPABILITY.yaml        # Machine-readable metadata
│       ├── .capability/
│       │   ├── agent-context.md   # Agent guide (source)
│       │   ├── integrate.sh       # Integration script
│       │   └── README.md          # This file
│       ├── issue_tracker/         # Python package
│       └── ...
│
├── .claude/                       # Claude Code configuration
│   ├── capabilities/              # Capability docs for agents
│   │   └── issue-facade.md        # Agent guide (copy)
│   │
│   ├── commands/                  # Slash commands
│   │   └── use-issues.md          # /use-issues command
│   │
│   └── context/                   # Always-available context
│       └── capabilities.md        # List of all capabilities
│
└── .issue-facade/                 # Capability config (gitignored)
    ├── config.json                # Backend configuration
    └── issues.db                  # Local cache/backup
```

## For Agent Developers

### How to Make Your Agent Use the Capability

**1. Check for capability context:**
```python
import os
from pathlib import Path

def has_issue_capability(project_root: Path) -> bool:
    """Check if issue-facade capability is available."""
    capability_guide = project_root / ".claude/capabilities/issue-facade.md"
    return capability_guide.exists()

if has_issue_capability(Path.cwd()):
    # Use capability
    from issue_tracker.backends.gitea import GiteaBackend
    backend = GiteaBackend()
else:
    # Fall back or prompt human
    print("Issue capability not available. Please integrate it.")
```

**2. Read the context:**
```python
def get_capability_docs(capability_name: str) -> str:
    """Read capability documentation."""
    doc_path = Path(f".claude/capabilities/{capability_name}.md")
    if doc_path.exists():
        return doc_path.read_text()
    return None

# Agent can read and understand the guide
docs = get_capability_docs("issue-facade")
# Parse docs for API usage patterns...
```

**3. Use the API as documented:**
```python
# Example from agent-context.md
from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.core.interfaces import IssueFilter

backend = GiteaBackend()
backend.connect(config)
issues = backend.list_issues(IssueFilter(state='open'))
```

### How to Avoid Bypassing

**Bad (Bypasses capability):**
```python
# ❌ Direct API call
import requests
response = requests.post(
    f"{gitea_url}/api/v1/repos/{owner}/{repo}/issues",
    json={"title": "Bug"},
    headers={"Authorization": f"token {token}"}
)
```

**Good (Uses capability):**
```python
# ✅ Uses capability
from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.core.models import Issue, IssueState
from datetime import datetime, timezone

backend = GiteaBackend()
backend.connect(config)
issue = Issue(
    id=None, number=0,
    title="Bug",
    description="Details",
    state=IssueState.OPEN,
    created_at=datetime.now(timezone.utc),
    updated_at=datetime.now(timezone.utc)
)
backend.create_issue(issue)
```

## For Capability Developers

### Adding a New Capability to This System

**1. Create capability structure:**
```
capabilities/your-capability/
├── CAPABILITY.yaml              # Metadata
├── .capability/
│   ├── agent-context.md         # Agent guide
│   ├── integrate.sh             # Integration script
│   ├── integration-checklist.md # Human checklist
│   └── README.md                # This doc adapted
└── your_package/                # Implementation
```

**2. Write CAPABILITY.yaml:**
```yaml
metadata:
  name: your-capability
  version: 1.0.0
  type: tool | library | service
  description: What it does

purpose:
  primary: Main purpose
  problems_solved:
    - Problem 1
    - Problem 2

usage_rules:
  MUST_USE_INSTEAD_OF:
    - "Alternative 1 to avoid"
    - "Alternative 2 to avoid"

api:
  core_operations:
    - name: operation_1
      python: "from your_package import ..."
      cli: "your-command ..."
```

**3. Write agent-context.md:**
- Critical warnings (what NOT to do)
- Quick reference API
- Common patterns
- Error handling
- Examples

**4. Create integrate.sh:**
- Install capability
- Configure if needed
- Copy context to `.claude/capabilities/`
- Create slash command
- Verify installation

**5. Add to main project:**
```bash
cd capabilities/your-capability
make integrate
```

## Discovery Mechanisms

### Manual Discovery (Human)
1. Human sees `capabilities/` directory
2. Reads `CAPABILITY.yaml` to understand what's available
3. Runs `make integrate` to set up for agents

### Automatic Discovery (Agent)
1. Agent checks `.claude/capabilities/` for available capabilities
2. Reads relevant `.md` files for usage guides
3. Uses capabilities as documented
4. Falls back gracefully if capability unavailable

### Tool-Assisted Discovery
```bash
# Future: Auto-discover all capabilities
make discover-capabilities
# Output:
#   Found capabilities:
#   - issue-facade (v1.0.0) - Issue tracking coordination
#   - ... (other capabilities)

# Auto-integrate all
make integrate-all-capabilities
```

## Priority System

Capabilities have priority scores (0-100) indicating importance:

- **90-100 (Critical):** Must always use, bypassing causes major issues
- **70-89 (High):** Should prefer over alternatives
- **50-69 (Medium):** Use when available
- **Below 50 (Low):** Optional convenience

**issue-facade priority: 95 (Critical)**

Agents should check priority when deciding whether to use a capability or fall back to alternatives.

## Best Practices

### For Capability Authors

1. **Make it obvious:** Clear documentation, examples, warnings
2. **Make it easy:** One-command integration, good defaults
3. **Make it safe:** No tokens in code, proper error handling
4. **Make it discoverable:** Standard structure, machine-readable metadata
5. **Make it maintainable:** Version clearly, document breaking changes

### For Project Integrators

1. **Integrate early:** Set up capabilities before agents start work
2. **Verify integration:** Run tests to ensure agents use capabilities
3. **Monitor usage:** Check that agents aren't bypassing capabilities
4. **Keep updated:** Pull capability updates regularly
5. **Share feedback:** Report issues, contribute improvements

### For Agent Developers

1. **Check context:** Always look for `.claude/capabilities/`
2. **Read docs:** Don't guess the API, read the guide
3. **Follow warnings:** If docs say "DO NOT", don't do it
4. **Handle errors:** Capability might not be available
5. **Report issues:** If capability is confusing, report it

## Future Enhancements

### v1.1: Auto-Discovery
- `make list-capabilities` to show all available
- `make integrate-capability NAME` for specific capability
- Auto-detect when capability would be useful

### v1.2: MCP Integration
- Capabilities as MCP servers
- Tool-based discovery (no file reading needed)
- Dynamic capability loading

### v2.0: Capability Registry
- Central registry of available capabilities
- Version management and updates
- Dependency resolution

## FAQ

**Q: Why not just document "use issue-facade" in README?**
A: Agents often skip general docs. Putting it in `.claude/capabilities/` makes it part of their working context.

**Q: What if agent bypasses capability anyway?**
A: 1) Check warnings are in context, 2) Use slash command to re-inject, 3) Review agent's reasoning for bypass.

**Q: Can capabilities depend on each other?**
A: Not yet (v1.0). Planned for v2.0 with dependency resolution.

**Q: How do I test integration?**
A: Run integration script, then test with agent doing actual work. Verify it uses capability API.

**Q: What if capability breaks?**
A: Document rollback in integration checklist. Keep backup configs. Have fallback plan.

## Summary

**The capability bootstrap system works by:**

1. **Self-description** - Capability declares what it does (CAPABILITY.yaml)
2. **Context injection** - Integration copies docs to `.claude/capabilities/`
3. **Agent discovery** - Agents check context before implementing
4. **Natural preference** - Good docs + warnings make capability easier than alternatives
5. **Verification** - Integration script tests that everything works

**Result:** Agents naturally discover and use capabilities instead of bypassing them.

## Example: Issue Tracking Use Case

**Without capability:**
```python
# Agent bypasses, makes direct API call
response = requests.post(gitea_url + "/issues", ...)
# Problems: Token in code, no caching, platform-specific
```

**With capability (properly integrated):**
```python
# Agent checks .claude/capabilities/issue-facade.md
# Reads: "Use this API, don't use direct requests"
# Agent follows documented pattern:
from issue_tracker.backends.gitea import GiteaBackend
backend = GiteaBackend()
backend.connect(config)
backend.create_issue(issue)
# Benefits: Centralized tokens, caching, platform-agnostic
```

**The difference:** Integration puts capability docs in agent's context, making it the obvious choice.

---

For more information:
- **Integration Guide:** `AGENT_INTEGRATION.md`
- **Development Guide:** `CLAUDE.md`
- **Roadmap:** `ROADMAP.md`
- **Examples:** `examples/agents/`