syndarix/docs/BACKLOG.md

# Syndarix Backlog

**Generated:** 2025-12-30
**Status:** Ready for Gitea import

This document contains detailed issues for Phase 0-1 implementation. Each issue is structured for parallel agent work.

---

## Labels

Create these labels in Gitea first:

| Label | Color | Description |
|-------|-------|-------------|
| `phase-0` | #0052CC | Phase 0: Foundation |
| `phase-1` | #00875A | Phase 1: Core Platform |
| `backend` | #5319E7 | Backend work |
| `frontend` | #F9A825 | Frontend work |
| `devops` | #212121 | DevOps/Infrastructure work |
| `database` | #006B75 | Database/migrations |
| `design` | #D4388C | UI/UX design work |
| `blocked` | #B60205 | Blocked by dependency |
| `epic` | #7057FF | Epic/parent issue |

---

## Phase 0: Foundation

### EPIC: Phase 0 - Foundation Infrastructure

**Issue #E01: [EPIC] Phase 0 - Foundation Infrastructure**

```
Title: [EPIC] Phase 0 - Foundation Infrastructure
Labels: epic, phase-0, devops

## Overview
Complete the remaining foundation infrastructure setup for Syndarix development.

## Child Issues
- [ ] #01 Configure CI/CD pipelines
- [ ] #02 Set up development environment documentation
- [ ] #03 Configure Redis for cache + pub/sub
- [ ] #04 Set up Celery worker infrastructure
- [ ] #05 Configure pgvector extension
- [ ] #06 Create MCP server directory structure
- [ ] #07 Set up Docker Compose for local development

## Success Criteria
- All developers can run the full stack locally
- CI/CD runs tests on every PR
- All infrastructure components healthy
```

---

### Issue #01: Configure CI/CD pipelines

```
Title: Configure CI/CD pipelines for Syndarix
Labels: phase-0, devops

## Description
Set up Gitea Actions CI/CD pipeline for the Syndarix repository.

## Requirements

### Backend Pipeline
- Run `uv run ruff check app` (linting)
- Run `uv run mypy app` (type checking)
- Run `IS_TEST=True uv run pytest --cov=app` (tests with coverage)
- Coverage threshold: 90% for new code

### Frontend Pipeline
- Run `npm run lint` (ESLint)
- Run `npm run type-check` (TypeScript)
- Run `npm test` (Jest unit tests)

### Pipeline Structure
1. `lint` job (fast feedback)
2. `test` job (depends on lint)
3. `build` job (depends on test)
4. `deploy` job (only on main, depends on build)

## Acceptance Criteria
- [ ] `.gitea/workflows/ci.yaml` created
- [ ] Backend linting, typing, and tests pass
- [ ] Frontend linting, typing, and tests pass
- [ ] Coverage reports generated
- [ ] Pipeline fails on any check failure
- [ ] Documentation updated

## Technical Notes
- Use `uv` for Python dependency management
- Reference: ADR-003 (Celery/Redis architecture)
- Celery workers not needed for CI tests

## Assignable To
devops-engineer agent
```

---

### Issue #02: Development environment documentation

```
Title: Create development environment setup documentation
Labels: phase-0, devops

## Description
Write comprehensive documentation for setting up the Syndarix development environment.

## Requirements

### Documentation Contents
1. Prerequisites (Python 3.12+, Node 20+, Docker, uv)
2. Repository cloning and setup
3. Environment variables configuration
4. Database setup (PostgreSQL with pgvector)
5. Redis setup
6. Running the backend (`uv run uvicorn`)
7. Running the frontend (`npm run dev`)
8. Running with Docker Compose
9. Running tests
10. Common troubleshooting

### File Structure
- `docs/DEVELOPMENT.md` - Main setup guide
- `docs/TROUBLESHOOTING.md` - Common issues and solutions

## Acceptance Criteria
- [ ] Fresh developer can set up environment following docs only
- [ ] All commands tested and working
- [ ] Environment variable templates provided
- [ ] Troubleshooting section covers common issues

## Technical Notes
- Reference existing README.md but expand significantly
- Include both local and Docker-based setup options

## Assignable To
devops-engineer agent
```

---

### Issue #03: Configure Redis for cache and pub/sub

```
Title: Configure Redis for cache and pub/sub
Labels: phase-0, devops, backend

## Description
Set up Redis configuration for caching and real-time event pub/sub.

## Requirements

### Redis Configuration
- Connection pooling
- Health check endpoint
- Separate logical databases or key prefixes for:
  - Cache (sessions, API responses)
  - Pub/Sub (real-time events)
  - Celery broker

### Backend Integration
- Create `app/core/redis.py` with Redis client setup
- Add health check for Redis in `/health` endpoint
- Configure connection string from environment

### Docker Compose
- Add Redis service with health check
- Volume for persistence
- Expose port for local development

## Acceptance Criteria
- [ ] Redis service in Docker Compose
- [ ] Health check endpoint includes Redis status
- [ ] Connection pooling configured
- [ ] Cache operations working (set/get/expire)
- [ ] Pub/sub working (publish/subscribe)
- [ ] Tests for Redis operations

## Technical Notes
- Reference: ADR-003 (Redis for cache/pub-sub)
- Reference: SPIKE-003 (Real-time communication)
- Use `redis.asyncio` for async support

## Assignable To
backend-engineer agent (primary)
devops-engineer agent (Docker Compose)
```

