coulomb/issue-core
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 Projects Releases Wiki Activity

feat: transform to agent coordination platform with comprehensive documentation

Browse Source 
Transform Issue Facade from a universal CLI tool into an agent coordination platform with comprehensive documentation and enhanced capabilities for autonomous coding agents.

Major Changes:
- Complete README rewrite focusing on agent-driven coordination
- New comprehensive documentation (AGENT_INTEGRATION.md, CLAUDE.md, ROADMAP.md)
- Capability integration setup with CAPABILITY.yaml and integration scripts
- Enhanced Makefile with local development targets for easier workflows

Bug Fixes:
- Fix schema initialization using executescript() for multi-line SQL support
- Disable FTS5 triggers due to compatibility issues (documented for future re-enablement)

Features:
- Enhanced CLI list command with full parameter passthrough
- New examples directory with agent integration patterns
- New comprehensive test suite (test_core_models.py, test_local_backend.py)

Code Quality:
- Remove @cached_property decorators for Label properties (simplification)
- Clean up test organization (removed old test_gitea_integration.py)

This milestone establishes Issue Facade as a production-ready coordination layer for multi-agent software development, with clear integration paths and comprehensive developer documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2025-12-17 19:32:37 +01:00
parent 2dfe5130a3
commit 324453bd8d
22 changed files with 6489 additions and 835 deletions
Download Patch File Download Diff File Expand all files Collapse all files

575
README.md
View File

