issue-core/ROADMAP.md

# Issue Core Roadmap

**Long-term vision and implementation plan for agent-driven software development coordination.**

## Current Status: v1.0 (Production-Ready Core)

✅ **Complete:**
- Core CRUD operations (100%)
- Gitea backend (production-ready)
- Local SQLite backend (fully functional)
- CLI with JSON output
- Python programmatic API
- Basic synchronization
- Comprehensive test suite (109 tests, 61% coverage)

⚠️ **Limitations:**
- Manual backend configuration
- No auto-detection
- Basic conflict resolution
- Hardcoded user context

---

## Phase 1: Auto-Configuration (v1.1) - **Next Priority**

**Goal:** Enable agents to work in any repository without manual setup.

### 1.1.1 Git Remote Detection

**Implementation:**
```python
# issue_core/core/detection.py

def detect_git_remote() -> Optional[Dict[str, str]]:
    """
    Parse git remote URL to extract platform, owner, repo.

    Returns:
        {
            'platform': 'gitea' | 'github' | 'gitlab',
            'base_url': 'https://gitea.example.com',
            'owner': 'myorg',
            'repo': 'myproject'
        }
    """

def parse_remote_url(url: str) -> Optional[Dict[str, str]]:
    """
    Parse various git remote URL formats:
    - https://gitea.example.com/owner/repo.git
    - git@gitea.example.com:owner/repo.git
    - https://github.com/owner/repo
    """
```

**Tests:** `tests/test_detection.py`
- Test various URL formats (HTTPS, SSH, with/without .git)
- Test platform detection (Gitea, GitHub, GitLab)
- Test edge cases (subgroups, custom domains)

**Effort:** 2-3 days

### 1.1.2 Environment-Based Configuration

**Implementation:**
```python
# issue_core/core/env_config.py

def load_backend_from_env() -> Optional[Dict[str, Any]]:
    """
    Load backend config from environment variables:
    - GITEA_URL, GITEA_TOKEN, GITEA_OWNER, GITEA_REPO
    - GITHUB_TOKEN (with auto-detection)
    - GITLAB_URL, GITLAB_TOKEN
    """

def create_backend_from_env(platform: str) -> IssueBackend:
    """Create and connect backend from environment."""
```

**New CLI command:**
```bash
issue config auto
# Tries: git remote → environment → user prompt
```

**Tests:**
- Test environment loading with various combinations
- Test fallback priority (git → env → prompt)
- Test error handling for missing credentials

**Effort:** 2-3 days

### 1.1.3 Per-Repository Configuration Files

**Implementation:**
```
.issue-core/
├── config.json          # Repository-specific settings
├── issues.db           # Local cache/backup
└── credentials.json    # Optional encrypted credentials
```

**Config format:**
```json
{
  "backend": {
    "type": "gitea",
    "url": "https://gitea.example.com",
    "owner": "myorg",
    "repo": "myproject",
    "token_source": "env:GITEA_TOKEN"  // or "file:/path/to/token"
  },
  "sync": {
    "enabled": true,
    "interval": "1h",
    "auto_pull": false
  },
  "agent": {
    "identity": "agent-coder",
    "claim_timeout": 1800
  }
}
```

**Functions:**
```python
def load_repo_config(path: Path = Path.cwd()) -> Optional[Dict]:
    """Load .issue-core/config.json from repo root."""

def save_repo_config(config: Dict, path: Path = Path.cwd()):
    """Save config to .issue-core/config.json."""

def find_repo_root() -> Optional[Path]:
    """Walk up directory tree to find git root."""
```

**Effort:** 3-4 days

### 1.1.4 Unified Auto-Configuration

**Implementation:**
```python
# issue_core/core/auto_config.py

def auto_configure_backend() -> IssueBackend:
    """
    Auto-configure backend with fallback priority:
    1. Check .issue-core/config.json
    2. Detect from git remote + environment token
    3. Check global config (~/.config/issue-core/)
    4. Prompt user for manual configuration
    """
```

**CLI integration:**
```bash
# New commands
issue config detect          # Detect and show config (no save)
issue config init           # Detect, confirm, and save
issue config show           # Show current config
issue config edit           # Open config in $EDITOR
```

