issue-core/README.md

# Issue Core - Agent Coordination via Issue Tracking

**A unified interface for autonomous coding agents to coordinate project implementation through issue tracking systems.**

## Purpose

The **Issue Core** provides a standardized abstraction layer for coding agents to interact with issue tracking backends (Gitea, GitHub, GitLab, local SQLite). Instead of each agent implementing platform-specific API integrations, they use one consistent interface that works across all backends.

### Why Issue Tracking for Agent Coordination?

Issue tracking provides natural coordination primitives for multi-agent software development:

- **Task Distribution**: Issues represent discrete work units agents can claim and execute
- **Progress Tracking**: States (open → in_progress → closed) track work across the team
- **Communication**: Comments enable agent-to-agent and agent-to-human communication
- **Visibility**: Labels, assignees, and milestones provide real-time project status
- **Human Integration**: Humans can seamlessly participate in agent-driven development

## Current Status

**Production-ready core with manual setup** (v1.0)

✅ **Fully Implemented:**
- Complete CRUD operations (issues, labels, users, milestones, comments)
- Gitea backend (production-ready with full API integration)
- Local SQLite backend (offline work with sync capability)
- CLI with JSON output for machine parsing
- Python API for programmatic access
- Comprehensive filtering and search
- Basic synchronization between backends

⚠️ **Current Limitations:**
- Manual backend configuration required (one-time setup per project)
- No auto-detection from git remotes (coming in v1.1)
- Basic conflict resolution (manual intervention for complex cases)
- Hardcoded user context (agents need external identity management)

## Quick Start

### Installation

```bash
cd capabilities/issue-core
pip install -e .                  # CLI only
pip install -e ".[api]"           # CLI + REST ingestion server
```

### REST Ingestion Server

