roboco/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

RoboCo is an AI Agentic Company - a virtual organization of 18 AI agents + 1 human CEO, designed to operate as a complete software development workforce. The system implements a structured organizational hierarchy with formal communication protocols, task management, and quality controls.

Core Architecture

CEO (Renzo - Human)
    │
    └── Board (3 agents)
         ├── Product Owner
         ├── Head of Marketing
         └── Auditor (silent observer, reports to CEO)
              │
              └── Main PM (coordinates all cells)
                   │
                   ├── Backend Cell (5 agents: 2 Devs, 1 QA, 1 PM, 1 Documenter)
                   ├── Frontend Cell (5 agents: 2 Devs, 1 QA, 1 PM, 1 Documenter)
                   └── UX/UI Cell (4 agents: 1 Dev, 1 QA, 1 PM, 1 Documenter)

Hardware Infrastructure

• Olares One (Powerhouse): Intel Ultra 9 + RTX 5090, runs Claude Code instances and AI inference
• UGREEN NAS (Warehouse): 36TB RAID6, hosts PostgreSQL, Redis, Qdrant (vector DB)
• Pi Cluster (Operations): Monitoring, notifications, smart home

Internal Services (To Be Built)

Service	Purpose
Messaging API	Agent-to-agent communication, channels, sessions, WebSocket streaming
Optimal API	RAG queries, knowledge base, prompt optimization, token management
Journal API	Agent personal logs, reflections, growth tracking
Task API	Task CRUD, status management, kanban views

Development Standards

Python (Backend)

# Package manager
uv

# Before any commit
uv run ruff format .
uv run ruff check .
uv run mypy src/
uv run pytest

# Coverage target: 80%

TypeScript (Frontend)

# Package manager
pnpm

# Before any commit
pnpm format
pnpm lint
pnpm typecheck
pnpm test

# Coverage target: 80%

Git Workflow

Branch naming:

• feature/{task-id}-{description}
• fix/{task-id}-{description}
• refactor/{task-id}-{description}
• docs/{task-id}-{description}

Commit format:

{type}({scope}): {description}

{body}

Task: {task-id}
Co-authored-by: {agent-name}

Types: feat, fix, docs, style, refactor, test, chore, perf

Task Lifecycle

Every piece of work follows this wrapper:

1. SCAN - Check for pending/ongoing tasks
2. CLAIM - Lock and take ownership
3. UNDERSTAND - Read requirements, ask questions (DO NOT PROCEED until clear)
4. PLAN - Break down, identify dependencies
5. EXECUTE - Do the work, commit frequently
6. VERIFY - Self-check against acceptance criteria
7. NOTES - Document journey, create handoff
8. CLOSE - Cleanup, return to SCAN

Task states: pending → claimed → in_progress → blocked/paused → verifying → awaiting_qa → awaiting_documentation → completed

Task Directory Structure

.tasks/
├── index.md              # Master task index
├── templates/            # Task templates by type
├── active/               # In-progress tasks
│   └── TASK-XXX-name/
│       ├── README.md     # Status, criteria, quick context
│       ├── plan.md       # Implementation plan
│       ├── journal.md    # Agent journey notes
│       ├── decisions.md  # Decision rationale
│       ├── blockers.md   # Current impediments
│       └── handoff.md    # For Documenter
├── completed/            # Archived by month
└── blocked/              # Waiting on blockers

Communication Model

Communication = constant stream (always flowing, logged, observed) Notifications = formal signals (require acknowledgment, sent by PMs/Board only)

Channel Structure

• Cell channels: #backend-cell, #frontend-cell, #uxui-cell
• Cross-cell: #dev-all, #qa-all, #pm-all, #doc-all
• Management: #main-pm-board, #board-private
• Special: #announcements (read-only except Board/Main PM), #all-hands

The Auditor has silent read access to ALL channels.

Key Principles

1. Everything is a task - All work is tracked and documented
2. No work without a task - Create task record first
3. No task without acceptance criteria - How do we know it's done?
4. No closure without documentation - Future agents need context
5. Communication is constant - Stream reasoning, log everything
6. State is sacred - If interrupted, state must be recoverable
7. The Auditor sees all - Quality monitored silently

Context Restoration Protocol

When resuming a task:

1. Read task record: README.md → plan.md → journal.md → decisions.md → blockers.md
2. Review artifacts and related commits
3. Query knowledge base for similar past tasks
4. Add to journal: "Resuming task. Context restored from records."

Technology Stack

Layer	Technology
API Framework	FastAPI
Database	PostgreSQL
Cache/Queue	Redis
Vector DB	Qdrant
Container Runtime	Docker + Docker Compose
Cloud LLM	Claude API
Local LLM	Ollama / vLLM
Embeddings	text-embedding-3-small / local
Frontend	React / Next.js (future)

Implementation Phases

The project follows a phased approach:

• Phase 0: Foundation (hardware, Docker, networking)
• Phase 1: Core Services (Messaging API, Task API, agent framework)
• Phase 2: Communication (WebSocket, transcription, notifications)
• Phase 3: Intelligence (RAG, Journal API, knowledge indexing)
• Phase 4: Agents (all 17 agent types, cell deployment)
• Phase 5: Management (Kanban UIs, dashboards)
• Phase 6: Polish (performance, documentation)

Blueprint Reference

The complete system design is documented in HOMELAB_TEAM_V0.md, which contains:

• Organizational structure and role descriptions
• Communication matrix and notification permissions
• Data models (Task, Agent, Session, Message, Channel, Notification, Journal)
• API endpoint specifications
• Kanban board designs
• Security and access control model
• Configuration templates