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

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

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

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

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

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

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

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

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

{
  "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

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

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

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

@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

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

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)