hive/planning/BZZZ_INTEGRATION_TODOS.md

# 🐝 WHOOSH-Bzzz Integration TODOs

**Updated**: January 13, 2025  
**Context**: Dynamic Project-Based Task Discovery for Bzzz P2P Coordination

---

## 🎯 **CRITICAL PRIORITY: RL Context Curator Integration**

### **0. Context Feedback and Learning System**
**Priority: Critical - Integration with HCFS RL Context Curator**
- [ ] **Task Outcome Tracking**
  - [ ] Extend `backend/app/models/task.py` with completion metrics
  - [ ] Add fields: completion_time, errors_encountered, follow_up_questions, success_rate
  - [ ] Implement task outcome classification (completed, failed, abandoned)
  - [ ] Add confidence scoring for task completions

- [ ] **Agent Role Management System**
  - [ ] Modify `backend/app/services/agent_manager.py` for role-based capabilities
  - [ ] Implement role definitions: backend, frontend, devops, qa, testing
  - [ ] Add directory scope patterns for each agent role
  - [ ] Create agent permission management with role inheritance
  - [ ] Support dynamic role assignment based on task requirements

- [ ] **Context Feedback Collection API**
  - [ ] Create `backend/app/api/feedback.py` with context feedback endpoints
  - [ ] Implement POST /api/feedback/context/{context_id} (upvote, downvote, forgetfulness)
  - [ ] Add POST /api/feedback/task-outcome/{task_id} for task completion feedback
  - [ ] Create feedback confidence and usage context tracking
  - [ ] Add feedback aggregation and analytics endpoints

- [ ] **Real-time Task Event System**
  - [ ] Extend `backend/app/services/websocket_manager.py` for task events
  - [ ] Add WebSocket events for task completion/failure triggers
  - [ ] Implement real-time feedback collection notifications
  - [ ] Create task-to-context relevance tracking events
  - [ ] Add agent role change notifications

- [ ] **Database Schema Extensions for Context Learning**
  - [ ] Create migration for context_feedback table
  - [ ] Create migration for agent_permissions table  
  - [ ] Add context relevance tracking to tasks table
  - [ ] Extend agent model with role and directory scope fields
  - [ ] Implement feedback aggregation views for RL training

- [ ] **Integration with Bzzz Context Events**
  - [ ] Add endpoints to receive context feedback from Bzzz P2P network
  - [ ] Implement feedback event routing to HCFS RL Context Curator
  - [ ] Create feedback event validation and deduplication
  - [ ] Add task-context relevance correlation tracking

## 🎯 **HIGH PRIORITY: Project Registration & Activation System**

### **1. Database-Driven Project Management**
- [ ] **Migrate from filesystem-only to hybrid approach**
  - [ ] Update `ProjectService` to use PostgreSQL instead of filesystem scanning
  - [ ] Implement proper CRUD operations for projects table
  - [ ] Add database migration for enhanced project schema
  - [ ] Create repository management fields in projects table

### **2. Enhanced Project Schema**
- [ ] **Extend projects table with Git repository fields**
  ```sql
  ALTER TABLE projects ADD COLUMN git_url VARCHAR(500);
  ALTER TABLE projects ADD COLUMN git_owner VARCHAR(255);
  ALTER TABLE projects ADD COLUMN git_repository VARCHAR(255);
  ALTER TABLE projects ADD COLUMN git_branch VARCHAR(255) DEFAULT 'main';
  ALTER TABLE projects ADD COLUMN bzzz_enabled BOOLEAN DEFAULT false;
  ALTER TABLE projects ADD COLUMN ready_to_claim BOOLEAN DEFAULT false;
  ALTER TABLE projects ADD COLUMN private_repo BOOLEAN DEFAULT false;
  ALTER TABLE projects ADD COLUMN github_token_required BOOLEAN DEFAULT false;
  ```

### **3. Project Registration API**
- [ ] **Create comprehensive project registration endpoints**
  ```python
  POST /api/projects/register - Register new Git repository as project
  PUT /api/projects/{id}/activate - Mark project as ready for Bzzz consumption  
  PUT /api/projects/{id}/deactivate - Remove project from Bzzz scanning
  GET /api/projects/active - Get all projects marked for Bzzz consumption
  PUT /api/projects/{id}/git-config - Update Git repository configuration
  ```