---

### Issue #04: Set up Celery worker infrastructure

```
Title: Set up Celery worker infrastructure
Labels: phase-0, devops, backend

## Description
Configure Celery for background task processing with Redis as broker.

## Requirements

### Queue Configuration
Per ADR-003:
| Queue | Workers | Purpose |
|-------|---------|---------|
| agent | 4 | High-priority agent tasks |
| git | 2 | Git operations |
| sync | 2 | Issue synchronization |
| default | 2 | General tasks |

### Backend Integration
- Create `app/core/celery_app.py` with Celery configuration
- Create `app/tasks/` directory structure
- Create sample task for testing

### Docker Compose
- Add Celery worker service per queue
- Add Celery beat for scheduled tasks (optional for Phase 0)
- Health checks for workers

### Monitoring
- Flower for Celery monitoring (optional for Phase 0)

## Acceptance Criteria
- [ ] Celery app configured with Redis broker
- [ ] All 4 queues defined and routable
- [ ] Worker services in Docker Compose
- [ ] Sample task executes successfully
- [ ] Workers restart on failure
- [ ] Health checks pass

## Technical Notes
- Reference: ADR-003 (Celery task queue architecture)
- Reference: SPIKE-002 (Agent orchestration patterns)
- Use `celery[redis]` package

## Assignable To
backend-engineer agent (Celery config)
devops-engineer agent (Docker Compose)
```

---

### Issue #05: Configure pgvector extension

```
Title: Configure pgvector extension for PostgreSQL
Labels: phase-0, devops, database

## Description
Set up pgvector extension for vector similarity search (RAG knowledge base).

## Requirements

### Database Configuration
- Use `pgvector/pgvector:pg17` Docker image
- Enable pgvector extension via migration
- Create vector index configuration utilities

### Migration
- Create migration to enable pgvector extension
- Document vector dimension choices (1536 for OpenAI, 1024 for Cohere)

### Testing
- Verify extension loads correctly
- Test basic vector operations

## Acceptance Criteria
- [ ] Docker Compose uses pgvector image
- [ ] Migration enables pgvector extension
- [ ] Vector operations working (cosine similarity)
- [ ] Health check includes pgvector status
- [ ] Documentation for vector dimension choices

## Technical Notes
- Reference: ADR-007 (pgvector for RAG)
- Reference: SPIKE-006 (pgvector RAG research)
- Default to 1536 dimensions (OpenAI embedding size)

## Assignable To
devops-engineer agent (Docker)
backend-engineer agent (migration)
```

---

### Issue #06: Create MCP server directory structure

```
Title: Create MCP server directory structure
Labels: phase-0, backend

## Description
Set up the directory structure and base classes for MCP (Model Context Protocol) servers.

## Requirements

### Directory Structure
```
mcp/
├── __init__.py
├── base/
│   ├── __init__.py
│   ├── server.py         # Base MCP server class
│   └── types.py          # Common MCP types
├── llm_gateway/          # Phase 2
├── knowledge_base/       # Phase 2
├── git_ops/              # Phase 2
├── issues/               # Phase 2
└── README.md             # MCP development guide
```

### Base Server Class
- FastMCP-based server template
- Standard tool registration pattern
- Project scoping utilities
- Error handling patterns

### Documentation
- How to create a new MCP server
- Tool naming conventions
- Project scoping requirements

## Acceptance Criteria
- [ ] Directory structure created
- [ ] Base server class with project scoping
- [ ] Type definitions for common patterns
- [ ] README with development guide
- [ ] Example tool registration

## Technical Notes
- Reference: ADR-004 (MCP-first architecture)
- Reference: ADR-005 (LiteLLM integration via MCP)
- All tools must accept `project_id` for scoping

## Assignable To
backend-engineer agent
```

---

### Issue #07: Set up Docker Compose for local development

```
Title: Set up complete Docker Compose for local development
Labels: phase-0, devops

## Description
Create comprehensive Docker Compose configuration for running the full Syndarix stack locally.

## Requirements

### Services
1. `db` - PostgreSQL with pgvector
2. `redis` - Cache and message broker
3. `backend` - FastAPI application
4. `frontend` - Next.js application
5. `celery-agent` - Celery worker (agent queue)
6. `celery-git` - Celery worker (git queue)
7. `celery-sync` - Celery worker (sync queue)
8. `celery-default` - Celery worker (default queue)

### Configuration
- Health checks for all services
- Proper dependency ordering (`depends_on` with conditions)
- Volume mounts for development (hot reload)
- Environment variable templates
- Resource limits (optional for dev)

### Files
- `docker-compose.yaml` - Main compose file
- `docker-compose.override.yaml` - Development overrides
- `.env.example` - Environment template

## Acceptance Criteria
- [ ] All services start with `docker compose up`
- [ ] Health checks pass for all services
- [ ] Hot reload works for backend and frontend
- [ ] Database data persists across restarts
- [ ] All services can communicate
- [ ] Documented in DEVELOPMENT.md

## Technical Notes
- Reference: Issue #03 (Redis), #04 (Celery), #05 (pgvector)
- This issue depends on #03, #04, #05 completion

## Dependencies
- Blocked by: #03, #04, #05

## Assignable To
devops-engineer agent
```

---

## Phase 1: Core Platform

### EPIC: Phase 1 - Core Platform

