issue-core/.capability/README.md

Capability Bootstrap System

How coding agents discover and integrate the issue-core 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-issue-tracking.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:

# Tools can parse this to understand capabilities
yq eval '.purpose.primary' CAPABILITY-issue-tracking.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-core.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:

make integrate
# or
cd capabilities/issue-core && ./.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-core && 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-core.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-core.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-core/              # Capability code
│       ├── CAPABILITY-issue-tracking.yaml        # Machine-readable metadata
│       ├── .capability/
│       │   ├── agent-context.md   # Agent guide (source)
│       │   ├── integrate.sh       # Integration script
│       │   └── README.md          # This file
│       ├── issue_core/         # Python package
│       └── ...
│
├── .claude/                       # Claude Code configuration
│   ├── capabilities/              # Capability docs for agents
│   │   └── issue-core.md        # Agent guide (copy)
│   │
│   ├── commands/                  # Slash commands
│   │   └── use-issues.md          # /use-issues command
│   │
│   └── context/                   # Always-available context
│       └── capabilities.md        # List of all capabilities
│
└── .issue-core/                 # 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:

import os
from pathlib import Path

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

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

2. Read the context:

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-core")
# Parse docs for API usage patterns...

3. Use the API as documented:

# Example from agent-context.md
from issue_core.backends.gitea import GiteaBackend
from issue_core.core.interfaces import IssueFilter

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

How to Avoid Bypassing

Bad (Bypasses capability):

# ❌ 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):

# ✅ Uses capability
from issue_core.backends.gitea import GiteaBackend
from issue_core.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-issue-tracking.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-issue-tracking.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:

cd capabilities/your-capability
make integrate

Discovery Mechanisms

Manual Discovery (Human)

1. Human sees capabilities/ directory
2. Reads CAPABILITY-issue-tracking.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

# Future: Auto-discover all capabilities
make discover-capabilities
# Output:
#   Found capabilities:
#   - issue-core (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-core 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-core" 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-issue-tracking.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:

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

With capability (properly integrated):

# Agent checks .claude/capabilities/issue-core.md
# Reads: "Use this API, don't use direct requests"
# Agent follows documented pattern:
from issue_core.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/