issue-core exposes `POST /issues/` for upstream emitters (primarily
activity-core's `IssueSink`). Launch with:

```bash
export ISSUE_CORE_API_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
issue serve --host 0.0.0.0 --port 8765
```

Clients authenticate with `Authorization: Bearer <key>` or `X-API-Key: <key>`.
See `SCOPE.md` "TaskSpec payload" for the request schema, or visit
`http://<host>:<port>/docs` once the server is running for live OpenAPI docs.

### Configuration (One-Time Setup)

**For Gitea-backed projects:**

```bash
# Set your Gitea token
export GITEA_API_TOKEN="your-token-here"

# Configure backend
issue backend add myproject gitea
# Prompts for: URL, owner, repo (reads token from environment)

# Set as default
issue backend set-default myproject

# Verify
issue backend test myproject
```

**For local/offline work:**

```bash
issue backend add local-work local
# Prompts for: database path (.issue-core/issues.db)

issue backend set-default local-work
```

### Basic Usage

```bash
# List issues (JSON output for agents)
issue list --format=json

# Create issue
issue create "Implement user authentication" \
  --label=feature --label=priority:high

# Update state
issue edit 42 --state=in_progress --assignee=agent-coder

# Add comment
issue comment 42 "Implementation complete, tests passing"

# Close issue
issue close 42 --comment="Ready for review"
```

## Agent Integration

**For autonomous coding agents**, see **[AGENT_INTEGRATION.md](AGENT_INTEGRATION.md)** for:

- Programmatic Python API usage
- Multi-agent coordination patterns
- Agent workflow examples
- Label-based role assignment
- State machine workflows
- Comment-based communication protocols
- Workarounds for current limitations
- Performance optimization tips

Quick example:

```python
from issue_core.backends.gitea import GiteaBackend
from issue_core.core.interfaces import IssueFilter

# Initialize
backend = GiteaBackend()
backend.connect(config)

# Query issues for agent
issues = backend.list_issues(IssueFilter(
    state='open',
    labels=['bug', 'priority:critical'],
    assignee='agent-coder'
))

# Process each issue
for issue in issues:
    # Agent implements fix
    result = agent.fix_bug(issue)

    # Report back
    issue.state = IssueState.CLOSED
    backend.update_issue(issue)
```

## Architecture

### Facade Pattern with Plugin Backends

```
┌─────────────────────────────────────┐
│      CLI Layer (Click)              │
│   issue list | create | edit        │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│   Core Domain Models                │
│   (Issue, Label, User, etc.)        │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│   Backend Interface (ABC)           │
│   IssueBackend, SyncableBackend     │
└──────────────┬──────────────────────┘
               │
       ┌───────┴────────┐
       │                │
┌──────▼─────┐   ┌──────▼──────┐
│   Local    │   │   Gitea     │
│  (SQLite)  │   │  (REST API) │
└────────────┘   └─────────────┘
```

**Key Design Principles:**
- Backend-agnostic core models
- Plugin architecture for easy backend addition
- Type-safe interfaces with comprehensive testing
- Sync support for offline/online workflows

### Supported Backends

| Backend | Status | Features |
|---------|--------|----------|
| **Gitea** | ✅ Production | Full API, rate limiting, state mapping |
| **Local SQLite** | ✅ Production | Offline work, fast queries, sync support |
| **GitHub** | 🚧 Planned (v1.1) | Full API integration |
| **GitLab** | 🚧 Planned (v1.2) | Full API integration |

## Use Cases

### 1. Multi-Agent Project Implementation

Multiple specialized agents coordinate via issues:

```bash
# Agent 1 (Coder): Claims and implements features
issue list --label=needs-implementation --format=json | \
  jq -r '.[0].number' | \
  xargs -I {} issue edit {} --assignee=agent-coder --state=in_progress

# Agent 2 (Reviewer): Reviews completed work
issue list --label=needs-review --format=json | \
  jq -r '.[0].number' | \
  xargs -I {} issue comment {} "Code review: Approved"

# Agent 3 (Tester): Runs tests
issue list --label=reviewed --format=json | \
  jq -r '.[0].number' | \
  xargs -I {} issue comment {} "Tests passing: 100%"
```

### 2. Agent-Human Collaboration

Agents propose implementations, humans approve:

```python
# Agent creates subtasks from human requirements
feature = backend.get_issue_by_number(100)
for subtask in agent.break_down_feature(feature):
    backend.create_issue(subtask)

# Human reviews and approves via comments
# Agent monitors and proceeds with implementation
```

### 3. Offline Development with Sync

Work offline with local backend, sync when online:

```bash
# Setup local backup
issue backend add backup local
issue sync pull gitea-production backup

# Work offline
issue backend set-default backup
issue create "Offline implementation" --label=offline

# Sync back
issue sync push backup gitea-production
```

## CLI Commands Reference

### Issue Operations
```bash
issue list [--state STATE] [--label LABEL] [--assignee USER] [--format FORMAT]
issue show ISSUE_NUMBER [--comments] [--format FORMAT]
issue create TITLE [--description DESC] [--label LABEL] [--assignee USER]
issue edit ISSUE_NUMBER [--title TITLE] [--state STATE] [--add-label LABEL]
issue close ISSUE_NUMBER [--comment COMMENT]
issue reopen ISSUE_NUMBER [--comment COMMENT]
issue comment ISSUE_NUMBER BODY
```

### Backend Management
```bash
issue backend list
issue backend add NAME TYPE
issue backend remove NAME
issue backend test NAME
issue backend set-default NAME
```

### Synchronization
```bash
issue sync status
issue sync pull SOURCE TARGET [--dry-run] [--force]
issue sync push SOURCE TARGET
issue sync bidirectional BACKEND1 BACKEND2
```

## Development

### Testing

```bash
# Install with dev dependencies
make install-dev

# Run all tests (109 tests, 61% coverage)
make test

# Run with coverage report
make test-cov

# Run only unit tests
make test-unit
```

### Code Quality

```bash
# Run linter
make issue-core-lint

# Format code
black issue_core/ tests/

# Type check
mypy issue_core/
```

### Project Structure

```
issue-core/
├── issue_core/
│   ├── core/              # Domain models and interfaces
│   │   ├── models.py      # Issue, Label, User, etc.
│   │   └── interfaces.py  # IssueBackend, SyncableBackend
│   ├── backends/
│   │   ├── gitea/         # Gitea backend implementation
│   │   └── local/         # SQLite backend implementation
│   └── cli/               # Click-based CLI
│       ├── commands.py    # Issue operations
│       ├── backend_commands.py
│       └── sync_commands.py
├── tests/                 # 109 tests, comprehensive coverage
├── examples/              # Agent integration examples
├── AGENT_INTEGRATION.md   # Agent coordination guide
├── CLAUDE.md             # Development guide for Claude Code
└── ROADMAP.md            # Future enhancements
```

## Documentation

- **[AGENT_INTEGRATION.md](AGENT_INTEGRATION.md)** - Comprehensive guide for autonomous agents
  - Programmatic API usage
  - Multi-agent coordination patterns
  - Workflow examples and strategies
  - Performance optimization
  - Current workarounds

- **[CLAUDE.md](CLAUDE.md)** - Development guide for working on this codebase
  - Architecture deep-dive
  - Testing strategy
  - Adding new backends
  - Common development tasks

- **[ROADMAP.md](ROADMAP.md)** - Planned features and implementation timeline

## Roadmap

### v1.1 - Auto-Configuration (Next)
- Automatic git remote detection
- Environment-variable-only setup
- Per-repository configuration files
- `issue config detect` command

### v1.2 - Agent Features
- Agent identity management
- Issue claiming/locking API
- Webhook support for reactive agents
- Structured metadata for agent state

### v2.0 - Advanced Coordination
- Issue dependency tracking
- Query DSL for complex filters
- Activity streams and event logs
- Distributed locking for concurrent operations

## Comparison with Platform CLIs

| Feature | Issue Core | gh (GitHub) | glab (GitLab) |
|---------|--------------|-------------|---------------|
| Multi-backend support | ✅ Yes | ❌ GitHub only | ❌ GitLab only |
| Offline capability | ✅ Local SQLite | ❌ No | ❌ No |
| Agent-friendly API | ✅ Python + JSON | ⚠️ CLI only | ⚠️ CLI only |
| Consistent interface | ✅ Same across all | ❌ Platform-specific | ❌ Platform-specific |
| Backend sync | ✅ Yes | ❌ No | ❌ No |
| Auto-configuration | 🚧 Coming v1.1 | ✅ Yes | ✅ Yes |

## Contributing

The Issue Core is designed to be extensible:

**To add a new backend:**
1. Implement the `IssueBackend` interface (see `core/interfaces.py`)
2. Handle platform-specific API details in your backend
3. Map platform models to/from core domain models
4. Add comprehensive tests
5. Register in `BackendFactory`

**Backend implementation checklist:**
- [ ] All CRUD operations (issues, labels, users, milestones, comments)
- [ ] State mapping to/from platform-specific states
- [ ] Error handling and rate limiting
- [ ] Sync support (if applicable)
- [ ] Integration tests with mock API
- [ ] Documentation

See existing backends (Gitea, Local) as reference implementations.

## Why "Facade"?

The **Facade Pattern** describes this tool's purpose:

> *"Provide a unified interface to a set of interfaces in a subsystem."*
> — Gang of Four, Design Patterns

Instead of coding agents learning different APIs for GitHub (`gh`), GitLab (`glab`), Gitea, JIRA, etc., they use one consistent interface. The facade doesn't replace issue trackers—it makes them easier to use uniformly.

## License

MIT License - See LICENSE file

## Part of MarkiTect

This capability is part of the [MarkiTect Project](https://github.com/markitect), a collection of tools for agent-driven software development.