### **4. Bzzz Integration Endpoints**
- [ ] **Create dedicated endpoints for Bzzz agents**
  ```python
  GET /api/bzzz/active-repos - Get list of active repository configurations
  GET /api/bzzz/projects/{id}/tasks - Get bzzz-task labeled issues for project
  POST /api/bzzz/projects/{id}/claim - Register task claim with WHOOSH system
  PUT /api/bzzz/projects/{id}/status - Update task status in WHOOSH
  ```

### **5. Frontend Project Management**
- [ ] **Enhance ProjectForm component**
  - [ ] Add Git repository URL field
  - [ ] Add "Enable for Bzzz" toggle
  - [ ] Add "Ready to Claim" activation control
  - [ ] Add private repository authentication settings

- [ ] **Update ProjectList component**
  - [ ] Add Bzzz status indicators (active/inactive/ready-to-claim)
  - [ ] Add bulk activation/deactivation controls
  - [ ] Add filter for Bzzz-enabled projects

- [ ] **Enhance ProjectDetail component**
  - [ ] Add "Bzzz Integration" tab
  - [ ] Display active bzzz-task issues from GitHub
  - [ ] Show task claim history and agent assignments
  - [ ] Add manual project activation controls

---

## 🔧 **MEDIUM PRIORITY: Enhanced GitHub Integration**

### **6. GitHub API Service Enhancement**
- [ ] **Extend GitHubService class**
  - [ ] Add method to fetch issues with bzzz-task label
  - [ ] Implement issue status synchronization
  - [ ] Add webhook support for real-time issue updates
  - [ ] Create GitHub token management for private repos

### **7. Task Synchronization System**
- [ ] **Bidirectional GitHub-WHOOSH sync**
  - [ ] Sync bzzz-task issues to WHOOSH tasks table
  - [ ] Update WHOOSH when GitHub issues change
  - [ ] Propagate task claims back to GitHub assignees
  - [ ] Handle issue closure and completion status

### **8. Authentication & Security**
- [ ] **GitHub token management**
  - [ ] Store encrypted GitHub tokens per project
  - [ ] Support organization-level access tokens
  - [ ] Implement token rotation and validation
  - [ ] Add API key authentication for Bzzz agents

---

## 🚀 **LOW PRIORITY: Advanced Features**

### **9. Project Analytics & Monitoring**
- [ ] **Bzzz coordination metrics**
  - [ ] Track task claim rates per project
  - [ ] Monitor agent coordination efficiency
  - [ ] Measure task completion times
  - [ ] Generate project activity reports

### **10. Workflow Integration**
- [ ] **N8N workflow triggers**
  - [ ] Trigger workflows when projects are activated
  - [ ] Notify administrators of project registration
  - [ ] Automate project setup and validation
  - [ ] Create project health monitoring workflows

### **11. Advanced UI Features**
- [ ] **Real-time project monitoring**
  - [ ] Live task claim notifications
  - [ ] Real-time agent coordination display
  - [ ] Project activity timeline view
  - [ ] Collaborative task assignment interface

---

## 📋 **API ENDPOINT SPECIFICATIONS**

### **GET /api/bzzz/active-repos**
```json
{
  "repositories": [
    {
      "project_id": 1,
      "name": "whoosh",
      "git_url": "https://github.com/anthonyrawlins/whoosh",
      "owner": "anthonyrawlins",
      "repository": "whoosh",
      "branch": "main",
      "bzzz_enabled": true,
      "ready_to_claim": true,
      "private_repo": false,
      "github_token_required": false
    }
  ]
}
```

### **POST /api/projects/register**
```json
{
  "name": "project-name",
  "description": "Project description",
  "git_url": "https://github.com/owner/repo",
  "private_repo": false,
  "bzzz_enabled": true,
  "auto_activate": false
}
```

---

## ✅ **SUCCESS CRITERIA**

### **Phase 1 Complete When:**
- [ ] Projects can be registered via UI with Git repository info
- [ ] Projects can be activated/deactivated for Bzzz consumption
- [ ] Bzzz agents can query active repositories via API
- [ ] Database properly stores all project configuration

### **Phase 2 Complete When:**
- [ ] GitHub issues sync with WHOOSH task system
- [ ] Task claims propagate between systems
- [ ] Real-time updates work bidirectionally
- [ ] Private repository authentication functional

### **Full Integration Complete When:**
- [ ] Multiple projects can be managed simultaneously
- [ ] Bzzz agents coordinate across multiple repositories
- [ ] UI provides comprehensive project monitoring
- [ ] Analytics track cross-project coordination efficiency

---

**Next Immediate Action**: Implement database CRUD operations in ProjectService and create /api/bzzz/active-repos endpoint.