roboco/.tasks/active/TASK-004-phase4-agents

TASK-004: Phase 4 - Agents

Status

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

Dates

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

Overview

Implement Phase 4 of the RoboCo system per HOMELAB_TEAM_V0.md blueprint (Section 13.6):

• Define all 17 agent types with role-specific workflows
• Implement the task lifecycle for each role
• Create cell deployment infrastructure
• Enable 3 functioning cells + Board

Acceptance Criteria

• Developer workflow implemented (SCAN → CLAIM → UNDERSTAND → PLAN → EXECUTE → VERIFY → NOTES → CLOSE)
• QA workflow implemented (MONITOR → RECEIVE → UNDERSTAND → TEST → VERDICT → DOCUMENT → RETURN)
• Documenter workflow implemented (MONITOR → RECEIVE → GATHER → SYNTHESIZE → WRITE → REVIEW → PUBLISH)
• Cell PM workflow implemented (MONITOR → TRIAGE → ASSIGN → FACILITATE → ESCALATE → TRACK → REPORT)
• Main PM workflow implemented (OVERSEE → RECEIVE → PRIORITIZE → COORDINATE → DISTRIBUTE → REPORT UP → FACILITATE)
• Board workflows implemented (Product Owner, Head of Marketing, Auditor)
• Cell factory and deployment system
• Organization factory for complete deployment

What Was Built

1. Developer Agent (roboco/agents/developer.py)

Component	Description
DevTaskPhase	Enum: SCAN, CLAIM, UNDERSTAND, PLAN, EXECUTE, VERIFY, NOTES, CLOSE, BLOCKED
TaskContext	Dataclass tracking current task state, subtasks, commits, journal
DeveloperAgent	Full lifecycle implementation with LLM integration

Key features:

• Phase-based task execution
• Subtask breakdown and tracking
• Quality checks (ruff, mypy, pytest)
• Journal entries at each phase
• Handoff creation for documenter
• Factory functions for BE/FE/UX developers

2. QA Agent (roboco/agents/qa.py)

Component	Description
QATaskPhase	Enum: MONITOR, RECEIVE, UNDERSTAND, TEST, VERDICT, DOCUMENT, RETURN
TestCase	Dataclass for test execution and results
ReviewContext	Dataclass tracking review state
QAAgent	Full review lifecycle implementation

Key features:

• Test case generation from requirements
• Automated test execution
• Clear PASS/FAIL verdicts
• Specific feedback for failures
• QA report generation

3. Documenter Agent (roboco/agents/documenter.py)

Component	Description
DocTaskPhase	Enum: MONITOR, RECEIVE, GATHER, SYNTHESIZE, WRITE, REVIEW, PUBLISH
DocType	Enum: API, README, ARCHITECTURE, CHANGELOG, etc.
DocumentSpec	Dataclass for document specifications
DocumenterAgent	Full documentation lifecycle

Key features:

• Material gathering (notes, commits, conversations)
• Synthesis of what was built
• Automatic document type detection
• Self-review before publish
• Factory functions for all cells

4. PM Agents (roboco/agents/pm.py)

Component	Description
CellPMPhase	Enum: MONITOR, TRIAGE, ASSIGN, FACILITATE, ESCALATE, TRACK, REPORT
MainPMPhase	Enum: OVERSEE, RECEIVE, PRIORITIZE, COORDINATE, DISTRIBUTE, REPORT_UP, FACILITATE
CellPMAgent	Cell-level management
MainPMAgent	Organization-level coordination

Key features:

• Continuous duty cycles (never complete)
• Task prioritization and assignment
• Blocker facilitation
• Escalation handling
• Status reporting
• Cross-cell coordination (Main PM)

5. Board Agents (roboco/agents/board.py)

Component	Description
ProductOwnerAgent	Vision, roadmap, requirements, acceptance
HeadMarketingAgent	Research, strategy, campaigns, analytics
AuditorAgent	Silent observation, analysis, CEO reporting

Auditor special powers:

• Read ALL channels silently
• Query all task history
• Access all commits, docs, notes
• Direct line to CEO
• Can notify anyone (sparingly)

6. Factory and Deployment (roboco/agents/factory.py)

Component	Description
Cell	Complete cell with PM, Devs, QA, Documenter
Board	Product Owner, Head of Marketing, Auditor
Organization	Complete 18-agent organization

Factory functions:

• create_backend_cell() - 5 agents
• create_frontend_cell() - 5 agents
• create_ux_cell() - 4 agents
• create_board() - 3 agents
• create_organization() - Complete deployment

Utility functions:

• get_agent_roster() - List all agents without instantiation
• print_org_chart() - Text-based org visualization

File Structure

roboco/agents/
├── __init__.py        # Updated with all exports
├── base.py            # Phase 1 - Base Agent class
├── orchestrator.py    # Phase 1 - Agent orchestration
├── developer.py       # NEW - Developer lifecycle
├── qa.py              # NEW - QA lifecycle
├── documenter.py      # NEW - Documenter lifecycle
├── pm.py              # NEW - Cell PM and Main PM
├── board.py           # NEW - Product Owner, Marketing, Auditor
└── factory.py         # NEW - Cell and Organization factories

Agent Count

Level	Count	Agents
Executive	1	CEO (Human)
Board	3	Product Owner, Head of Marketing, Auditor
Management	1	Main PM
Backend Cell	5	PM, 2 Devs, QA, Documenter
Frontend Cell	5	PM, 2 Devs, QA, Documenter
UX/UI Cell	4	PM, 1 Dev, QA, Documenter
Total	19	18 AI + 1 Human CEO

Workflow Summary

Developer Lifecycle

SCAN → CLAIM → UNDERSTAND → PLAN → EXECUTE → VERIFY → NOTES → CLOSE
  │                           │        │
  └─────── BLOCKED ───────────┴────────┘

QA Lifecycle

MONITOR → RECEIVE → UNDERSTAND → TEST → VERDICT → DOCUMENT → RETURN
                                          │
                                    PASS ─┴─ FAIL

Documenter Lifecycle

MONITOR → RECEIVE → GATHER → SYNTHESIZE → WRITE → REVIEW → PUBLISH

Cell PM Lifecycle (Continuous)

MONITOR → TRIAGE → ASSIGN → FACILITATE → ESCALATE → TRACK → REPORT
    ▲                                                          │
    └──────────────────────────────────────────────────────────┘

Usage Example

from roboco.agents import create_organization

# Create complete organization
org = create_organization()

# Start all agents
await org.start_all()

# Access specific agents
be_dev = org.get_agent_by_slug("be-dev-1")
auditor = org.board.auditor

# Get cell status
backend_agents = org.get_agents_by_team(Team.BACKEND)

# Stop all agents
await org.stop_all()

Next Steps (Phase 5: Management)

Per HOMELAB_TEAM_V0.md section 13.7:

• Build Kanban interfaces
• Create Auditor dashboard
• Create CEO overview
• Implement metrics collection
• Build reporting system

Quick Context Restore

Phase 4 agents complete. All 17 agent types implemented with role-specific workflows. Each agent follows its lifecycle from the blueprint (Section 7). Factory functions create complete cells and the full organization. Agents load system prompts from blueprint files in agents/blueprints/. Ready for Phase 5 which adds management UIs and dashboards.