**Issue #E02: [EPIC] Phase 1 - Core Platform**

```
Title: [EPIC] Phase 1 - Core Platform
Labels: epic, phase-1

## Overview
Build the basic project and agent management system without LLM integration.

## Child Issues

### Data Model (1.1)
- [ ] #08 Create Project entity and CRUD
- [ ] #09 Create AgentType entity and CRUD
- [ ] #10 Create AgentInstance entity and CRUD
- [ ] #11 Create Issue entity with external tracker fields
- [ ] #12 Create Sprint entity and CRUD

### API Layer (1.2)
- [ ] #13 Project management API endpoints
- [ ] #14 Agent type configuration API endpoints
- [ ] #15 Agent instance management API endpoints
- [ ] #16 Issue CRUD API endpoints
- [ ] #17 Sprint management API endpoints

### Real-time Infrastructure (1.3)
- [ ] #18 Implement EventBus with Redis Pub/Sub
- [ ] #19 Create SSE endpoint for project events
- [ ] #20 Client-side SSE handling

### Frontend Foundation (1.4)
- [ ] #21 [DESIGN] Project dashboard page
- [ ] #22 [DESIGN] Agent configuration UI
- [ ] #23 [DESIGN] Issue list and detail views
- [ ] #24 [DESIGN] Real-time activity feed component
- [ ] #25 Implement project dashboard
- [ ] #26 Implement agent configuration UI
- [ ] #27 Implement issue views
- [ ] #28 Implement activity feed
- [ ] #29 Navigation and layout

## Success Criteria
- CRUD operations for all core entities
- Real-time event streaming working
- Basic admin UI for configuration
```

---

### Issue #08: Create Project entity and CRUD

```
Title: Create Project entity and CRUD operations
Labels: phase-1, backend, database

## Description
Implement the Project entity and all CRUD operations.

## Requirements

### Entity Fields
```python
class Project(Base):
    id: UUID
    name: str
    slug: str  # URL-friendly identifier
    description: Optional[str]
    autonomy_level: AutonomyLevel  # FULL_CONTROL, MILESTONE, AUTONOMOUS
    status: ProjectStatus  # ACTIVE, PAUSED, COMPLETED, ARCHIVED
    settings: dict  # JSON field for project-specific settings
    owner_id: UUID  # FK to User

    # Relationships
    sprints: List[Sprint]
    agent_instances: List[AgentInstance]
    issues: List[Issue]

    # Timestamps
    created_at: datetime
    updated_at: datetime
```

### Enums
```python
class AutonomyLevel(str, Enum):
    FULL_CONTROL = "full_control"  # Approve every action
    MILESTONE = "milestone"        # Approve sprint boundaries
    AUTONOMOUS = "autonomous"      # Only major decisions

class ProjectStatus(str, Enum):
    ACTIVE = "active"
    PAUSED = "paused"
    COMPLETED = "completed"
    ARCHIVED = "archived"
```

### CRUD Operations
- `create(db, obj_in: ProjectCreate) -> Project`
- `get(db, id: UUID) -> Optional[Project]`
- `get_by_slug(db, slug: str) -> Optional[Project]`
- `get_multi_by_owner(db, owner_id: UUID) -> List[Project]`
- `update(db, db_obj: Project, obj_in: ProjectUpdate) -> Project`
- `delete(db, id: UUID) -> None`

### Tests
- Unit tests for all CRUD operations
- Test slug uniqueness
- Test owner relationship
- Test status transitions

## Acceptance Criteria
- [ ] Model defined with all fields
- [ ] Migration created and applied
- [ ] CRUD class with all methods
- [ ] Pydantic schemas (Create, Update, InDB, Response)
- [ ] Unit tests with >90% coverage
- [ ] Async patterns (SQLAlchemy 2.0 style)

## Technical Notes
- Reference: ADR-009 (Issue synchronization architecture)
- Follow existing CRUD patterns from PragmaStack
- Use custom exceptions from `app.core.exceptions`

## Assignable To
backend-engineer agent
```

---

### Issue #09: Create AgentType entity and CRUD

```
Title: Create AgentType entity and CRUD operations
Labels: phase-1, backend, database

## Description
Implement the AgentType entity representing agent templates.

## Requirements

### Entity Fields
```python
class AgentType(Base):
    id: UUID
    name: str  # e.g., "Product Owner", "Backend Engineer"
    slug: str  # URL-friendly
    description: str
    expertise: List[str]  # JSON array of expertise areas
    personality_prompt: str  # System prompt defining personality

    # Model Configuration
    primary_model: str  # e.g., "claude-opus-4.5"
    fallback_models: List[str]  # JSON array, in order of preference
    model_params: dict  # temperature, max_tokens, etc.

    # MCP Configuration
    mcp_servers: List[str]  # Which MCP servers this agent can use
    tool_permissions: dict  # Tool-level permissions

    # Metadata
    is_active: bool
    created_at: datetime
    updated_at: datetime
