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

  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

  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

  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

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

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