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

# Issue Core 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:**
  ```bash
  pip install -e capabilities/issue-core/
  ```

- [ ] **Verify installation:**
  ```bash
  issue --version
  ```

- [ ] **Configure backend (one-time):**
  ```bash
  export GITEA_API_TOKEN="your-token"
  issue backend add myproject gitea
  # Provide: URL, owner, repo when prompted
  issue backend set-default myproject
  ```

- [ ] **Test connection:**
  ```bash
  issue backend test myproject
  issue list --limit=5
  ```

## Project Integration

### Option 1: Agent Context File (Recommended)

- [ ] **Copy agent context to project:**
  ```bash
  mkdir -p .claude/capabilities/
  cp capabilities/issue-core/.capability/agent-context.md \
     .claude/capabilities/issue-core.md
  ```

- [ ] **Add to Claude Code context:**
  Create `.claude/context/capabilities.md`:
  ```markdown
  # Available Capabilities

  This project uses specialized capabilities. Always check these before implementing similar functionality.

  ## Issue Tracking: issue-core

  **Location:** `capabilities/issue-core/`
  **Documentation:** `.claude/capabilities/issue-core.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-core.md` for usage patterns.
  ```

### Option 2: Slash Command

- [ ] **Create slash command:**
  Create `.claude/commands/use-issues.md`:
  ```markdown
  You are working with issue tracking. Use the issue-core capability:

  **Python API:**
  ```python
  from issue_core.backends.gitea import GiteaBackend
  backend = GiteaBackend()
  backend.connect(config)
  ```

  **CLI:**
  ```bash
  issue list --format=json
  issue create "Title" --label=bug
  ```

  **Full docs:** See `capabilities/issue-core/AGENT_INTEGRATION.md`

  **DO NOT use direct API calls or platform CLIs!**
  ```

- [ ] **Test slash command:**
  ```bash
  # 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-core/config.json`:
  ```json
  {
    "agent": {
      "identity": "agent-coder",
      "type": "implementation"
    }
  }
  ```

- [ ] **Or use environment variables:**
  ```bash
  export ISSUE_AGENT_ID="agent-coder"
  export ISSUE_AGENT_TYPE="coder"
  ```

## Verification

- [ ] **Test basic operations:**
  ```python
  from issue_core.backends.gitea import GiteaBackend
  from issue_core.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:**
  ```bash
  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:**
  ```markdown
  ## Issue Tracking

  This project uses the issue-core capability for unified issue tracking.

  **Setup:**
  ```bash
  pip install -e capabilities/issue-core/
  export GITEA_API_TOKEN="your-token"
  issue backend add myproject gitea
  ```

  **Usage:** See `capabilities/issue-core/AGENT_INTEGRATION.md`
  ```

- [ ] **Add to CONTRIBUTING.md:**
  ```markdown
  ### Issue Tracking

  Always use the `issue` command or Python API from `issue_core` package.
  Never make direct API calls to Gitea/GitHub/GitLab.

  Examples: `capabilities/issue-core/examples/agents/`
  ```

## Security Review

- [ ] **Verify tokens are not in code:** `git grep GITEA_TOKEN` (should be empty)
- [ ] **Check .gitignore includes:**
  ```
  .issue-core/config.json
  .issue-core/issues.db
  .issue-core/credentials.json
  ```

- [ ] **Audit token permissions:** Read-only for bots, write for implementation
- [ ] **Document token rotation:** How often, who has access

## Testing

- [ ] **Run capability tests:**
  ```bash
  cd capabilities/issue-core/
  make test
  ```

- [ ] **Test agent workflows:**
  ```bash
  python examples/agents/simple_task_executor.py --once
  ```

- [ ] **Verify multi-agent coordination:**
  ```bash
  python examples/agents/multi_agent_pipeline.py --mode=roundrobin --max-iterations=1
  ```

## Maintenance

- [ ] **Schedule regular updates:**
  ```bash
  cd capabilities/issue-core/
  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:**
  ```bash
  # Temporarily use direct API
  export ISSUE_FACADE_DISABLED=1
  # Or
  issue backend remove myproject
  ```

- [ ] **Keep backup config:**
  ```bash
  cp ~/.config/issue-core/backends.json ~/.config/issue-core/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:**
```bash
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