roboco/.tasks/active/TASK-005-phase5-management/README.md

TASK-005: Phase 5 - Management

Status

• State: completed
• Priority: P0
• Cell: board

Dates

• Created: 2025-12-09
• Completed: 2025-12-09

Overview

Implement Phase 5 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.7):

• Build Task API for task CRUD and status management
• Create Kanban service with role-specific board views
• Implement metrics collection and reporting
• Build Auditor dashboard API
• Build CEO overview API

Acceptance Criteria

• Task API with full CRUD operations
• Task service with status transitions and lifecycle management
• Kanban service with board views for each role
• Dev Kanban: Backlog → Assigned → In Progress → QA Review → Documenting → Done
• QA Kanban: Awaiting Review → In Review → Passed → Failed
• Documenter Kanban: Awaiting Handoff → Gathering → Writing → Published
• PM Kanban: Incoming → Triaged → Assigned → In Progress → Blocked → Done
• Main PM Kanban: Cross-cell view with Backend/Frontend/UX columns
• Board Kanban: Ideas → Roadmap → In Development → Released
• Metrics collection (velocity, blockers, completion rate)
• Auditor dashboard API (live feeds, flagged items, metrics, reports)
• CEO overview API (health status, key metrics, auditor alerts, roadmap progress)

What Was Built

1. Task Service (src/roboco/services/task.py)

Component	Description
TaskService	Full CRUD operations for tasks
Status transitions	claim, start, block, unblock, pause, resume, verify, submit_for_qa, pass_qa, fail_qa, complete, cancel
Progress tracking	add_progress, add_checkpoint, add_commit
Queries	list_all, list_by_team, list_by_assignee, list_by_status, list_pending, list_blocked, list_awaiting_qa, list_awaiting_docs
Statistics	count_by_status, count_by_team, get_active_count

2. Task API Routes (src/roboco/api/routes/tasks.py)

Endpoint	Description
GET/POST /tasks	List and create tasks
GET/PUT/DELETE /tasks/{id}	Task CRUD
GET /tasks/my	Get agent's tasks
GET /tasks/pending, /blocked, /awaiting-qa, /awaiting-docs	Status-based lists
GET /tasks/team/{team}	Team tasks
GET /tasks/stats	Task statistics
POST /tasks/{id}/claim, /start, /block, /unblock, /pause, /resume	Lifecycle transitions
POST /tasks/{id}/verify, /submit-qa, /pass-qa, /fail-qa, /complete, /cancel	Review transitions
POST /tasks/{id}/progress, /checkpoint, /commit	Progress and artifacts

3. Kanban Models (src/roboco/models/kanban.py)

Component	Description
KanbanBoardType	Enum: DEV, QA, DOCUMENTER, PM, MAIN_PM, BOARD
KanbanCard	Card representation with task data
KanbanColumn	Column with cards and WIP limit
KanbanSwimlane	Swimlane for grouping
KanbanBoard	Complete board with columns or swimlanes
Column configs	DEV_COLUMNS, QA_COLUMNS, DOCUMENTER_COLUMNS, PM_COLUMNS, MAIN_PM_COLUMNS, BOARD_COLUMNS

4. Kanban Service (src/roboco/services/kanban.py)

Method	Description
get_dev_board(team, swimlane_by)	Dev board with optional swimlanes
get_qa_board(team)	QA review board
get_documenter_board(team)	Documenter board
get_pm_board(team)	Cell PM board
get_main_pm_board()	Cross-cell Main PM board
get_main_pm_board_flat()	Flat team-column view
get_board_kanban()	Board-level roadmap
get_board_stats(team)	Board statistics

5. Kanban API Routes (src/roboco/api/routes/kanban.py)

Endpoint	Description
GET /kanban/dev/{team}	Dev board with swimlane option
GET /kanban/qa/{team}	QA board
GET /kanban/documenter/{team}	Documenter board
GET /kanban/pm/{team}	Cell PM board
GET /kanban/main-pm	Main PM cross-cell board
GET /kanban/board	Board-level roadmap
GET /kanban/stats	Board statistics

6. Metrics Service (src/roboco/services/metrics.py)