```

### CRUD Operations
- `create(db, obj_in: AgentTypeCreate) -> AgentType`
- `get(db, id: UUID) -> Optional[AgentType]`
- `get_by_slug(db, slug: str) -> Optional[AgentType]`
- `get_all_active(db) -> List[AgentType]`
- `update(db, db_obj: AgentType, obj_in: AgentTypeUpdate) -> AgentType`
- `delete(db, id: UUID) -> None` (soft delete via is_active)

### Seed Data
Create initial agent types:
- Product Owner
- Business Analyst
- Solutions Architect
- Backend Engineer
- Frontend Engineer
- QA Engineer
- DevOps Engineer

### Tests
- CRUD operations
- Model configuration validation
- MCP server permissions

## Acceptance Criteria
- [ ] Model defined with all fields
- [ ] Migration created
- [ ] CRUD operations implemented
- [ ] Pydantic schemas
- [ ] Seed data script
- [ ] Unit tests with >90% coverage

## Technical Notes
- Reference: ADR-002 (Agent orchestration)
- Reference: SPIKE-002 (Agent orchestration research)
- `model_params` should be validated against known LLM parameters

## Assignable To
backend-engineer agent
```

---

### Issue #10: Create AgentInstance entity and CRUD

```
Title: Create AgentInstance entity and CRUD operations
Labels: phase-1, backend, database

## Description
Implement AgentInstance entity representing spawned agents working on projects.

## Requirements

### Entity Fields
```python
class AgentInstance(Base):
    id: UUID
    agent_type_id: UUID  # FK to AgentType
    project_id: UUID  # FK to Project

    # Instance State
    status: AgentStatus  # IDLE, WORKING, WAITING, PAUSED, TERMINATED
    current_task: Optional[str]  # Description of current work

    # Memory (per SPIKE-002)
    short_term_memory: dict  # Current context, clears between tasks
    long_term_memory_ref: Optional[str]  # Reference to RAG collection

    # Session
    session_id: Optional[str]  # Current active session
    last_activity_at: Optional[datetime]

    # Metrics
    tasks_completed: int
    tokens_used: int
    cost_incurred: float

    # Timestamps
    created_at: datetime
    updated_at: datetime
    terminated_at: Optional[datetime]
```

### Enums
```python
class AgentStatus(str, Enum):
    IDLE = "idle"
    WORKING = "working"
    WAITING = "waiting"  # Waiting for human approval
    PAUSED = "paused"
    TERMINATED = "terminated"
```

### CRUD Operations
- `create(db, obj_in) -> AgentInstance`
- `get(db, id: UUID) -> Optional[AgentInstance]`
- `get_by_project(db, project_id: UUID) -> List[AgentInstance]`
- `get_active_by_project(db, project_id: UUID) -> List[AgentInstance]`
- `update_status(db, id: UUID, status: AgentStatus) -> AgentInstance`
- `update_metrics(db, id: UUID, tokens: int, cost: float) -> AgentInstance`
- `terminate(db, id: UUID) -> AgentInstance`

### Tests
- CRUD operations
- Status transitions
- Metrics accumulation
- Project relationship

## Acceptance Criteria
- [ ] Model with all fields
- [ ] Migration created
- [ ] CRUD operations
- [ ] Status transition validation
- [ ] Pydantic schemas
- [ ] Unit tests with >90% coverage

## Technical Notes
- Reference: ADR-002 (Agent orchestration)
- Reference: SPIKE-007 (Inter-agent communication)
- short_term_memory should be cleared on task completion

## Assignable To
backend-engineer agent
```

---

### Issue #11: Create Issue entity with external tracker fields

```
Title: Create Issue entity with external tracker fields
Labels: phase-1, backend, database

## Description
Implement Issue entity that syncs with external trackers (Gitea, GitHub, GitLab).

## Requirements

### Entity Fields
```python
class Issue(Base):
    id: UUID
    project_id: UUID  # FK to Project

    # Local Fields
    title: str
    body: str
    status: IssueStatus
    priority: IssuePriority
    labels: List[str]  # JSON array

    # Assignment
    assigned_agent_id: Optional[UUID]  # FK to AgentInstance
    human_assignee: Optional[str]

    # Sprint
    sprint_id: Optional[UUID]  # FK to Sprint
    story_points: Optional[int]

    # External Tracker Sync (per ADR-009)
    external_tracker: Optional[str]  # 'gitea', 'github', 'gitlab'
    external_id: Optional[str]  # Issue ID in external system
    external_url: Optional[str]  # Direct link
    external_number: Optional[int]  # Issue number
    sync_status: SyncStatus
    last_synced_at: Optional[datetime]
    external_updated_at: Optional[datetime]  # Conflict detection

    # Timestamps
    created_at: datetime
    updated_at: datetime
    closed_at: Optional[datetime]
```

### Enums
```python
class IssueStatus(str, Enum):
    OPEN = "open"
    IN_PROGRESS = "in_progress"
    IN_REVIEW = "in_review"
    BLOCKED = "blocked"
    CLOSED = "closed"

class IssuePriority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

class SyncStatus(str, Enum):
    SYNCED = "synced"
    PENDING = "pending"
    CONFLICT = "conflict"
    ERROR = "error"
```

### CRUD Operations
- Standard CRUD
- `get_by_external_id(db, tracker, external_id) -> Optional[Issue]`
- `get_pending_sync(db, project_id: UUID) -> List[Issue]`
- `get_by_sprint(db, sprint_id: UUID) -> List[Issue]`
- `get_assigned_to_agent(db, agent_id: UUID) -> List[Issue]`

### Tests
- CRUD operations
- External sync field handling
- Sprint assignment
- Agent assignment

## Acceptance Criteria
- [ ] Model with all fields
- [ ] Migration created
- [ ] CRUD operations
- [ ] Conflict detection logic
- [ ] Pydantic schemas
- [ ] Unit tests with >90% coverage

## Technical Notes
- Reference: ADR-009 (Issue synchronization)
- Reference: SPIKE-009 (Issue synchronization research)
- `external_updated_at` used for conflict detection

## Assignable To
backend-engineer agent
```