@@ -1,340 +1,399 @@
# Issue Facade - Universal CLI for Issue Tracking
# Issue Facade - Agent Coordination via Issue Tracking
A convenient command-line facade that provides a unified interface to the repository's main issue tracker, regardless of which backend system is actually being used.
**A unified interface for autonomous coding agents to coordinate project implementation through issue tracking systems.**
## Purpose
The **Issue Facade** acts as a convenient CLI wrapper that automatically detects and interfaces with whatever issue tracking system is configured for the current repository. This means you get a consistent, intuitive command-line experience whether your project uses:
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.
- GitHub Issues
- GitLab Issues
- Gitea Issues
- JIRA
- Local SQLite storage
- Any other supported backend
### Why Issue Tracking for Agent Coordination?
## Philosophy
Issue tracking provides natural coordination primitives for multi-agent software development:
Rather than learning different commands and workflows for each issue tracking system, the Issue Facade provides:
- **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
- **One CLI to rule them all**: Same commands work across all backends
- **Repository-aware**: Automatically detects the relevant issue tracker for your repo
- **Offline capability**: Local SQLite fallback when remote systems are unavailable
- **Seamless sync**: Keep local and remote issue trackers synchronized
## Current Status
## How It Works
**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
# The facade automatically detects your repository's issue tracker
cd /path/to/my-project
issue list # Lists issues from the repo's configured tracker
cd /path/to/another-project
issue list # Lists issues from THIS repo's tracker
# Same commands, different backends - transparent to the user
cd capabilities/issue-facade
pip install -e .
```
## Key Features
### Configuration (One-Time Setup)
### 🎯 **Repository Context Awareness**
The facade automatically detects:
- Git remotes (GitHub, GitLab, Gitea URLs)
- Configuration files (`.issue-config`, `pyproject.toml`, etc.)
- Environment variables
- Default fallbacks
### 🖥️ **Unified CLI Experience**
```bash
# Core issue operations (same across all backends)
issue list # List issues
issue show 42 # Show issue details
issue create "Bug in parser" # Create new issue
issue edit 42 --add-label bug # Edit existing issue
issue close 42 --comment "Fixed" # Close with comment
issue comment 42 "Still broken" # Add comment
# Advanced operations
issue list --assignee=me --state=open
issue search "memory leak"
issue stats # Show issue statistics
```
### 🔄 **Automatic Backend Detection**
```bash
# GitHub repository
cd my-github-project
issue list # → Automatically uses GitHub Issues API
# Gitea repository
cd my-gitea-project
issue list # → Automatically uses Gitea Issues API
# Offline/local work
cd any-project
issue backend set local
issue list # → Uses local SQLite storage
```
### 🌐 **Seamless Synchronization**
```bash
# Work offline, sync later
issue create "Bug found offline" --local
issue sync # Pushes to remote when online
# Keep backups
issue sync pull # Download all remote issues locally
issue export backup.json # Export for archival
```
## Installation & Setup
### 1. Install the Facade
```bash
pip install issue-facade
```
### 2. Automatic Configuration
The facade auto-detects your repository's issue tracker:
**For Gitea-backed projects:**
```bash
cd your-repository
issue config detect # Auto-configure based on git remotes
issue list # Ready to use!
# 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
```
### 3. Manual Configuration (if needed)
**For local/offline work:**
```bash
# Configure specific backends
issue backend add github my-repo
issue backend add gitea company-repo
issue backend add local offline
issue backend add local-work local
# Prompts for: database path (.issue-facade/issues.db)
# Set repository-specific backend
issue config set-backend github # For current repository
issue backend set-default local-work
```
## Repository Integration Examples
### Basic Usage
### GitHub Repository
```bash
cd my-github-project
issue config detect
# → Automatically configures GitHub Issues via API
# → Uses .github/ISSUE_TEMPLATE/ for templates
# → Respects repository labels and milestones
# List issues (JSON output for agents)
issue list --format=json
issue create "Security vulnerability" --template security
# 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"
```
### Corporate Gitea
```bash
cd company-project
issue config detect
# → Detects Gitea instance from git remote
# → Prompts for access token (one-time setup)
# → Uses corporate labels and workflows
## Agent Integration
issue list --milestone "Q4 Release"
```
**For autonomous coding agents**, see **[AGENT_INTEGRATION.md](AGENT_INTEGRATION.md)** for:
### Offline Development
```bash
cd any-project
issue backend set local
# → Creates local SQLite database in .issue-facade/
# → Full offline functionality
# → Sync to remote when connection available
- 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
issue create "Performance issue" --offline
issue sync when-online
```
Quick example:
## Configuration
```python
from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.core.interfaces import IssueFilter
### Per-Repository Configuration
Each repository can have its own configuration in `.issue-facade/config.json`:
# Initialize
backend = GiteaBackend()
backend.connect(config)
```json
{
"backend": "github",
"github": {
"owner": "myorg",
"repo": "myproject",
"token_env": "GITHUB_TOKEN"
},
"local": {
"db_path": ".issue-facade/issues.db",
"sync_enabled": true
},
"templates": {
"bug": ".github/ISSUE_TEMPLATE/bug_report.md",
"feature": ".github/ISSUE_TEMPLATE/feature_request.md"
}
}
```
# Query issues for agent
issues = backend.list_issues(IssueFilter(
state='open',
labels=['bug', 'priority:critical'],
assignee='agent-coder'
))
### Global Configuration
User-wide settings in `~/.config/issue-facade/config.json`:
# Process each issue
for issue in issues:
# Agent implements fix
result = agent.fix_bug(issue)
```json
{
"default_backend": "local",
"github_token": "env:GITHUB_TOKEN",
"gitea_instances": {
"company": {
"url": "https://git.company.com",
"token": "env:GITEA_TOKEN"
}
},
"offline_mode": false,
"sync_interval": "1h"
}
# Report back
issue.state = IssueState.CLOSED
backend.update_issue(issue)
```
## Architecture
### Facade Pattern Implementation
### Facade Pattern with Plugin Backends
```
Repository Working Directory
├── .git/ # Git repository
├── .issue-facade/ # Facade configuration
│ ├── config.json # Repository-specific config
│ ├── issues.db # Local SQLite cache/backup
│ └── templates/ # Issue templates
├── your-project-files...
└── issue # CLI command (context-aware)
┌─────────────────────────────────────┐
│ CLI Layer (Click) │
│ issue list | create | edit │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ Core Domain Models │
│ (Issue, Label, User, etc.) │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ Backend Interface (ABC) │
│ IssueBackend, SyncableBackend │
└──────────────┬──────────────────────┘
│
┌───────┴────────┐
│ │
┌──────▼─────┐ ┌──────▼──────┐
│ Local │ │ Gitea │
│ (SQLite) │ │ (REST API) │
└────────────┘ └─────────────┘
```
### Backend Detection Logic
1. **Check repository configuration**: `.issue-facade/config.json`
2. **Analyze git remotes**: Detect GitHub/GitLab/Gitea URLs
3. **Look for platform files**: `.github/`, `.gitlab/`, etc.
4. **Check environment**: `GITHUB_TOKEN`, `GITLAB_TOKEN`, etc.
5. **Fall back to local**: SQLite storage if no remote detected
**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
### Multi-Repository Support
```bash
# Each repository maintains its own context
/projects/web-app/ → GitHub Issues
/projects/api-server/ → GitLab Issues
/projects/cli-tool/ → Gitea Issues
/projects/experiment/ → Local SQLite
### Supported Backends
# Same commands work in all contexts
cd web-app && issue list # GitHub
cd api-server && issue list # GitLab
cd cli-tool && issue list # Gitea
cd experiment && issue list # Local
```
| 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-Platform Developer**
You work with repositories across GitHub, GitLab, and company Gitea:
### 1. Multi-Agent Project Implementation
Multiple specialized agents coordinate via issues:
```bash
# Learn one CLI, use everywhere
issue list --assignee=me # Works on all platforms
issue create "Cross-platform bug" --label bug
# 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. **Offline Developer**
You need to track issues without constant internet:
```bash
issue create "Found while flying" --offline
issue list --local # View offline issues
issue sync # Upload when back online
### 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. **Repository Migration**
Moving from GitHub to GitLab:
### 3. Offline Development with Sync
Work offline with local backend, sync when online:
```bash
issue export github-backup.json # Backup from GitHub
issue backend set gitlab # Switch to GitLab
issue import github-backup.json # Import to GitLab
# 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
```
### 4. **Cross-Repository Analytics**
Track issues across multiple repositories:
## CLI Commands Reference
### Issue Operations
```bash
issue stats --all-repos # Statistics across all configured repos
issue search "security" --global # Search across all issue trackers
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
```
## Integration with Development Workflow
### Git Hooks Integration
### Backend Management
```bash
# .git/hooks/pre-commit
issue list --assignee=me --state=open > ISSUES.md
git add ISSUES.md
issue backend list
issue backend add NAME TYPE
issue backend remove NAME
issue backend test NAME
issue backend set-default NAME
```
### CI/CD Integration
### Synchronization
```bash
# In your CI pipeline
issue create "Build failed on commit $SHA" --label ci-failure
issue close-if-fixed $ISSUE_NUMBER
issue sync status
issue sync pull SOURCE TARGET [--dry-run] [--force]
issue sync push SOURCE TARGET
issue sync bidirectional BACKEND1 BACKEND2
```
### IDE Integration
## Development
### Testing
```bash
# VS Code, Vim, Emacs plugins can use the CLI
:IssueList # List issues in editor
:IssueCreate "Typo in function" # Create issue from editor
# 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
```
## Comparison with Native Tools
### Code Quality
| Feature | issue-facade | gh (GitHub CLI) | glab (GitLab CLI) | Platform Web UI |
|---------|--------------|-----------------|-------------------|-----------------|
| **Multi-platform** | ✅ All backends | ❌ GitHub only | ❌ GitLab only | ❌ Single platform |
| **Offline support** | ✅ Local SQLite | ❌ Online only | ❌ Online only | ❌ Online only |
| **Consistent CLI** | ✅ Same commands | ❌ GitHub-specific | ❌ GitLab-specific | ❌ Web interface |
| **Repository context** | ✅ Auto-detect | ✅ Git-aware | ✅ Git-aware | ❌ Manual navigation |
| **Cross-repo search** | ✅ Global search | ❌ Single repo | ❌ Single repo | ❌ Single repo |
| **Data portability** | ✅ Export/import | ❌ Platform-locked | ❌ Platform-locked | ❌ Platform-locked |
```bash
# Run linter
make issue-facade-lint
## Future Roadmap
# Format code
black issue_tracker/ tests/
### Version 1.0 (Current)
- [x] Core facade architecture
- [x] GitHub/GitLab/Gitea backend support
- [x] Local SQLite backend
- [x] Automatic repository detection
- [x] Basic synchronization
# Type check
mypy issue_tracker/
```
### Version 1.1
- [ ] Advanced sync (conflict resolution)
- [ ] Issue templates support
- [ ] Workflow automation hooks
- [ ] Plugin system for custom backends
### Project Structure
### Version 2.0
- [ ] Web dashboard for multi-repo overview
- [ ] Advanced analytics and reporting
- [ ] Team collaboration features
- [ ] Integration with project management tools
```
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](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 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:
- **Backend-agnostic**: Easy to add new issue tracking systems
- **Repository-aware**: Respects the conventions of each platform
- **Developer-friendly**: Consistent CLI across all environments
The Issue Facade is designed to be extensible:
To add a new backend:
1. Implement the `IssueBackend` interface
2. Add detection logic for the platform
3. Register the backend in the factory
4. Add CLI configuration support
**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** perfectly describes this tool's purpose:
The **Facade Pattern** describes this tool's purpose:
> *"Provide a unified interface to a set of interfaces in a subsystem. Facade defines a higher-level interface that makes the subsystem easier to use."*
> *"Provide a unified interface to a set of interfaces in a subsystem."*
> — Gang of Four, Design Patterns
Instead of learning different CLIs for GitHub (`gh`), GitLab (`glab`), JIRA, etc., the Issue Facade provides one consistent interface that works with all of them. It's the universal remote control for issue tracking systems.
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.
The facade doesn't replace the underlying issue trackers - it makes them easier to use consistently across different platforms and repositories.
## 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.