**Tests:**
- Integration test: git repo → auto-detection → working backend
- Test fallback priority
- Test config precedence

**Effort:** 3-4 days

### 1.1.5 Integration Script UX Improvements

**Problem:** Integration script has poor UX - hardcoded defaults, no backup, doesn't reuse existing config.

**Implementation:**

```bash
# .capability/integrate.sh improvements

# 1. Smart default for backend name (derive from project)
PROJECT_NAME=$(basename "$PROJECT_ROOT")
read -p "Backend name [$PROJECT_NAME]: " backend_name
backend_name="${backend_name:-$PROJECT_NAME}"

# 2. Pre-populate existing settings when replacing
if issue backend show "$backend_name" &>/dev/null; then
    echo "⚠️  Backend '$backend_name' already exists"

    # Load current values
    CURRENT_URL=$(issue backend show "$backend_name" --field=url 2>/dev/null || echo "")
    CURRENT_OWNER=$(issue backend show "$backend_name" --field=owner 2>/dev/null || echo "")
    CURRENT_REPO=$(issue backend show "$backend_name" --field=repo 2>/dev/null || echo "")

    read -p "Replace existing backend? [y/N]: " replace
    if [ "$replace" = "y" ] || [ "$replace" = "Y" ]; then
        # Create timestamped backup
        TIMESTAMP=$(date +%Y%m%d_%H%M%S)
        CONFIG_FILE="$HOME/.config/issue-core/backends.json"
        if [ -f "$CONFIG_FILE" ]; then
            BACKUP_FILE="$CONFIG_FILE.backup.$TIMESTAMP"
            cp "$CONFIG_FILE" "$BACKUP_FILE"
            echo "✓ Backed up config to: $BACKUP_FILE"
        fi

        # Offer existing values as defaults
        read -p "Gitea URL [$CURRENT_URL]: " url
        url="${url:-$CURRENT_URL}"

        read -p "Repository owner [$CURRENT_OWNER]: " owner
        owner="${owner:-$CURRENT_OWNER}"

        read -p "Repository name [$CURRENT_REPO]: " repo
        repo="${repo:-$CURRENT_REPO}"
    else
        echo "Keeping existing configuration"
        exit 0
    fi
fi
```

**Benefits:**
- Reduces typing (project name auto-detected)
- Prevents accidental config loss (automatic backups)
- Speeds up reconfiguration (existing values as defaults)
- Better error recovery (timestamped backups)

**Implementation tasks:**
1. Add `detect_project_name()` function to integration script
2. Add `load_existing_backend_config()` function
3. Add `backup_config_file()` function with timestamp
4. Update interactive prompts to use defaults from existing config
5. Add rollback instructions to output

**Tests:**
- Manual testing of integration script with various scenarios:
  - Fresh installation (no existing backend)
  - Replacing existing backend (should show defaults)
  - Backup creation and verification
  - Directory name extraction accuracy

**Effort:** 2-3 days

**Total Phase 1:** ~15-20 days (3-4 weeks)

---

## Phase 2: Agent Features (v1.2)

**Goal:** Native support for multi-agent coordination.

### 1.2.1 Agent Identity Management

**Problem:** Currently uses hardcoded "cli-user" for all operations.

**Implementation:**
```python
# issue_core/core/agent.py

@dataclass
class AgentContext:
    """Context for agent operations."""
    agent_id: str
    agent_type: str  # 'coder', 'reviewer', 'tester', etc.
    capabilities: List[str]  # ['python', 'javascript', 'testing']
    metadata: Dict[str, Any]

def get_agent_context() -> AgentContext:
    """
    Get agent context from:
    1. Environment (ISSUE_AGENT_ID, ISSUE_AGENT_TYPE)
    2. Config file (.issue-core/config.json)
    3. Default to system username
    """

def set_agent_context(context: AgentContext):
    """Set global agent context for operations."""
```

**Backend integration:**
```python
# Update all comment/assignee operations
def add_comment(self, issue_id: str, body: str):
    """Add comment with current agent context."""
    ctx = get_agent_context()
    comment = Comment(
        author=User(id=ctx.agent_id, username=ctx.agent_id),
        body=f"[{ctx.agent_type}] {body}",
        ...
    )
```

**CLI:**
```bash
issue config agent set-id "agent-coder-v1"
issue config agent set-type "coder"
issue config agent show
```