---

### Issue #12: Create Sprint entity and CRUD

```
Title: Create Sprint entity and CRUD operations
Labels: phase-1, backend, database

## Description
Implement Sprint entity for organizing work into time-boxed iterations.

## Requirements

### Entity Fields
```python
class Sprint(Base):
    id: UUID
    project_id: UUID  # FK to Project

    # Sprint Info
    name: str
    number: int  # Sequential sprint number
    goal: Optional[str]

    # Dates
    start_date: date
    end_date: date

    # Status
    status: SprintStatus

    # Velocity
    planned_points: Optional[int]
    completed_points: Optional[int]

    # Relationships
    issues: List[Issue]

    # Timestamps
    created_at: datetime
    updated_at: datetime
```

### Enums
```python
class SprintStatus(str, Enum):
    PLANNED = "planned"
    ACTIVE = "active"
    COMPLETED = "completed"
    CANCELLED = "cancelled"
```

### CRUD Operations
- Standard CRUD
- `get_active(db, project_id: UUID) -> Optional[Sprint]`
- `get_by_project(db, project_id: UUID) -> List[Sprint]`
- `start_sprint(db, id: UUID) -> Sprint`
- `complete_sprint(db, id: UUID) -> Sprint`
- `get_next_number(db, project_id: UUID) -> int`

### Tests
- CRUD operations
- Status transitions
- Sprint overlap prevention
- Velocity calculation

## Acceptance Criteria
- [ ] Model with all fields
- [ ] Migration created
- [ ] CRUD operations
- [ ] Business logic (start, complete)
- [ ] Pydantic schemas
- [ ] Unit tests with >90% coverage

## Technical Notes
- Reference: ADR-012 (Client approval flow)
- Only one sprint can be ACTIVE per project

## Assignable To
backend-engineer agent
```

---

### Issue #13: Project management API endpoints