Component	Description
VelocityMetrics	Tasks completed, created, avg time, completion rate
BlockerMetrics	Active blockers, avg time, longest blocked, by team
TeamMetrics	Active/blocked/completed tasks, avg time, doc coverage
AgentMetrics	Agent performance and activity
get_velocity(days, team)	Velocity metrics
get_blocker_metrics()	Blocker analysis
get_team_metrics(team)	Team performance
get_agent_metrics(agent_id)	Agent performance
get_communication_volume(hours)	Message and notification counts
get_health_status(team)	ok/slow/critical status

7. Dashboard API Routes (src/roboco/api/routes/dashboard.py)

Endpoint	Description
GET /dashboard/auditor	Complete auditor dashboard
GET /dashboard/auditor/flags	Auditor flags with filters
POST /dashboard/auditor/flags	Create flag
PUT /dashboard/auditor/flags/{id}/resolve	Resolve flag
GET /dashboard/auditor/reports	Auditor reports
POST /dashboard/auditor/reports	Create report
POST /dashboard/auditor/reports/{id}/send	Send to CEO
GET /dashboard/ceo	CEO overview
GET /dashboard/ceo/teams	Team details
GET /dashboard/ceo/blockers	Blocker details
GET /dashboard/ceo/velocity	Velocity metrics
GET /dashboard/metrics/*	Various metric endpoints

File Structure

src/roboco/
├── models/
│   └── kanban.py          # NEW - Kanban board models
├── services/
│   ├── task.py            # NEW - Task CRUD and lifecycle
│   ├── kanban.py          # NEW - Kanban board generation
│   └── metrics.py         # NEW - Metrics collection
├── api/routes/
│   ├── tasks.py           # NEW - Task API
│   ├── kanban.py          # NEW - Kanban API
│   └── dashboard.py       # NEW - Dashboard API
└── api/
    └── app.py             # Updated with new routes

API Summary

Task API

• Full CRUD for tasks
• Complete lifecycle management (claim → start → verify → qa → docs → complete)
• Progress tracking and checkpoints
• Commit linking

Kanban API

• 6 board types for different roles
• Swimlane support (by priority, assignee)
• Cross-cell views for Main PM
• Roadmap view for Board

Dashboard API

• Auditor: Live feeds, flags, metrics, reports
• CEO: Health status, metrics, alerts, roadmap

Usage Examples

Create and Track a Task

# Create task
POST /api/v1/tasks
{
    "title": "Implement feature X",
    "description": "...",
    "acceptance_criteria": ["..."],
    "team": "backend",
    "priority": 1
}

# Claim and start
POST /api/v1/tasks/{id}/claim
POST /api/v1/tasks/{id}/start

# Add progress
POST /api/v1/tasks/{id}/progress
{"message": "Completed first subtask", "percentage": 30}

# Submit for QA
POST /api/v1/tasks/{id}/submit-qa

View Kanban Boards

# Dev board with priority swimlanes
GET /api/v1/kanban/dev/backend?swimlane_by=priority

# Main PM cross-cell view
GET /api/v1/kanban/main-pm?flat=true

# Board-level roadmap
GET /api/v1/kanban/board

CEO Overview

# Get full overview
GET /api/v1/dashboard/ceo

# Response includes:
# - health_status: [{team, status, active_tasks, blocked_tasks, ...}]
# - key_metrics: {velocity_weekly, completion_rate, doc_coverage, blockers}
# - auditor_alerts: {urgent_count, warning_count, last_report_at}
# - roadmap_progress: {current_quarter_progress, priority_totals}

Next Steps (Phase 6: Polish)

Per HOMELAB_TEAM_V0.md section 13.8:

• Performance optimization
• Comprehensive documentation
• Test coverage
• Error handling improvements
• Logging and observability

Quick Context Restore

Phase 5 management complete. Task API provides full CRUD with lifecycle transitions. Kanban service generates role-specific boards with swimlane support. Metrics service tracks velocity, blockers, and agent performance. Auditor dashboard provides live feeds, flags, and reporting. CEO overview aggregates health status, metrics, and roadmap progress. Ready for Phase 6 polish.