**Tests:**
- Test context loading from various sources
- Test context inheritance in backend operations
- Test agent metadata propagation

**Effort:** 4-5 days

### 1.2.2 Issue Claiming/Locking

**Problem:** No native support for claiming issues (prevents race conditions).

**Implementation:**
```python
# issue_core/core/locking.py

class IssueClaim:
    issue_id: str
    agent_id: str
    claimed_at: datetime
    expires_at: datetime
    metadata: Dict[str, Any]

class LockManager:
    """Manages issue claims/locks."""

    def claim_issue(self, issue_id: str, timeout_seconds: int = 1800) -> IssueClaim:
        """
        Claim an issue for exclusive work.
        Raises ClaimError if already claimed.
        """

    def release_issue(self, issue_id: str):
        """Release claim on issue."""

    def check_claim(self, issue_id: str) -> Optional[IssueClaim]:
        """Check if issue is claimed and by whom."""

    def extend_claim(self, issue_id: str, additional_seconds: int):
        """Extend claim timeout."""

    def cleanup_expired(self):
        """Clean up expired claims."""
```

**Storage:** Store claims in issue metadata or separate tracking table.

**For Gitea backend:**
```json
// In issue.sync_metadata
{
  "claim": {
    "agent_id": "agent-coder",
    "claimed_at": "2024-01-15T10:00:00Z",
    "expires_at": "2024-01-15T10:30:00Z"
  }
}
```

**CLI:**
```bash
issue claim 42 --timeout=30m          # Claim for 30 minutes
issue claim release 42                # Release claim
issue claim check 42                  # Check claim status
issue claim extend 42 --add-time=15m  # Extend by 15 minutes
```

**Tests:**
- Test claim acquisition and release
- Test claim expiration
- Test concurrent claim attempts (should fail)
- Test claim cleanup

**Effort:** 5-6 days

### 1.2.3 Structured Agent Metadata

**Problem:** Agent state tracked in comments (unstructured).

**Implementation:**
```python
# Extend Issue model
@dataclass
class Issue:
    ...
    agent_metadata: Dict[str, Any] = field(default_factory=dict)
    """
    Structured metadata for agent operations:
    {
        'assigned_agent': {
            'agent_id': 'agent-coder',
            'assigned_at': '2024-01-15T10:00:00Z',
            'progress': 0.75
        },
        'work_state': {
            'stage': 'implementation',
            'checkpoints': ['analysis', 'design'],
            'next_checkpoint': 'testing'
        },
        'dependencies': {
            'blocks': [43, 44],
            'blocked_by': [41]
        }
    }
    """
```

**API:**
```python
def update_agent_progress(issue: Issue, progress: float, status: str):
    """Update agent progress metadata."""

def mark_checkpoint(issue: Issue, checkpoint: str):
    """Mark a workflow checkpoint complete."""

def get_agent_state(issue: Issue) -> Dict[str, Any]:
    """Get current agent state for issue."""
```

**Effort:** 3-4 days

### 1.2.4 Webhook Support

**Problem:** Agents poll for changes (inefficient for real-time reactions).

**Implementation:**
```python
# issue_core/core/webhooks.py

class WebhookManager:
    """Manage webhooks for real-time notifications."""

    def register_webhook(
        self,
        url: str,
        events: List[str],  # ['issue.created', 'issue.updated', 'issue.closed']
        secret: Optional[str] = None
    ):
        """Register webhook with backend."""

    def validate_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
        """Validate webhook payload signature."""

# Simple webhook receiver
class WebhookReceiver:
    def start(self, port: int = 8080):
        """Start HTTP server to receive webhooks."""

    def on_event(self, event_type: str, callback: Callable):
        """Register callback for event type."""
```

**Example usage:**
```python
receiver = WebhookReceiver()

@receiver.on_event('issue.created')
def handle_new_issue(issue: Issue):
    if 'priority:critical' in [l.name for l in issue.labels]:
        agent.claim_and_process(issue)

receiver.start(port=8080)
```

**CLI:**
```bash
issue webhook register http://agent.example.com/hook --events=issue.created,issue.updated
issue webhook list
issue webhook remove <id>
```

**Effort:** 5-6 days

