issue-core/.capability/integration-checklist.md

Issue Facade Integration Checklist

For project maintainers integrating this capability into their codebase.

Pre-Integration

• Verify Python version: >= 3.8
• Check issue tracker platform: Gitea (✅), GitHub (🚧 v1.1), GitLab (🚧 v1.2)
• Obtain API token: Read-only for monitoring, write for implementation
• Document token storage: Environment variable or secure secret manager

Installation

• Install capability:

  pip install -e capabilities/issue-facade/
  

• Verify installation:

  issue --version
  

• Configure backend (one-time):

  export GITEA_API_TOKEN="your-token"
  issue backend add myproject gitea
  # Provide: URL, owner, repo when prompted
  issue backend set-default myproject
  

• Test connection:

  issue backend test myproject
  issue list --limit=5
  

Project Integration

Option 1: Agent Context File (Recommended)

• Copy agent context to project:

  mkdir -p .claude/capabilities/
  cp capabilities/issue-facade/.capability/agent-context.md \
     .claude/capabilities/issue-facade.md
  

• Add to Claude Code context: Create .claude/context/capabilities.md:

  # Available Capabilities
  
  This project uses specialized capabilities. Always check these before implementing similar functionality.
  
  ## Issue Tracking: issue-facade
  
  **Location:** `capabilities/issue-facade/`
  **Documentation:** `.claude/capabilities/issue-facade.md`
  
  **CRITICAL:** Always use this capability for issue operations. Never use:
  - Direct API calls (requests to /api/v1/repos/...)
  - Platform CLIs (gh, glab)
  - Platform libraries (PyGithub, python-gitlab)
  
  See `.claude/capabilities/issue-facade.md` for usage patterns.
  

Option 2: Slash Command

• Create slash command: Create .claude/commands/use-issues.md:

  You are working with issue tracking. Use the issue-facade capability:
  
  **Python API:**
  ```python
  from issue_tracker.backends.gitea import GiteaBackend
  backend = GiteaBackend()
  backend.connect(config)
  

  CLI:

  issue list --format=json
  issue create "Title" --label=bug
  

  Full docs: See capabilities/issue-facade/AGENT_INTEGRATION.md

  DO NOT use direct API calls or platform CLIs!

• Test slash command:

  # In Claude Code
  /use-issues
  

Option 3: MCP Server (Future - v1.2)

• Configure MCP server (when available)
• Register tools in Claude Code
• Test tool discovery

Agent Configuration

• Set agent identity: Add to .issue-facade/config.json:

  {
    "agent": {
      "identity": "agent-coder",
      "type": "implementation"
    }
  }
  

• Or use environment variables:

  export ISSUE_AGENT_ID="agent-coder"
  export ISSUE_AGENT_TYPE="coder"
  

Verification

• Test basic operations:

  from issue_tracker.backends.gitea import GiteaBackend
  from issue_tracker.core.interfaces import IssueFilter
  
  backend = GiteaBackend()
  backend.connect({'base_url': '...', 'token': '...', 'owner': '...', 'repo': '...'})
  
  # Should return issues
  issues = backend.list_issues(IssueFilter(state='open', limit=5))
  print(f"Found {len(issues)} issues")
  

• Test CLI:

  issue list --state=open --format=json | jq 'length'
  

• Verify agents use capability:

  • Create test issue via agent
  • Check it appears in tracker
  • Verify token from environment was used (not hardcoded)

Documentation Updates

• Update project README:

  ## Issue Tracking
  
  This project uses the issue-facade capability for unified issue tracking.
  
  **Setup:**
  ```bash
  pip install -e capabilities/issue-facade/
  export GITEA_API_TOKEN="your-token"
  issue backend add myproject gitea
  

  Usage: See capabilities/issue-facade/AGENT_INTEGRATION.md

• Add to CONTRIBUTING.md:

  ### Issue Tracking
  
  Always use the `issue` command or Python API from `issue_tracker` package.
  Never make direct API calls to Gitea/GitHub/GitLab.
  
  Examples: `capabilities/issue-facade/examples/agents/`
  

Security Review

• Verify tokens are not in code: git grep GITEA_TOKEN (should be empty)

• Check .gitignore includes:

  .issue-facade/config.json
  .issue-facade/issues.db
  .issue-facade/credentials.json
  

• Audit token permissions: Read-only for bots, write for implementation

• Document token rotation: How often, who has access

Testing

• Run capability tests:

  cd capabilities/issue-facade/
  make test
  

• Test agent workflows:

  python examples/agents/simple_task_executor.py --once
  

• Verify multi-agent coordination:

  python examples/agents/multi_agent_pipeline.py --mode=roundrobin --max-iterations=1
  

Maintenance

• Schedule regular updates:

  cd capabilities/issue-facade/
  git pull origin main
  pip install -e . --upgrade
  

• Monitor capability roadmap: Check ROADMAP.md for new features

• Subscribe to updates: Watch the capability repository

Rollback Plan

If capability causes issues:

• Document how to disable:

  # Temporarily use direct API
  export ISSUE_FACADE_DISABLED=1
  # Or
  issue backend remove myproject
  

• Keep backup config:

  cp ~/.config/issue-facade/backends.json ~/.config/issue-facade/backends.json.backup
  

• Document rollback steps in project wiki/docs

Success Criteria

• Agents successfully create/update issues via capability
• No direct API calls in agent code (verified via code review)
• Token management centralized (one env var, not scattered)
• Multi-agent coordination works (no race conditions)
• Offline/online sync works (if using local backend)

Post-Integration

• Share integration experience: Document what worked, what didn't
• Contribute improvements: PRs to capability for common patterns
• Update capability docs: Add project-specific examples
• Monitor agent usage: Are they using capability correctly?

Troubleshooting

Agents bypass capability

Problem: Agent makes direct API call instead of using capability.

Solution:

1. Check Claude Code context includes capability docs
2. Add explicit reminder in .claude/context/
3. Use slash command /use-issues before agent work
4. Review agent logs for why it chose direct API

Configuration not found

Problem: issue backend list shows empty.

Solution:

issue backend add myproject gitea
issue backend set-default myproject
issue backend test myproject

Authentication failures

Problem: "401 Unauthorized" errors.

Solution:

1. Verify token: echo $GITEA_API_TOKEN
2. Test token: curl -H "Authorization: token $GITEA_API_TOKEN" $GITEA_URL/api/v1/user
3. Check token hasn't expired
4. Verify token has correct permissions

Questions?

• Technical: See CLAUDE.md (development guide)
• Agent patterns: See AGENT_INTEGRATION.md (comprehensive guide)
• Examples: See examples/agents/ (working code)
• Issues: Create issue in capability repository