```
Title: Create Project management API endpoints
Labels: phase-1, backend

## Description
Implement REST API endpoints for Project CRUD operations.

## Requirements

### Endpoints
```
POST   /api/v1/projects                 - Create project
GET    /api/v1/projects                 - List user's projects
GET    /api/v1/projects/{id}            - Get project details
GET    /api/v1/projects/slug/{slug}     - Get project by slug
PATCH  /api/v1/projects/{id}            - Update project
DELETE /api/v1/projects/{id}            - Archive project
POST   /api/v1/projects/{id}/pause      - Pause project
POST   /api/v1/projects/{id}/resume     - Resume project
```

### Authorization
- Users can only access their own projects
- Superusers can access all projects
- Owner check on all mutations

### Response Schema
```json
{
  "id": "uuid",
  "name": "string",
  "slug": "string",
  "description": "string",
  "autonomy_level": "string",
  "status": "string",
  "settings": {},
  "owner": {...},
  "stats": {
    "active_agents": 0,
    "open_issues": 0,
    "current_sprint": null
  },
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### Tests
- All endpoints with valid data
- Authorization (own projects only)
- Validation errors
- 404 handling
- Status transitions

## Acceptance Criteria
- [ ] All endpoints implemented
- [ ] Authorization enforced
- [ ] Proper error responses
- [ ] Rate limiting configured
- [ ] Integration tests
- [ ] OpenAPI schema updated

## Dependencies
- Depends on: #08 (Project entity)

## Assignable To
backend-engineer agent
```

---

### Issue #14: Agent type configuration API endpoints

```
Title: Create Agent type configuration API endpoints
Labels: phase-1, backend

## Description
Implement REST API endpoints for AgentType management.

## Requirements

### Endpoints
```
POST   /api/v1/agent-types              - Create agent type (admin)
GET    /api/v1/agent-types              - List all active types
GET    /api/v1/agent-types/{id}         - Get agent type details
GET    /api/v1/agent-types/slug/{slug}  - Get by slug
PATCH  /api/v1/agent-types/{id}         - Update type (admin)
DELETE /api/v1/agent-types/{id}         - Deactivate type (admin)
```

### Authorization
- Read endpoints: authenticated users
- Write endpoints: superusers only

### Response Schema
Include model configuration, MCP permissions, and instance counts.

### Tests
- All endpoints
- Admin-only enforcement
- Validation (model names, MCP servers)

## Acceptance Criteria
- [ ] All endpoints implemented
- [ ] Admin authorization enforced
- [ ] Model validation
- [ ] Integration tests
- [ ] OpenAPI schema updated

## Dependencies
- Depends on: #09 (AgentType entity)

## Assignable To
backend-engineer agent
```

---

### Issue #15: Agent instance management API endpoints

```
Title: Create Agent instance management API endpoints
Labels: phase-1, backend

## Description
Implement REST API endpoints for AgentInstance lifecycle management.

## Requirements

### Endpoints
```
POST   /api/v1/projects/{pid}/agents              - Spawn agent
GET    /api/v1/projects/{pid}/agents              - List project agents
GET    /api/v1/projects/{pid}/agents/{id}         - Get agent details
PATCH  /api/v1/projects/{pid}/agents/{id}         - Update agent
POST   /api/v1/projects/{pid}/agents/{id}/pause   - Pause agent
POST   /api/v1/projects/{pid}/agents/{id}/resume  - Resume agent
DELETE /api/v1/projects/{pid}/agents/{id}         - Terminate agent
GET    /api/v1/projects/{pid}/agents/{id}/metrics - Get agent metrics
```

### Authorization
- Project owner or superuser only
- Agents scoped to projects

### Response Schema
Include status, current task, metrics, and memory summary.

### Tests
- All endpoints
- Project ownership check
- Status transitions
- Metrics calculation

## Acceptance Criteria
- [ ] All endpoints implemented
- [ ] Project scoping enforced
- [ ] Status transitions validated
- [ ] Metrics endpoint accurate
- [ ] Integration tests
- [ ] OpenAPI schema updated

## Dependencies
- Depends on: #08 (Project), #10 (AgentInstance)

## Assignable To
backend-engineer agent
```

---

### Issue #16: Issue CRUD API endpoints

```
Title: Create Issue CRUD API endpoints
Labels: phase-1, backend

## Description
Implement REST API endpoints for Issue management.

## Requirements

### Endpoints
```
POST   /api/v1/projects/{pid}/issues              - Create issue
GET    /api/v1/projects/{pid}/issues              - List issues (filters)
GET    /api/v1/projects/{pid}/issues/{id}         - Get issue details
PATCH  /api/v1/projects/{pid}/issues/{id}         - Update issue
DELETE /api/v1/projects/{pid}/issues/{id}         - Delete issue
POST   /api/v1/projects/{pid}/issues/{id}/assign  - Assign to agent
POST   /api/v1/projects/{pid}/issues/{id}/sync    - Trigger sync
```

### Query Filters
- status, priority, labels, sprint_id, assigned_agent_id
- search (title/body)
- sync_status

### Response Schema
Include external tracker info, assignment, sprint.

### Tests
- All endpoints
- Filtering and search
- Assignment validation
- Sync trigger

## Acceptance Criteria
- [ ] All endpoints implemented
- [ ] Filtering works correctly
- [ ] Assignment validation
- [ ] Sync trigger initiates background job
- [ ] Integration tests
- [ ] OpenAPI schema updated

## Dependencies
- Depends on: #08 (Project), #11 (Issue)

## Assignable To
backend-engineer agent
```

---

### Issue #17: Sprint management API endpoints

```
Title: Create Sprint management API endpoints
Labels: phase-1, backend

## Description
Implement REST API endpoints for Sprint management.

## Requirements

### Endpoints
```
POST   /api/v1/projects/{pid}/sprints             - Create sprint
GET    /api/v1/projects/{pid}/sprints             - List sprints
GET    /api/v1/projects/{pid}/sprints/active      - Get active sprint
GET    /api/v1/projects/{pid}/sprints/{id}        - Get sprint details
PATCH  /api/v1/projects/{pid}/sprints/{id}        - Update sprint
POST   /api/v1/projects/{pid}/sprints/{id}/start  - Start sprint
POST   /api/v1/projects/{pid}/sprints/{id}/complete - Complete sprint
GET    /api/v1/projects/{pid}/sprints/{id}/issues - Get sprint issues
POST   /api/v1/projects/{pid}/sprints/{id}/issues - Add issue to sprint
```

### Business Rules
- Only one active sprint per project
- Cannot modify completed sprints
- Start date validation

### Response Schema
Include issues, velocity metrics, progress.

### Tests
- All endpoints
- Business rules enforcement
- Velocity calculation

## Acceptance Criteria
- [ ] All endpoints implemented
- [ ] Business rules enforced
- [ ] Velocity metrics accurate
- [ ] Integration tests
- [ ] OpenAPI schema updated

## Dependencies
- Depends on: #08 (Project), #11 (Issue), #12 (Sprint)

## Assignable To
backend-engineer agent
```

---

### Issue #18: Implement EventBus with Redis Pub/Sub

```
Title: Implement EventBus with Redis Pub/Sub
Labels: phase-1, backend

## Description
Create centralized event bus for real-time notifications using Redis Pub/Sub.

## Requirements

### EventBus Class
```python
class EventBus:
    async def publish(self, channel: str, event: Event) -> None
    async def subscribe(self, channels: List[str]) -> AsyncIterator[Event]
    def get_project_channel(self, project_id: UUID) -> str
    def get_agent_channel(self, agent_id: UUID) -> str
```

### Event Types
```python
class EventType(str, Enum):
    # Agent Events
    AGENT_SPAWNED = "agent.spawned"
    AGENT_STATUS_CHANGED = "agent.status_changed"
    AGENT_MESSAGE = "agent.message"
    AGENT_TERMINATED = "agent.terminated"

    # Issue Events
    ISSUE_CREATED = "issue.created"
    ISSUE_UPDATED = "issue.updated"
    ISSUE_ASSIGNED = "issue.assigned"
    ISSUE_CLOSED = "issue.closed"

    # Sprint Events
    SPRINT_STARTED = "sprint.started"
    SPRINT_COMPLETED = "sprint.completed"

    # Approval Events
    APPROVAL_REQUESTED = "approval.requested"
    APPROVAL_GRANTED = "approval.granted"
    APPROVAL_DENIED = "approval.denied"
```

### Event Schema
```python
class Event(BaseModel):
    id: str
    type: EventType
    timestamp: datetime
    project_id: UUID
    actor_id: Optional[UUID]  # Agent or user who triggered
    actor_type: str  # 'agent', 'user', 'system'
    payload: dict
```

### Tests
- Publish/subscribe cycle
- Multiple subscribers
- Channel isolation
- Event serialization

## Acceptance Criteria
- [ ] EventBus class implemented
- [ ] All event types defined
- [ ] Redis Pub/Sub working
- [ ] Project channel isolation
- [ ] Unit tests
- [ ] Integration tests with real Redis

## Technical Notes
- Reference: SPIKE-003 (Real-time communication)
- Reference: ADR-003 (Redis pub/sub)
- Use `redis.asyncio` for async support

## Assignable To
backend-engineer agent
```

---

### Issue #19: Create SSE endpoint for project events

```
Title: Create SSE endpoint for project events
Labels: phase-1, backend

## Description
Implement Server-Sent Events (SSE) endpoint for real-time project updates.

## Requirements

### Endpoint
```
GET /api/v1/projects/{pid}/events/stream
```

### Implementation
```python
@router.get("/projects/{project_id}/events/stream")
async def stream_events(
    project_id: UUID,
    current_user: User = Depends(get_current_user),
    event_bus: EventBus = Depends(get_event_bus)
):
    # Authorization check
    # Subscribe to project channel
    # Yield SSE formatted events
    # Keepalive every 30s
```

### SSE Format
```
event: agent.status_changed
data: {"id": "...", "type": "agent.status_changed", ...}

: keepalive

event: issue.created
data: {...}
```

### Features
- Automatic reconnection support (Last-Event-ID)
- Keepalive every 30 seconds
- Connection cleanup on disconnect
- Rate limiting

### Tests
- Event streaming
- Keepalive mechanism
- Authorization
- Reconnection

## Acceptance Criteria
- [ ] SSE endpoint implemented
- [ ] Events stream correctly
- [ ] Keepalive working
- [ ] Authorization enforced
- [ ] Last-Event-ID support
- [ ] Integration tests

## Dependencies
- Depends on: #18 (EventBus)

## Assignable To
backend-engineer agent
```

---

### Issue #20: Client-side SSE handling

```
Title: Implement client-side SSE handling
Labels: phase-1, frontend

## Description
Create React hooks and utilities for consuming SSE events.

## Requirements

### Hook: useProjectEvents
```typescript
function useProjectEvents(projectId: string): {
  events: ProjectEvent[];
  isConnected: boolean;
  error: Error | null;
  reconnect: () => void;
}
```

### Features
- Automatic reconnection with exponential backoff
- Event parsing and type safety
- Connection state management
- Event buffer (last 100 events)

### Event Store
```typescript
interface EventStore {
  events: ProjectEvent[];
  addEvent: (event: ProjectEvent) => void;
  clearEvents: () => void;
}
```

### Components
- ConnectionStatus indicator
- EventList component (for activity feed)

### Tests
- Hook behavior
- Reconnection logic
- Event parsing
- Store management

## Acceptance Criteria
- [ ] useProjectEvents hook implemented
- [ ] Auto-reconnection working
- [ ] Type-safe event handling
- [ ] Connection status UI
- [ ] Unit tests

## Dependencies
- Depends on: #19 (SSE endpoint)

## Assignable To
frontend-engineer agent
```

---

### Issue #21: [DESIGN] Project dashboard page

```
Title: [DESIGN] Project dashboard page
Labels: phase-1, frontend, design

## Description
Design interactive React prototype for the project dashboard page.

## Requirements

### Page Sections
1. **Header**: Project name, status badge, autonomy level, quick actions
2. **Agent Panel**: Active agents, their status, current tasks
3. **Sprint Overview**: Current sprint progress, burndown
4. **Recent Activity**: Real-time event feed
5. **Issue Summary**: Open/in-progress/blocked counts

### Interactions
- Click agent to view details
- Click sprint to view backlog
- Real-time activity updates
- Status change animations

### Responsive Design
- Desktop: Multi-column layout
- Tablet: Stacked sections
- Mobile: Single column, collapsible sections

## Deliverables
- `frontend/prototypes/project-dashboard/page.tsx`
- `frontend/prototypes/project-dashboard/README.md`
- Screenshots in issue comments

## Acceptance Criteria
- [ ] Prototype navigable in browser
- [ ] All sections represented
- [ ] Interactive elements work
- [ ] Responsive breakpoints
- [ ] Design decisions documented
- [ ] User approval obtained

## Assignable To
ui-designer agent
```

---

### Issue #22: [DESIGN] Agent configuration UI

```
Title: [DESIGN] Agent configuration UI
Labels: phase-1, frontend, design

## Description
Design interactive React prototype for agent type configuration.

## Requirements

### Views
1. **Agent Type List**: All available types with status
2. **Agent Type Detail**: Full configuration view
3. **Agent Type Editor**: Form for creating/editing

### Configuration Fields
- Name, description, expertise areas
- Model selection (primary + fallbacks)
- Model parameters (temperature, etc.)
- MCP server permissions
- Personality prompt

### Interactions
- Create new type
- Edit existing type
- Duplicate type
- Deactivate type
- Test configuration

## Deliverables
- `frontend/prototypes/agent-config/page.tsx`
- `frontend/prototypes/agent-config/README.md`
- Screenshots in issue comments

## Acceptance Criteria
- [ ] All views represented
- [ ] Form interactions work
- [ ] Model selection UI clear
- [ ] Permission editor intuitive
- [ ] User approval obtained

## Assignable To
ui-designer agent
```

---

### Issue #23: [DESIGN] Issue list and detail views

```
Title: [DESIGN] Issue list and detail views
Labels: phase-1, frontend, design

## Description
Design interactive React prototype for issue management views.

## Requirements

### Issue List View
- Filterable by status, priority, labels, sprint, assignee
- Sortable columns
- Bulk actions (assign, move to sprint, change status)
- Quick status change
- Sync status indicator

### Issue Detail View
- Full issue content (markdown)
- Status workflow buttons
- Assignment panel
- Sprint assignment
- External tracker link
- Activity timeline

### Interactions
- Filter/sort
- Inline status change
- Assign to agent
- Add to sprint

## Deliverables
- `frontend/prototypes/issues/page.tsx`
- `frontend/prototypes/issues/README.md`
- Screenshots in issue comments

## Acceptance Criteria
- [ ] List and detail views
- [ ] Filters functional
- [ ] Status workflow clear
- [ ] Sync status visible
- [ ] User approval obtained

## Assignable To
ui-designer agent
```

---

### Issue #24: [DESIGN] Real-time activity feed component

```
Title: [DESIGN] Real-time activity feed component
Labels: phase-1, frontend, design

## Description
Design interactive React prototype for the activity feed component.

## Requirements

### Event Types to Display
- Agent status changes
- Agent messages
- Issue updates
- Sprint events
- Approval requests

### Features
- Real-time updates (simulated)
- Event grouping by time
- Event type icons
- Click to expand details
- Connection status indicator

### Interactions
- Auto-scroll to new events
- Pause auto-scroll on hover
- Filter by event type
- Mark as read

## Deliverables
- `frontend/prototypes/activity-feed/page.tsx`
- `frontend/prototypes/activity-feed/README.md`
- Screenshots in issue comments

## Acceptance Criteria
- [ ] All event types represented
- [ ] Real-time feel (simulated)
- [ ] Filtering works
- [ ] Visual hierarchy clear
- [ ] User approval obtained

## Assignable To
ui-designer agent
```

---

### Issues #25-29: Implementation issues

*(These are created after design approval and follow the approved designs)*

```
Issue #25: Implement project dashboard
Labels: phase-1, frontend
Dependencies: #13, #18, #19, #20, #21 (approved)

Issue #26: Implement agent configuration UI
Labels: phase-1, frontend
Dependencies: #14, #22 (approved)

Issue #27: Implement issue views
Labels: phase-1, frontend
Dependencies: #16, #23 (approved)

Issue #28: Implement activity feed
Labels: phase-1, frontend
Dependencies: #19, #20, #24 (approved)

Issue #29: Navigation and layout
Labels: phase-1, frontend
Dependencies: None (can be done in parallel)
```

---

## Parallel Work Tracks

These issues can be worked on in parallel:

### Track 1: DevOps (Issues #01, #02, #03, #04, #05, #07)
**Agent:** devops-engineer
**Parallelizable:** #01, #02 can run parallel. #03, #04, #05 can run parallel. #07 depends on all.

### Track 2: Backend Data Model (Issues #08, #09, #10, #11, #12)
**Agent:** backend-engineer
**Parallelizable:** #08, #09 can run parallel. #10, #11, #12 can run after.

### Track 3: Backend API (Issues #13-17)
**Agent:** backend-engineer
**Parallelizable:** After data models. Can parallelize API issues once entities exist.

### Track 4: Real-time (Issues #18, #19, #20)
**Agent:** backend-engineer (18, 19), frontend-engineer (20)
**Parallelizable:** Sequential.

### Track 5: UI Design (Issues #21, #22, #23, #24)
**Agent:** ui-designer
**Parallelizable:** All can run in parallel.

### Track 6: Frontend Implementation (Issues #25-29)
**Agent:** frontend-engineer
**Parallelizable:** After design approval. Can parallelize implementations.

---

## Dependency Graph

```
Phase 0:
#01, #02 ─────────────────────┐
#03 ──────────────────────────┼──▶ #07 (Docker Compose)
#04 ──────────────────────────┤
#05 ──────────────────────────┤
#06 ──────────────────────────┘

Phase 1 - Data Model:
#08 (Project) ────────────────┬──▶ #10 (AgentInstance)
#09 (AgentType) ──────────────┤
                              └──▶ #11 (Issue) ──▶ #12 (Sprint)

Phase 1 - API:
#08 ──▶ #13 (Project API)
#09 ──▶ #14 (AgentType API)
#08, #10 ──▶ #15 (AgentInstance API)
#08, #11 ──▶ #16 (Issue API)
#08, #11, #12 ──▶ #17 (Sprint API)

Phase 1 - Real-time:
#03 ──▶ #18 (EventBus) ──▶ #19 (SSE) ──▶ #20 (Client SSE)

Phase 1 - UI:
#21, #22, #23, #24 (Design) ──[approval]──▶ #25, #26, #27, #28, #29 (Implementation)
```