**Total Phase 2:** ~20-25 days (4-5 weeks)

---

## Phase 3: Advanced Coordination (v2.0)

**Goal:** Enterprise-grade multi-agent system coordination.

### 2.0.1 Issue Dependency Tracking

**Implementation:**
```python
@dataclass
class Issue:
    ...
    depends_on: List[int] = field(default_factory=list)
    blocks: List[int] = field(default_factory=list)

class DependencyGraph:
    """Manage issue dependencies."""

    def add_dependency(self, issue_id: int, depends_on: int):
        """Mark issue as depending on another."""

    def remove_dependency(self, issue_id: int, depends_on: int):
        """Remove dependency."""

    def get_blocking_issues(self, issue_id: int) -> List[Issue]:
        """Get issues blocking this one."""

    def get_blocked_issues(self, issue_id: int) -> List[Issue]:
        """Get issues blocked by this one."""

    def can_start(self, issue_id: int) -> bool:
        """Check if all dependencies are resolved."""

    def get_ready_issues(self) -> List[Issue]:
        """Get all issues with no blocking dependencies."""
```

**CLI:**
```bash
issue depends add 42 --blocks=43,44     # 42 blocks 43 and 44
issue depends remove 42 --blocks=43
issue depends show 42                   # Show dependency graph
issue depends ready                     # List issues ready to start
```

**Effort:** 6-7 days

### 2.0.2 Query DSL

**Problem:** Filtering is verbose and limited.

**Implementation:**
```python
# issue_core/core/query_dsl.py

class QueryParser:
    """
    Parse query DSL:
    - is:open is:closed is:in-progress
    - assignee:me assignee:agent-coder
    - label:bug,priority:high
    - created:>7d updated:<24h
    - milestone:"Q1 Release"
    - sort:created-desc sort:priority
    """

    def parse(self, query: str) -> IssueFilter:
        """Parse query string into IssueFilter."""

# Examples:
# "is:open assignee:me label:bug,critical"
# "is:closed created:>30d sort:closed-desc"
# "label:needs-review -label:blocked"  # exclude label
```

**CLI:**
```bash
issue search "is:open assignee:me label:bug,priority:high"
issue list --query="is:in-progress created:>7d"
```

**Effort:** 5-6 days

### 2.0.3 Activity Streams & Event Logs

**Implementation:**
```python
# issue_core/core/activity.py

@dataclass
class ActivityEvent:
    event_type: str  # 'issue.created', 'issue.updated', 'comment.added'
    issue_id: str
    actor_id: str
    timestamp: datetime
    changes: Dict[str, Any]
    metadata: Dict[str, Any]

class ActivityStream:
    """Track all issue activity."""

    def log_event(self, event: ActivityEvent):
        """Log an activity event."""

    def get_issue_activity(self, issue_id: str) -> List[ActivityEvent]:
        """Get all activity for an issue."""

    def get_agent_activity(self, agent_id: str) -> List[ActivityEvent]:
        """Get all activity by an agent."""

    def stream_events(self, since: datetime) -> Iterator[ActivityEvent]:
        """Stream events since timestamp."""
```

**Storage:** Add `activity_log` table to schema.

**Effort:** 6-7 days

### 2.0.4 Distributed Locking

**Problem:** Current locking is local only (single instance).

**Implementation:**
```python
# issue_core/core/distributed_lock.py

class DistributedLockManager:
    """Distributed locking using Redis/database."""

    def __init__(self, redis_url: Optional[str] = None):
        """Use Redis if available, fallback to database."""

    def acquire_lock(
        self,
        resource: str,
        owner: str,
        ttl: int = 30
    ) -> bool:
        """Acquire distributed lock."""

    def release_lock(self, resource: str, owner: str):
        """Release distributed lock."""

    def extend_lock(self, resource: str, owner: str, additional_ttl: int):
        """Extend lock TTL."""

    def is_locked(self, resource: str) -> bool:
        """Check if resource is locked."""
```

**Integration:**
```python
# Use for claim operations
with distributed_lock(f"issue:{issue_id}", agent_id):
    # Work on issue
    pass
```

**Effort:** 7-8 days

### 2.0.5 Conflict Resolution Strategies

**Problem:** Sync has basic conflict detection but no resolution.

