issue-core/README.md

Issue Facade - Agent Coordination via Issue Tracking

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

Purpose

The Issue Facade 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

cd capabilities/issue-facade
pip install -e .

Configuration (One-Time Setup)

For Gitea-backed projects:

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

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

issue backend set-default local-work

Basic Usage

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

from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.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:

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

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

# 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

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

issue backend list
issue backend add NAME TYPE
issue backend remove NAME
issue backend test NAME
issue backend set-default NAME

Synchronization

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

Development

Testing

# 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

# Run linter
make issue-facade-lint

# Format code
black issue_tracker/ tests/

# Type check
mypy issue_tracker/

Project Structure

issue-facade/
├── issue_tracker/
│   ├── 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 - Comprehensive guide for autonomous agents

  • Programmatic API usage
  • Multi-agent coordination patterns
  • Workflow examples and strategies
  • Performance optimization
  • Current workarounds

• CLAUDE.md - Development guide for working on this codebase

  • Architecture deep-dive
  • Testing strategy
  • Adding new backends
  • Common development tasks

• 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 Facade	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 Facade 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, a collection of tools for agent-driven software development.