issue-core/CAPABILITY.yaml

# Issue Facade Capability Manifest
# This file describes the capability to coding agents and integration systems

metadata:
  name: issue-facade
  version: 1.0.0
  type: coordination-tool
  description: >
    Universal interface for issue tracking coordination across Gitea, GitHub, GitLab.
    Provides unified API to prevent direct platform API usage and credential sprawl.

# What problems this capability solves
purpose:
  primary: Agent coordination via issue tracking
  problems_solved:
    - Direct API calls to GitHub/GitLab/Gitea (avoid credential sprawl)
    - Inconsistent issue tracking access patterns
    - Token waste from redundant API calls
    - Platform-specific code in agents
    - Offline/online sync complexity

# When agents should use this capability
usage_rules:
  MUST_USE_INSTEAD_OF:
    - "Direct Gitea API calls (requests.post to /api/v1/repos/...)"
    - "GitHub CLI (gh issue create/list/...)"
    - "GitLab CLI (glab issue create/list/...)"
    - "Python libraries (PyGithub, python-gitlab)"
    - "Direct SQL queries to issue databases"

  PREFER_OVER:
    - "Web scraping of issue tracker UIs"
    - "Manual issue management"
    - "Custom issue tracking scripts"

  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  # Future: Phase 2
      status: planned

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

  configuration:
    required: true
    method: manual  # v1.0 - auto in 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"

    - name: add_comment
      description: Add comment to issue
      python: "backend.add_comment(issue.id, comment)"
      cli: "issue comment 42 'Progress update'"

    - name: close_issue
      description: Close issue
      python: "issue.state = IssueState.CLOSED; backend.update_issue(issue)"
      cli: "issue close 42 --comment='Done'"

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

  token_savings:
    vs_direct_api: "~70% fewer tokens (uses local cache + structured models)"
    vs_cli_tools: "~50% fewer tokens (JSON output vs parsing text)"

# Credential management
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)"

  best_practices:
    - "Use read-only tokens for monitoring agents"
    - "Use write tokens only for implementation agents"
    - "Rotate tokens regularly"

# Agent integration guidance
agent_guidance:
  quick_start: |
    # For Python agents:
    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'))

    # For CLI/shell agents:
    issue list --format=json | jq '.[] | {number, title, state}'

  coordination_pattern: |
    # Claim issue to prevent race conditions
    issue edit 42 --assignee=my-agent-id --state=in_progress
    issue comment 42 "Starting work..."

    # Do work...

    issue comment 42 "Completed: <summary>"
    issue close 42 --comment="Done"

  error_handling: |
    # Check exit codes
    if ! issue backend test myproject; then
      echo "Backend not configured or unavailable"
      exit 1
    fi

# Documentation references
documentation:
  integration: "AGENT_INTEGRATION.md"
  development: "CLAUDE.md"
  roadmap: "ROADMAP.md"
  examples: "examples/agents/"

# Dependencies and requirements
requirements:
  runtime:
    python: ">=3.8"
    packages:
      - "click>=8.0.0"
      - "requests>=2.25.0"
      - "python-dateutil>=2.8.0"

  optional:
    - "jq (for JSON parsing in shell)"
    - "sqlite3 (usually pre-installed)"

# Current limitations (v1.0)
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)"
  - "Hardcoded user context (agent identity in v1.2)"

# Roadmap for capability evolution
roadmap:
  v1.1:
    - "Auto-detection from git remotes"
    - "Environment-only configuration"
    - "Zero-setup for common platforms"
  v1.2:
    - "Agent identity management"
    - "Native issue claiming/locking"
    - "Webhook support"
  v2.0:
    - "Issue dependencies"
    - "Query DSL"
    - "Distributed locking"

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

  verify_installation: |
    # Verify capability is working
    issue backend list  # Should show configured backends
    issue list --format=json | jq 'length'  # Should return issue count

# Support and troubleshooting
support:
  common_issues:
    - problem: "Backend not configured"
      solution: "Run: issue backend add <name> <type>"

    - problem: "Authentication failed"
      solution: "Check GITEA_API_TOKEN is set and valid"

    - problem: "Command not found: issue"
      solution: "Run: pip install -e capabilities/issue-facade/"

# Integration priority score (higher = more important for agent to use)
priority:
  score: 95  # 0-100, where 100 = critical
  reasoning: >
    Critical for agent coordination. Bypassing this capability leads to:
    - Credential management issues
    - Inconsistent issue state
    - Token waste
    - Platform lock-in
    - Race conditions in multi-agent scenarios