**Implementation:**
```python
# issue_core/core/sync_strategies.py

class ConflictResolutionStrategy(ABC):
    def resolve(self, local: Issue, remote: Issue) -> Issue:
        """Resolve conflict between local and remote."""

class TimestampStrategy(ConflictResolutionStrategy):
    """Take newer version based on updated_at."""

class ThreeWayMergeStrategy(ConflictResolutionStrategy):
    """Three-way merge using common ancestor."""

class InteractiveMergeStrategy(ConflictResolutionStrategy):
    """Prompt user to resolve conflicts."""

class AgentMergeStrategy(ConflictResolutionStrategy):
    """Use agent to intelligently merge changes."""

def sync_with_strategy(
    source: IssueBackend,
    target: IssueBackend,
    strategy: ConflictResolutionStrategy
):
    """Sync with specified conflict resolution strategy."""
```

**Effort:** 8-10 days

**Total Phase 3:** ~35-40 days (7-8 weeks)

---

## Phase 4: Platform Expansion (Future)

### GitHub Backend
- Full API integration
- GitHub-specific features (projects, discussions)
- **Effort:** 10-12 days

### GitLab Backend
- Full API integration
- GitLab-specific features (epics, boards)
- **Effort:** 10-12 days

### JIRA Backend
- REST API integration
- JIRA workflow mapping
- **Effort:** 12-15 days

### Linear Backend
- GraphQL API integration
- Linear-specific features
- **Effort:** 8-10 days

---

## Implementation Priority

### Critical Path (for agent use)
1. **Auto-configuration** (Phase 1.1) - 2-3 weeks
2. **Agent identity** (Phase 2.1) - 1 week
3. **Issue claiming** (Phase 2.2) - 1 week

**Total:** ~5-6 weeks to full agent-ready state

### Nice to Have
4. Agent metadata (Phase 2.3)
5. Webhooks (Phase 2.4)
6. Dependency tracking (Phase 3.1)
7. Query DSL (Phase 3.2)

### Future Enhancements
8. Activity streams (Phase 3.3)
9. Distributed locking (Phase 3.4)
10. Advanced merge (Phase 3.5)

---

## Success Metrics

### Phase 1 Success
- [ ] Agent can work in any repo with zero manual config
- [ ] Environment-only setup works: `GITEA_TOKEN=xxx issue list`
- [ ] Auto-detection accuracy: >95% for common platforms

### Phase 2 Success
- [ ] Multiple agents can coordinate without race conditions
- [ ] Agent identity propagates to all operations
- [ ] Claim/lock prevents concurrent work on same issue

### Phase 3 Success
- [ ] Complex dependency chains work correctly
- [ ] Query DSL covers 90% of common queries
- [ ] Real-time event processing with <1s latency

---

## Migration Path

Each phase maintains backward compatibility:

**Phase 1:**
- Old: Manual `issue backend add` still works
- New: Auto-detection as optional enhancement

**Phase 2:**
- Old: Hardcoded user still works for CLI
- New: Agent context for programmatic use

**Phase 3:**
- Old: Basic filtering still works
- New: Query DSL as superset of old filters

---

## Contributing

Want to help implement these features?

1. Pick a feature from Phase 1 or 2
2. Create issue: `issue create "Implement <feature>" --label=enhancement`
3. See `CLAUDE.md` for development guide
4. Follow architecture in `core/interfaces.py`
5. Add tests (maintain >60% coverage)
6. Submit PR

**Quick wins for new contributors:**
- Environment config loading (Phase 1.1.2)
- Git remote parsing (Phase 1.1.1)
- Agent context API (Phase 2.1)

---

## Version Timeline (Estimate)

- **v1.0** (Current) - Production-ready core
- **v1.1** (Q1 2025) - Auto-configuration
- **v1.2** (Q2 2025) - Agent features
- **v2.0** (Q3 2025) - Advanced coordination
- **v2.1** (Q4 2025) - Additional platforms

*Timeline assumes single developer part-time. Can accelerate with contributors.*

---

## Questions or Feedback?

- **Architecture questions:** See `CLAUDE.md`
- **Agent integration:** See `AGENT_INTEGRATION.md`
- **Examples:** See `examples/agents/`
- **Issues:** Create issue in main repository