diff --git a/CLAUDE.md b/CLAUDE.md index 5c9e78aa..24ba8091 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,34 +10,25 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ``` 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) + | + +-- 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) +- **UGREEN NAS (Warehouse)**: 36TB RAID6, hosts PostgreSQL, Redis - **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) @@ -48,7 +39,7 @@ uv # Before any commit uv run ruff format . uv run ruff check . -uv run mypy src/ +uv run mypy roboco/ uv run pytest # Coverage target: 80% @@ -68,57 +59,188 @@ pnpm test # Coverage target: 80% ``` -### Git Workflow +## Technology Stack -**Branch naming:** -- `feature/{task-id}-{description}` -- `fix/{task-id}-{description}` -- `refactor/{task-id}-{description}` -- `docs/{task-id}-{description}` +| Layer | Technology | +|-------|------------| +| API Framework | FastAPI | +| Database | PostgreSQL + asyncpg | +| Vector Store | PostgreSQL + pgvector (via piragi) | +| RAG Engine | piragi (HyDE, hybrid search, BM25) | +| Cache/Queue | Redis | +| Container Runtime | Docker + Docker Compose | +| Cloud LLM | Claude API (claude-opus-4-5-20251101) | +| Local LLM | Ollama (qwen3:8b for HyDE/RAG) | +| Embeddings | BAAI/bge-base-en-v1.5 (768 dim) | +| Frontend | React / Next.js (future) | + +## Multi-Agent Workspace Structure + +Each agent gets their own git clone of a project, enabling parallel development without conflicts: -**Commit format:** ``` -{type}({scope}): {description} - -{body} - -Task: {task-id} -Co-authored-by: {agent-name} +{ROBOCO_WORKSPACES_ROOT}/ # Default: /data/workspaces ++-- {project-slug}/ + +-- {team}/ + +-- {agent-slug}/ + +-- [git repository] ``` -Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf` +**Example:** +``` +/data/workspaces/ ++-- roboco/ +| +-- backend/ +| | +-- be-dev-1/ # be-dev-1's workspace +| | +-- be-dev-2/ # be-dev-2's workspace +| +-- frontend/ +| +-- fe-dev-1/ +| +-- fe-dev-2/ ++-- roboco-panel/ + +-- frontend/ + +-- fe-dev-1/ +``` + +**Key Configuration (roboco/config.py):** +- `ROBOCO_WORKSPACES_ROOT`: Root directory for workspaces (default: `/data/workspaces`) +- `ROBOCO_WORKSPACE_AUTO_CLONE`: Auto-clone repos on first access (default: `true`) +- `ROBOCO_WORKSPACE_CLONE_TIMEOUT`: Clone timeout in seconds (default: `300`) + +## Git Workflow + +### Branch Naming Convention + +Branch names follow the pattern: `{type}/{team}/{task-id[:8]}` + +**Types:** `feature`, `bug`, `chore`, `docs`, `hotfix` + +**Examples:** +- `feature/backend/ABC12345` +- `bug/frontend/DEF67890` +- `hotfix/backend/GHI11111` + +### Commit Format + +Commits are automatically prefixed with the task ID: + +``` +[{task-id[:8]}] {message} +``` + +**Example:** +``` +[ABC12345] Add user authentication endpoint +``` + +### Work Sessions + +When a developer claims a git-enabled task, a **WorkSession** is created that tracks: +- Branch name and base/target branches +- All commits made during the session +- Files modified +- PR number/URL when created +- Merge status and who merged ## Task Lifecycle -Every piece of work follows this wrapper: +### Task States -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 +The complete task lifecycle is defined in `roboco/enforcement/task_lifecycle.py`: ``` -.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 +backlog -> pending -> claimed -> in_progress -> [blocked|paused] -> verifying + | | + v v + awaiting_qa <------------------+ awaiting_documentation + | (needs_revision) | | + v | v + awaiting_documentation --------+ awaiting_pm_review + | | + v v + awaiting_pm_review awaiting_ceo_approval + | | + v v + completed completed +``` + +**States:** +| State | Description | +|-------|-------------| +| `backlog` | PM setup phase - dependencies or session setup needed | +| `pending` | Ready for work - orchestrator can spawn agents | +| `claimed` | Agent has locked the task | +| `in_progress` | Active development | +| `blocked` | External dependency blocking progress | +| `paused` | Temporarily stopped (can resume) | +| `verifying` | Self-verification by developer | +| `needs_revision` | QA or CEO requested changes | +| `awaiting_qa` | Submitted for QA review | +| `awaiting_documentation` | Parallel phase: Documenter + Developer PR creation | +| `awaiting_pm_review` | Docs complete + PR created, PM reviews | +| `awaiting_ceo_approval` | Major tasks escalated for CEO final approval | +| `completed` | Terminal state - work done and merged | +| `cancelled` | Terminal state - work cancelled | +| `quarantined` | Special state for problematic tasks (can return to pending) | + +### Role-Based Transitions + +Certain transitions require specific roles: +- **Cancel any task**: PM roles only (`cell_pm`, `main_pm`, `product_owner`, `head_marketing`) +- **QA actions**: Only `qa` role can pass/fail QA +- **Documentation actions**: Only `documenter` role +- **CEO approval**: Only `ceo` role can approve/reject from `awaiting_ceo_approval` +- **PM review completion**: PM roles only + +### Git Integration Requirements + +For tasks with `requires_git=True`: +1. **claimed -> in_progress**: Must have `branch_name` set (PM creates branch first) +2. **awaiting_documentation -> awaiting_pm_review**: Requires BOTH `docs_complete=True` AND `pr_created=True` +3. **awaiting_pm_review -> awaiting_ceo_approval**: Must have `pr_number` set + +### CEO Approval Workflow + +Major tasks are escalated to CEO for final approval: +1. PM reviews and approves, escalates to `awaiting_ceo_approval` +2. CEO can: + - **Approve**: Merges PR, task -> `completed` + - **Request changes**: Task -> `needs_revision` + - **Cancel**: Task -> `cancelled` + +## Data Models + +### Core Models (roboco/models/) + +| Model | Purpose | +|-------|---------| +| `Task` | Atomic unit of work with acceptance criteria | +| `Project` | Git repository configuration and CI/CD commands | +| `WorkSession` | Links agent work to task, tracks branch/commits/PR | +| `Agent` | AI agent with role, team, capabilities | +| `Session` | Communication session with messages | +| `Channel` | Team communication channel | +| `Message` | Extracted message from agent streams | +| `Notification` | Formal notification requiring acknowledgment | +| `Journal` | Agent personal log for reflections/learnings | + +### Task Model Key Fields + +```python +# Git configuration +task_type: TaskType # code, documentation, research, planning, design, administrative +requires_git: bool # Whether git workflow applies +project_id: UUID # Project this task works on +branch_name: str # Branch created for this task (set by PM) +work_session_id: UUID # Active work session + +# PR tracking (parallel execution in awaiting_documentation) +pr_number: int # GitHub/GitLab PR number +pr_url: str # Full URL to PR +docs_complete: bool # Documenter has finished +pr_created: bool # Developer has created PR + +# Commits linked to task +commits: list[CommitRef] # All commits made for this task ``` ## Communication Model @@ -143,49 +265,78 @@ The Auditor has silent read access to ALL channels. 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 +8. **Commits linked to tasks** - Every commit references its task ID +9. **CEO approves major changes** - Escalation path for important work -## Context Restoration Protocol +## MCP Servers -When resuming a task: +RoboCo provides MCP (Model Context Protocol) servers for agents: -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." +| Server | Purpose | +|--------|---------| +| `task_server` | Task CRUD, lifecycle transitions, claiming | +| `git_server` | Git operations (commit, push, branch, PR) | +| `message_server` | Channel messaging, sessions | +| `journal_server` | Agent personal logs | +| `notify_server` | Formal notifications | +| `optimal_server` | RAG queries, knowledge base | +| `a2a_server` | Agent-to-agent protocol | -## Technology Stack +## Services -| 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) | +Core services in `roboco/services/`: -## Implementation Phases +| Service | Purpose | +|---------|---------| +| `TaskService` | Task CRUD and state transitions | +| `WorkSessionService` | Git session management, PR lifecycle | +| `WorkspaceService` | Multi-agent workspace resolution and cloning | +| `ProjectService` | Project/repository management | +| `MessagingService` | Channels, sessions, messages | +| `NotificationService` | Formal notifications | +| `JournalService` | Agent journals and entries | +| `OptimalService` | RAG queries using piragi | +| `PermissionsService` | Role-based access control | -The project follows a phased approach: +## Configuration -- **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) +Key settings in `roboco/config.py` (env prefix: `ROBOCO_`): + +```bash +# Database +ROBOCO_DATABASE_HOST=localhost +ROBOCO_DATABASE_PORT=5432 +ROBOCO_DATABASE_USER=roboco +ROBOCO_DATABASE_PASSWORD=roboco +ROBOCO_DATABASE_NAME=roboco + +# Redis +ROBOCO_REDIS_HOST=localhost +ROBOCO_REDIS_PORT=6379 + +# Workspaces +ROBOCO_WORKSPACES_ROOT=/data/workspaces +ROBOCO_WORKSPACE_AUTO_CLONE=true +ROBOCO_WORKSPACE_CLONE_TIMEOUT=300 + +# RAG (piragi + pgvector) +ROBOCO_RAG_CHUNK_STRATEGY=fixed +ROBOCO_RAG_CHUNK_SIZE=512 +ROBOCO_RAG_USE_HYDE=true +ROBOCO_RAG_USE_HYBRID_SEARCH=true + +# AI/LLM +ROBOCO_DEFAULT_LLM_MODEL=claude-opus-4-5-20251101 +ROBOCO_DEFAULT_EMBEDDING_MODEL=BAAI/bge-base-en-v1.5 +ROBOCO_LOCAL_LLM_MODEL=qwen3:8b +ROBOCO_LOCAL_LLM_BASE_URL=http://192.168.50.111:11434/v1 +``` ## 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 diff --git a/README.md b/README.md index e9769962..1b01ec79 100644 --- a/README.md +++ b/README.md @@ -25,19 +25,31 @@ CEO (Renzo - Human) ``` roboco/ -├── roboco/ # Main Python package -│ ├── models/ # Pydantic data models -│ ├── db/ # SQLAlchemy ORM & database -│ ├── api/ # FastAPI routes (coming soon) -│ └── config.py # Application configuration -├── agents/blueprints/ # Agent system prompts (16 agents) -├── .tasks/ # Task management system -│ ├── templates/ # Task templates by type -│ ├── active/ # In-progress tasks -│ ├── completed/ # Archived tasks -│ └── initiatives/ # Multi-task initiatives -├── CLAUDE.md # Claude Code guidance -└── HOMELAB_TEAM_V0.md # System blueprint +├── roboco/ # Main Python package +│ ├── api/ # FastAPI routes & schemas +│ │ ├── routes/ # API endpoints (tasks, git, agents, etc.) +│ │ └── schemas/ # Pydantic request/response models +│ ├── services/ # Business logic services +│ │ ├── task.py # Task lifecycle management +│ │ ├── workspace.py # Multi-agent workspace management +│ │ ├── messaging.py # Agent communication +│ │ └── optimal_brain/ # RAG/Knowledge base (piragi) +│ ├── models/ # Pydantic domain models +│ ├── db/ # SQLAlchemy ORM & migrations +│ ├── enforcement/ # Task lifecycle state machine +│ ├── runtime/ # Orchestrator for agent spawning +│ ├── agents/ # Agent base classes +│ ├── mcp/ # MCP server implementations +│ └── config.py # Application configuration +├── agents/ +│ ├── blueprints/ # Agent system prompts (18 agents) +│ └── prompts/identities/ # Agent identity files +├── docs/ +│ ├── architecture/ # Architecture documentation +│ └── workflows/ # Workflow documentation +├── alembic/ # Database migrations +├── CLAUDE.md # Claude Code guidance +└── docker-compose.yml # Local development stack ``` ## Quick Start @@ -53,9 +65,80 @@ docker compose up -d uv run alembic upgrade head # Start the API server -uv run uvicorn roboco.api:app --reload +uv run python -m roboco.cli + +# Or just the API without orchestrator +uv run uvicorn roboco.api:app --reload --host 0.0.0.0 --port 8000 ``` +## Configuration + +Key environment variables (see `roboco/config.py` for all options): + +```bash +# API Server +ROBOCO_HOST=0.0.0.0 +ROBOCO_PORT=8000 + +# Database +ROBOCO_DATABASE_HOST=localhost +ROBOCO_DATABASE_PORT=5432 +ROBOCO_DATABASE_NAME=roboco + +# Workspaces (Multi-Agent Git) +ROBOCO_WORKSPACES_ROOT=/data/workspaces +ROBOCO_WORKSPACE_AUTO_CLONE=true + +# RAG/LLM +ROBOCO_LOCAL_LLM_BASE_URL=http://localhost:11434/v1 +ROBOCO_LOCAL_LLM_MODEL=qwen3:8b +``` + +## Multi-Agent Workspace Structure + +Each agent gets their own git clone for parallel development: + +``` +{ROBOCO_WORKSPACES_ROOT}/ +└── {project-slug}/ + └── {team}/ + └── {agent-slug}/ + └── [git repository] + +Example: +/data/workspaces/roboco/backend/be-dev-1/ +/data/workspaces/roboco/backend/be-dev-2/ +``` + +## Task Lifecycle + +``` +backlog → pending → claimed → in_progress → verifying → awaiting_qa + ↓ ↓ ↓ ↓ +cancelled blocked needs_revision awaiting_documentation + paused ↓ + awaiting_pm_review + ↓ + awaiting_ceo_approval + ↓ + completed +``` + +## API Endpoints + +| Route Group | Description | +|-------------|-------------| +| `/api/v1/tasks` | Task CRUD, lifecycle, claiming | +| `/api/v1/agents` | Agent management | +| `/api/v1/git` | Git operations (status, commit, push, PR) | +| `/api/v1/test` | Test/lint/format/build commands | +| `/api/v1/sessions` | Communication sessions | +| `/api/v1/messages` | Agent messages | +| `/api/v1/projects` | Project (repo) management | +| `/api/v1/work-sessions` | Git work session tracking | +| `/api/v1/optimal` | RAG/Knowledge base queries | +| `/api/v1/journals` | Agent journals/reflections | + ## Development ```bash @@ -68,7 +151,10 @@ uv run pytest # Format and lint uv run ruff format . uv run ruff check . -uv run mypy src/ +uv run mypy roboco/ + +# Type checking +uv run mypy roboco/ ``` ## Core Principles @@ -79,29 +165,41 @@ uv run mypy src/ 4. **No closure without documentation** - Future agents need context 5. **Communication is constant** - Stream reasoning, log everything 6. **The Auditor sees all** - Quality monitored silently +7. **CEO approves major changes** - Human-in-the-loop for critical decisions ## Technology Stack | Layer | Technology | |-------|------------| | API Framework | FastAPI | -| Database | PostgreSQL + SQLAlchemy | +| Database | PostgreSQL + SQLAlchemy (async) | +| Vector Store | pgvector (via piragi) | | Cache/Queue | Redis | -| Vector DB | Qdrant | -| LLM | Claude API | +| RAG Library | piragi | +| Embeddings | BAAI/bge-base-en-v1.5 (sentence-transformers) | +| Local LLM | Ollama (qwen3:8b) | +| Cloud LLM | Claude API (Anthropic) | | Package Manager | uv | ## Status -**Phase 1: Core Services** (In Progress) +**Core Infrastructure** (Complete) - [x] Data models (Pydantic) -- [x] Database ORM (SQLAlchemy) -- [x] Configuration management -- [x] Agent blueprints (16 agents) -- [x] Task templates -- [ ] Messaging API -- [ ] Task API -- [ ] Agent orchestration +- [x] Database ORM (SQLAlchemy async) +- [x] Task lifecycle state machine +- [x] Multi-agent workspace management +- [x] Agent blueprints (18 agents) +- [x] Messaging API +- [x] Task API with full lifecycle +- [x] Git operations API +- [x] Test/CI operations API +- [x] RAG/Knowledge base (piragi + pgvector) +- [x] Agent orchestrator +- [x] CEO approval workflow + +**In Progress** +- [ ] Frontend panel (roboco-panel) +- [ ] Full agent autonomy testing ## License diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 00000000..207fae9a --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,52 @@ +# Architecture Documentation + +This directory contains detailed architecture documentation for the RoboCo system. + +## Documents + +| Document | Description | +|----------|-------------| +| [Task Lifecycle](./task_lifecycle.md) | Task states, transitions, and workflow enforcement | +| [Data Model](./data_model.md) | Core entities: Task, Agent, Project, Session, Message, WorkSession | +| [API Overview](./api_overview.md) | High-level API structure and endpoint categories | +| [Workspaces](./workspaces.md) | Multi-agent workspace architecture for parallel development | + +## Quick Reference + +### System Overview + +RoboCo is an AI Agentic Company - a virtual organization of 18 AI agents + 1 human CEO. The system implements: + +- **Organizational Hierarchy**: CEO, Board (3 agents), Main PM, and 3 Cell teams (Backend, Frontend, UX/UI) +- **Task Management**: Full lifecycle from backlog to completion with QA and documentation phases +- **Git Integration**: Per-agent workspaces, branch management, PR workflows +- **Knowledge Base**: RAG-powered semantic search across code, docs, decisions, and learnings +- **Communication**: Channel-based messaging with sessions and scoped contexts + +### Core Technology Stack + +| Layer | Technology | +|-------|------------| +| API Framework | FastAPI | +| Database | PostgreSQL | +| Cache/Queue | Redis | +| Vector DB | Qdrant (via pgvector) | +| Container Runtime | Docker + Docker Compose | +| Cloud LLM | Claude API | +| Local LLM | Ollama / vLLM | +| Embeddings | text-embedding-3-small / local | + +### Key Design 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. **State is sacred** - If interrupted, state must be recoverable +6. **Communication is constant** - Stream reasoning, log everything +7. **The Auditor sees all** - Quality monitored silently + +## Related Documentation + +- [CLAUDE.md](../../CLAUDE.md) - Project instructions and coding standards +- [HOMELAB_TEAM_V0.md](../../HOMELAB_TEAM_V0.md) - Complete system design blueprint diff --git a/docs/architecture/api_overview.md b/docs/architecture/api_overview.md new file mode 100644 index 00000000..ebe046ef --- /dev/null +++ b/docs/architecture/api_overview.md @@ -0,0 +1,452 @@ +# API Overview + +This document provides a high-level overview of the RoboCo API structure, organized by functional domain. + +## API Architecture + +The API is built with FastAPI and follows RESTful principles. All endpoints require agent authentication via headers: + +``` +X-Agent-ID: +X-Agent-Role: +X-Agent-Team: +``` + +## Route Modules + +| Module | Path Prefix | Description | +|--------|-------------|-------------| +| `health` | `/health` | Health checks and readiness probes | +| `agents` | `/agents` | Agent lookup and information | +| `tasks` | `/tasks` | Task CRUD and lifecycle management | +| `projects` | `/projects` | Git project/repository management | +| `work_session` | `/work-sessions` | Work session tracking | +| `git` | `/git` | Git operations for agents | +| `channels` | `/channels` | Communication channels | +| `groups` | `/groups` | Channel groups | +| `sessions` | `/sessions` | Message sessions | +| `messages` | `/messages` | Message operations | +| `notifications` | `/notifications` | Formal notifications | +| `journals` | `/journals` | Agent journals | +| `optimal` | `/optimal` | Knowledge base and RAG | +| `kanban` | `/kanban` | Kanban board views | +| `dashboard` | `/dashboard` | Dashboard data | +| `orchestrator` | `/orchestrator` | Agent orchestration | +| `stream` | `/stream` | WebSocket streaming | +| `test` | `/test` | Test execution | +| `a2a` | `/a2a` | Agent-to-Agent protocol | + +--- + +## Task API (`/tasks`) + +Full CRUD operations and lifecycle management for tasks. + +### CRUD Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/tasks` | Create a new task | +| `GET` | `/tasks` | List tasks with optional filters | +| `GET` | `/tasks/my` | Get tasks assigned to current agent | +| `GET` | `/tasks/pending` | Get pending tasks available to claim | +| `GET` | `/tasks/blocked` | Get blocked tasks | +| `GET` | `/tasks/awaiting-qa` | Get tasks awaiting QA review | +| `GET` | `/tasks/awaiting-docs` | Get tasks awaiting documentation | +| `GET` | `/tasks/awaiting-pm-review` | Get tasks awaiting PM review | +| `GET` | `/tasks/awaiting-ceo-approval` | Get CEO approval queue | +| `GET` | `/tasks/team/{team}` | Get tasks for a specific team | +| `GET` | `/tasks/stats` | Get task counts by status | +| `GET` | `/tasks/stats/by-team` | Get task counts by team | +| `GET` | `/tasks/{task_id}` | Get a specific task with full context | +| `PUT/PATCH` | `/tasks/{task_id}` | Update a task | +| `DELETE` | `/tasks/{task_id}` | Delete a task | +| `GET` | `/tasks/{task_id}/subtasks` | Get immediate subtasks | +| `GET` | `/tasks/{task_id}/descendants` | Get all descendants (recursive) | + +### Lifecycle Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/tasks/{task_id}/claim` | Claim a pending task | +| `POST` | `/tasks/{task_id}/start` | Start working on claimed task | +| `POST` | `/tasks/{task_id}/block` | Block task on dependency | +| `POST` | `/tasks/{task_id}/soft-block` | Block on external factor | +| `POST` | `/tasks/{task_id}/unblock` | Unblock a task | +| `POST` | `/tasks/{task_id}/pause` | Pause active task | +| `POST` | `/tasks/{task_id}/resume` | Resume paused task | +| `POST` | `/tasks/{task_id}/verify` | Submit for self-verification | +| `POST` | `/tasks/{task_id}/submit-qa` | Submit to QA | +| `POST` | `/tasks/{task_id}/pass-qa` | QA passes task | +| `POST` | `/tasks/{task_id}/fail-qa` | QA fails task | +| `POST` | `/tasks/{task_id}/docs-complete` | Mark docs complete (documenter) | +| `POST` | `/tasks/{task_id}/submit-pm-review` | Submit for PM review | +| `POST` | `/tasks/{task_id}/complete` | Complete task (PM) | +| `POST` | `/tasks/{task_id}/cancel` | Cancel task (PM) | +| `POST` | `/tasks/{task_id}/activate` | Activate from backlog (PM) | + +### CEO Approval Workflow + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/tasks/{task_id}/escalate-to-ceo` | Escalate to CEO (PM) | +| `POST` | `/tasks/{task_id}/ceo-approve` | CEO approves | +| `POST` | `/tasks/{task_id}/ceo-reject` | CEO rejects | + +### Escalation & Substitution + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/tasks/{task_id}/escalate` | Escalate to PM/management (all agents) | +| `POST` | `/tasks/{task_id}/substitute` | Request substitution (assigned agent) | + +### Progress & Artifacts + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/tasks/{task_id}/progress` | Add progress update | +| `POST` | `/tasks/{task_id}/checkpoint` | Add state checkpoint | +| `POST` | `/tasks/{task_id}/commit` | Link a commit | +| `GET` | `/tasks/{task_id}/sessions` | Get linked sessions | + +--- + +## Agent API (`/agents`) + +Agent lookup and information endpoints. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/agents` | List agents (filter by slug, role, team) | +| `GET` | `/agents/{agent_id}` | Get agent by ID or slug | + +--- + +## Project API (`/projects`) + +CRUD operations for managing git projects/repositories. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/projects` | List projects (filter by cell, active) | +| `POST` | `/projects` | Register a new project (PM) | +| `GET` | `/projects/{project_id}` | Get project details | +| `PUT/PATCH` | `/projects/{project_id}` | Update project | +| `DELETE` | `/projects/{project_id}` | Delete project | +| `POST` | `/projects/{project_id}/sync` | Update sync state | +| `POST` | `/projects/{project_id}/workspace` | Set workspace path | + +--- + +## Git API (`/git`) + +Git operations for agents working on code tasks. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/git/{project}/status` | Get git status | +| `GET` | `/git/{project}/diff` | Get diff | +| `GET` | `/git/{project}/log` | Get commit log | +| `GET` | `/git/{project}/branches` | List branches | +| `POST` | `/git/{project}/branch` | Create a branch | +| `POST` | `/git/{project}/checkout` | Checkout a branch | +| `POST` | `/git/{project}/commit` | Create a commit | +| `POST` | `/git/{project}/push` | Push changes | +| `POST` | `/git/{project}/pr` | Create a pull request | +| `POST` | `/git/{project}/pr/merge` | Merge a pull request | + +--- + +## Work Session API (`/work-sessions`) + +Work session tracking for git-enabled tasks. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/work-sessions` | List work sessions | +| `POST` | `/work-sessions` | Create a work session | +| `GET` | `/work-sessions/{id}` | Get work session details | +| `PATCH` | `/work-sessions/{id}` | Update work session | +| `GET` | `/work-sessions/task/{task_id}` | Get work session for task | +| `GET` | `/work-sessions/agent/{agent_id}` | Get agent's active session | + +--- + +## Messaging API + +### Channels (`/channels`) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/channels` | List channels | +| `POST` | `/channels` | Create a channel | +| `GET` | `/channels/{slug}` | Get channel by slug | +| `PUT` | `/channels/{slug}` | Update channel | +| `DELETE` | `/channels/{slug}` | Delete channel | + +### Groups (`/groups`) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/groups` | List groups | +| `POST` | `/groups` | Create a group | +| `GET` | `/groups/{id}` | Get group | +| `PUT` | `/groups/{id}` | Update group | +| `DELETE` | `/groups/{id}` | Delete group | + +### Sessions (`/sessions`) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/sessions` | List sessions | +| `POST` | `/sessions` | Create a session | +| `GET` | `/sessions/{id}` | Get session | +| `POST` | `/sessions/{id}/close` | Close session | +| `POST` | `/sessions/{id}/messages` | Add message to session | +| `GET` | `/sessions/{id}/messages` | Get session messages | +| `POST` | `/sessions/for-tasks` | Create session for tasks (PM) | +| `POST` | `/sessions/{id}/link-task` | Link task to session | + +### Messages (`/messages`) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/messages` | List messages | +| `POST` | `/messages` | Create a message | +| `GET` | `/messages/{id}` | Get message | +| `PUT` | `/messages/{id}` | Edit message | + +--- + +## Notifications API (`/notifications`) + +Formal notification management. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/notifications` | List notifications | +| `GET` | `/notifications/unread` | Get unread notifications | +| `POST` | `/notifications` | Create notification (PM/Board) | +| `GET` | `/notifications/{id}` | Get notification | +| `POST` | `/notifications/{id}/ack` | Acknowledge notification | +| `POST` | `/notifications/{id}/read` | Mark as read | + +--- + +## Journal API (`/journals`) + +Agent personal journal management. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/journals` | Get current agent's journal | +| `GET` | `/journals/{agent_id}` | Get agent's journal | +| `POST` | `/journals/entries` | Create journal entry | +| `GET` | `/journals/entries` | List entries | +| `GET` | `/journals/entries/{id}` | Get entry | + +--- + +## Optimal API (`/optimal`) + +Knowledge base, RAG queries, and semantic search. + +### Indexing + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/optimal/kb/index/code` | Index code files | +| `POST` | `/optimal/kb/index/docs` | Index documentation | +| `POST` | `/optimal/kb/refresh` | Refresh an index | +| `POST` | `/optimal/kb/reindex` | Trigger full reindex | +| `DELETE` | `/optimal/kb/{index_type}` | Clear an index | +| `GET` | `/optimal/kb/{index_type}/documents` | List indexed documents | + +### Search & RAG + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/optimal/kb/search` | Semantic search | +| `GET` | `/optimal/kb/similar` | Find similar documents | +| `POST` | `/optimal/rag/query` | RAG query with answer | +| `POST` | `/optimal/rag/context` | Get context without answer | + +### Knowledge Services + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/optimal/mentor/ask` | Ask the organizational knowledge base | +| `POST` | `/optimal/errors/search` | Search for error solutions | +| `POST` | `/optimal/errors/record` | Record error solution | +| `POST` | `/optimal/decisions/check` | Check for precedent decisions | +| `POST` | `/optimal/decisions/record` | Record a decision | +| `POST` | `/optimal/standards/get` | Get coding/security standards | +| `POST` | `/optimal/standards/validate` | Validate action against standards | +| `POST` | `/optimal/review/code` | Code review | +| `POST` | `/optimal/learnings/record` | Record a learning | +| `POST` | `/optimal/learnings/search` | Search learnings | +| `POST` | `/optimal/context/proactive` | Get proactive context for task | + +### Management + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/optimal/stats` | Get all index statistics | +| `GET` | `/optimal/stats/{index_type}` | Get single index stats | +| `GET` | `/optimal/health` | RAG system health check | +| `POST` | `/optimal/tokens/estimate` | Estimate token count | +| `POST` | `/optimal/prompts` | Create prompt template | +| `GET` | `/optimal/prompts` | List prompt templates | + +--- + +## Kanban API (`/kanban`) + +Kanban board views for task management. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/kanban/board` | Get kanban board data | +| `GET` | `/kanban/board/{team}` | Get team kanban board | +| `GET` | `/kanban/swimlanes` | Get swimlane view | + +--- + +## Dashboard API (`/dashboard`) + +Dashboard data and metrics. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/dashboard/summary` | Get dashboard summary | +| `GET` | `/dashboard/metrics` | Get system metrics | +| `GET` | `/dashboard/activity` | Get recent activity | + +--- + +## Orchestrator API (`/orchestrator`) + +Agent orchestration and management. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/orchestrator/spawn` | Spawn an agent | +| `POST` | `/orchestrator/terminate` | Terminate an agent | +| `GET` | `/orchestrator/status` | Get orchestrator status | + +--- + +## Stream API (`/stream`) + +WebSocket streaming for real-time communication. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `WS` | `/stream/connect` | WebSocket connection | +| `WS` | `/stream/channel/{slug}` | Channel stream | +| `WS` | `/stream/agent/{id}` | Agent stream | + +--- + +## Test API (`/test`) + +Test execution endpoints. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `POST` | `/test/run` | Run tests in workspace | +| `GET` | `/test/results/{id}` | Get test results | + +--- + +## A2A API (`/a2a`) + +Agent-to-Agent protocol support. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/a2a/.well-known/agent.json` | Agent discovery | +| `POST` | `/a2a/tasks/send` | Send task to agent | +| `GET` | `/a2a/tasks/{id}/status` | Get task status | + +--- + +## Health API (`/health`) + +System health and readiness. + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/health` | Basic health check | +| `GET` | `/health/ready` | Readiness probe | +| `GET` | `/health/live` | Liveness probe | + +--- + +## Permission Model + +The API enforces role-based permissions: + +### Task Actions + +| Action | Allowed Roles | +|--------|---------------| +| `CREATE` | PM, Board, CEO | +| `VIEW_ALL` | Main PM, Board, CEO, Auditor | +| `CLAIM` | Developers, QA, Documenters (own team) | +| `UPDATE_OWN` | Assigned agent or creator | +| `ASSIGN` | PM, Board, CEO | +| `CHANGE_PRIORITY` | PM, Board, CEO | +| `CLOSE` | PM, Board, CEO | + +### KB Actions + +| Action | Allowed Roles | +|--------|---------------| +| `INDEX_CODE` | PM, Board, CEO | +| `INDEX_DOCS` | PM, Board, CEO | +| `VIEW_STATS` | All authenticated agents | +| `CLEAR_INDEX` | PM, Board, CEO | +| `REFRESH_INDEX` | PM, Board, CEO | + +### Notification Permissions + +Only specific roles can send formal notifications: +- `cell_pm` +- `main_pm` +- `product_owner` +- `head_marketing` +- `auditor` + +--- + +## Error Responses + +All endpoints return standard error responses: + +```json +{ + "detail": "Error message describing what went wrong" +} +``` + +Common HTTP status codes: + +| Code | Meaning | +|------|---------| +| `400` | Bad Request - Invalid input | +| `401` | Unauthorized - Missing authentication | +| `403` | Forbidden - Insufficient permissions | +| `404` | Not Found - Resource doesn't exist | +| `500` | Internal Server Error | +| `504` | Gateway Timeout - Operation timed out | + +--- + +## Rate Limiting + +Currently, no rate limiting is implemented. This is planned for future versions. + +## Versioning + +The API does not currently implement versioning. Breaking changes will be documented in release notes. diff --git a/docs/architecture/data_model.md b/docs/architecture/data_model.md new file mode 100644 index 00000000..d673e93b --- /dev/null +++ b/docs/architecture/data_model.md @@ -0,0 +1,525 @@ +# Data Model + +This document describes the core entities in the RoboCo system, their relationships, and key fields. + +## Entity Relationship Overview + +``` + +--------+ + | CEO | + +---+----+ + | + v ++--------+ +----------+ +-------+ +---------+ +| Project| <-- |WorkSession| -- | Task | -- | Agent | ++---+----+ +----------+ +---+---+ +----+----+ + | | | + | | | + v v v ++----------+ +---------------+ +----------+ +| Workspace| | SessionTask | | Journal | +| (on disk)| | (many-to-many)| +----+-----+ ++----------+ +-------+-------+ | + | v + v +-------------+ + +----------+ |JournalEntry | + | Session | +-------------+ + +----+-----+ + | + v + +----------+ + | Message | + +----------+ + ++----------+ +-------+ +---------+ +| Channel | --> | Group | --> | Session | ++----------+ +-------+ +---------+ + ++---------------+ +| Notification | ++---------------+ + ++---------------+ +| Handoff | (Reserved for future use) ++---------------+ + ++------------------+ +| IndexedDocument | (Knowledge base tracking) ++------------------+ +``` + +## Core Entities + +### Agent + +Represents an AI agent in the organization. Each agent has a role, team affiliation, capabilities, and permissions. + +**Table**: `agents` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `name` | String(100) | Display name | +| `slug` | String(50) | URL-safe identifier (e.g., `be-dev-1`) | +| `role` | Enum | `developer`, `qa`, `documenter`, `cell_pm`, `main_pm`, `product_owner`, `head_marketing`, `auditor`, `ceo`, `system` | +| `team` | Enum | `backend`, `frontend`, `ux_ui`, `main_pm`, `board`, `marketing` (nullable for board members) | +| `status` | Enum | `active`, `idle`, `offline` | +| `current_task_id` | UUID | Currently assigned task (FK) | +| `model_config` | JSON | LLM configuration (provider, model name, temperature, etc.) | +| `system_prompt` | Text | Base system prompt for this agent | +| `capabilities` | Array[String] | List of capabilities (`code_execution`, `git_operations`, etc.) | +| `permissions` | JSON | Channel access permissions | +| `metrics` | JSON | Performance metrics (tasks completed, quality score, etc.) | +| `journal_id` | UUID | Agent's personal journal ID | +| `description` | Text | Human-readable description | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | + +**Agent Roles**: +- **Executive**: `ceo` +- **Board**: `product_owner`, `head_marketing`, `auditor` +- **Management**: `main_pm`, `cell_pm` +- **Cell Members**: `developer`, `qa`, `documenter` +- **System**: `system` (internal orchestrator) + +--- + +### Task + +The atomic unit of work in RoboCo. Every piece of work follows the universal task lifecycle. + +**Table**: `tasks` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `title` | String(200) | Task title | +| `description` | Text | Detailed description | +| `acceptance_criteria` | Array[String] | How we know it's done | +| `status` | Enum | Current lifecycle state (see [Task Lifecycle](./task_lifecycle.md)) | +| `priority` | Integer | 0=P0 (highest) to 3=P3 (lowest) | +| `task_type` | Enum | `code`, `documentation`, `research`, `planning`, `design`, `administrative` | +| `requires_git` | Boolean | Whether git workflow applies | +| `project_id` | UUID | Associated project (FK) | +| `branch_name` | String(500) | Git branch for this task | +| `work_session_id` | UUID | Active work session (FK) | +| `pr_number` | Integer | GitHub/GitLab PR number | +| `pr_url` | String(500) | Full URL to PR | +| `docs_complete` | Boolean | Documenter has finished | +| `pr_created` | Boolean | Developer has created PR | +| `pm_approvals` | JSON | PM approval tracking | +| `created_by` | UUID | Agent who created the task (FK) | +| `assigned_to` | UUID | Currently assigned agent (FK) | +| `team` | Enum | Which cell owns this task | +| `parent_task_id` | UUID | Parent task for sub-tasks (FK) | +| `dependency_ids` | Array[UUID] | Tasks this is blocked by | +| `blocker_ids` | Array[UUID] | Tasks this is blocking | +| `claimed_at` | Timestamp | When task was claimed | +| `started_at` | Timestamp | When work started | +| `completed_at` | Timestamp | When task completed | +| `target_date` | Timestamp | Target completion date | +| `plan` | JSON | Implementation plan (sub-tasks, risks, questions) | +| `estimated_complexity` | Enum | `low`, `medium`, `high` | +| `execution_log` | JSON | Execution events and errors | +| `checkpoints` | JSON | State recovery checkpoints | +| `progress_updates` | JSON | Progress update history | +| `commits` | JSON | Linked commits | +| `documents` | JSON | Linked documents | +| `outputs` | JSON | Output artifacts | +| `dev_notes` | Text | Developer journey notes | +| `qa_notes` | Text | QA feedback | +| `auditor_notes` | Text | Auditor observations | +| `self_verified` | Boolean | Self-verification passed | +| `qa_verified` | Boolean | QA verification result | +| `quick_context` | Text | 2-3 sentences for quick context restoration | +| `proactive_context` | JSON | RAG context injected when claimed | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | + +**Indexes**: +- `ix_tasks_team_status` - Team + Status queries +- `ix_tasks_assigned_status` - Assignee + Status queries +- `ix_tasks_project_status` - Project + Status queries + +--- + +### Project + +A git repository that agents work on. Projects are registered by PMs and contain configuration for the development workflow. + +**Table**: `projects` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `name` | String(100) | Project name | +| `slug` | String(50) | URL-safe identifier (e.g., `roboco`, `roboco-panel`) | +| `git_url` | String(500) | Git repository URL | +| `default_branch` | String(100) | Default branch (default: `main`) | +| `protected_branches` | Array[String] | Branches that cannot be pushed directly | +| `test_command` | String(500) | Command to run tests | +| `lint_command` | String(500) | Command to run linter | +| `format_command` | String(500) | Command to format code | +| `typecheck_command` | String(500) | Command to run type checker | +| `build_command` | String(500) | Command to build | +| `assigned_cell` | Enum | Which cell owns this project | +| `allowed_agents` | Array[UUID] | Specific agents allowed (null = all in cell) | +| `workspace_path` | String(500) | Local workspace path | +| `last_synced_at` | Timestamp | Last sync from remote | +| `head_commit` | String(40) | Current HEAD commit SHA | +| `created_by` | UUID | PM who registered the project (FK) | +| `is_active` | Boolean | Whether project is active | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | + +--- + +### WorkSession + +Tracks an agent's working session on a task, including branch management, commits, and PR tracking. + +**Table**: `work_sessions` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `project_id` | UUID | Project being worked on (FK) | +| `task_id` | UUID | Task being worked on (FK) | +| `agent_id` | UUID | Agent doing the work (FK) | +| `branch_name` | String(500) | Full branch name | +| `base_branch` | String(500) | Branch this was forked from | +| `target_branch` | String(500) | Branch to merge into | +| `started_at` | Timestamp | Session start time | +| `ended_at` | Timestamp | Session end time | +| `status` | Enum | `active`, `completed`, `abandoned` | +| `commits` | Array[String] | Commit SHAs made in this session | +| `files_modified` | Array[String] | Files touched in this session | +| `pr_number` | Integer | PR number | +| `pr_url` | String(500) | Full URL to PR | +| `pr_status` | String(50) | `open`, `merged`, `closed` | +| `pr_created_at` | Timestamp | When PR was created | +| `pr_merged_at` | Timestamp | When PR was merged | +| `merged_by` | UUID | Agent who merged the PR (FK) | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | + +--- + +### Session + +Sessions group messages within boundaries (time, count, content length). They are automatically created and closed based on configuration. + +**Table**: `sessions` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key (sesh_id) | +| `group_id` | UUID | Parent group (FK) | +| `max_time_window` | Interval | Maximum session duration (default: 30 min) | +| `max_message_count` | Integer | Maximum messages per session (default: 100) | +| `max_content_length` | Integer | Maximum total characters (default: 50000) | +| `timeout_seconds` | Integer | Inactivity timeout (default: 300) | +| `status` | Enum | `active`, `closed`, `timed_out` | +| `scope` | Enum | `initiative`, `cell`, `task` | +| `started_at` | Timestamp | Session start time | +| `last_activity_at` | Timestamp | Last activity time | +| `closed_at` | Timestamp | Session close time | +| `message_count` | Integer | Number of messages | +| `total_content_length` | Integer | Total character count | +| `created_at` | Timestamp | Creation time | + +**Session Scopes**: +- `initiative`: Cross-cell coordination (Main PM, #dev-all) +- `cell`: Cell-specific work (Cell PM, #backend-cell) +- `task`: Individual task execution (Developer level) + +--- + +### SessionTask (Junction Table) + +Many-to-many relationship between Sessions and Tasks. PMs can create work sessions as discussion contexts for tasks. + +**Table**: `session_tasks` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `session_id` | UUID | Session (FK) | +| `task_id` | UUID | Task (FK) | +| `is_primary` | Boolean | Primary discussion session for this task | +| `relationship_type` | String(50) | `discussion`, `planning`, `review`, `retrospective` | +| `added_at` | Timestamp | When link was created | +| `added_by` | UUID | PM who created the link (FK) | + +--- + +### Message + +Extracted, stored message from agent streams. Messages are the atomic unit of communication. + +**Table**: `messages` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key (msg_id) | +| `agent_id` | UUID | Agent who sent the message (FK) | +| `channel_id` | UUID | Channel the message is in (FK) | +| `group_id` | UUID | Group the message belongs to (FK) | +| `session_id` | UUID | Session ID (FK) | +| `type` | Enum | `reasoning`, `dialogue`, `decision`, `action`, `blocker`, `technical` | +| `content` | Text | Message content | +| `content_length` | Integer | Character count | +| `is_reply` | Boolean | Whether this is a reply | +| `reply_to` | UUID | Parent message ID (FK) | +| `mentions` | Array[UUID] | Agent IDs mentioned | +| `task_id` | UUID | Related task ID (FK) | +| `commit_ref` | String(40) | Related commit hash | +| `timestamp` | Timestamp | Message timestamp | +| `confidence` | Float | Extraction confidence | +| `raw_excerpt` | Text | Original text before extraction | +| `edited_at` | Timestamp | Last edit time | +| `edit_history` | JSON | Previous versions | +| `created_at` | Timestamp | Creation time | + +--- + +### Channel + +Communication channels for agent messaging. + +**Table**: `channels` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `name` | String(100) | Channel name | +| `slug` | String(50) | URL-safe identifier | +| `type` | Enum | `cell`, `cross_cell`, `management`, `special` | +| `description` | Text | Channel description | +| `topic` | String(500) | Current topic | +| `members` | Array[UUID] | Member agent IDs | +| `writers` | Array[UUID] | Agents with write access | +| `silent_observers` | Array[UUID] | Agents with silent read access (Auditor) | +| `is_archived` | Boolean | Whether channel is archived | +| `is_private` | Boolean | Private channel flag | +| `allow_threads` | Boolean | Whether threads are allowed | +| `allow_reactions` | Boolean | Whether reactions are allowed | +| `message_retention_days` | Integer | Message retention (default: 90) | +| `max_message_length` | Integer | Maximum message length (default: 10000) | +| `message_count` | Integer | Total messages | +| `group_count` | Integer | Total groups | +| `last_activity` | Timestamp | Last activity time | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | + +**Channel Types**: +- `cell`: Internal team channels (#backend-cell, #frontend-cell, #uxui-cell) +- `cross_cell`: Coordination channels (#dev-all, #qa-all, #pm-all, #doc-all) +- `management`: Management channels (#main-pm-board, #board-private) +- `special`: Special channels (#announcements, #all-hands) + +--- + +### Group + +Groups within channels, used to organize conversations. + +**Table**: `groups` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `name` | String(100) | Group name | +| `channel_id` | UUID | Parent channel (FK) | +| `allowed_roles` | Array[String] | Roles allowed in this group | +| `hierarchy_level` | Integer | Hierarchy level (default: 4) | +| `members` | Array[UUID] | Member agent IDs | +| `is_active` | Boolean | Whether group is active | +| `active_session_id` | UUID | Current active session | +| `default_session_config` | JSON | Session boundary configuration | +| `total_sessions` | Integer | Total sessions | +| `total_messages` | Integer | Total messages | +| `last_activity` | Timestamp | Last activity time | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | + +--- + +### Notification + +Formal notifications requiring acknowledgment. + +**Table**: `notifications` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `type` | Enum | `task_assignment`, `priority_change`, `blocker_escalation`, `review_request`, `documentation_request`, `alert`, `broadcast`, `knowledge_share`, `mention` | +| `priority` | Enum | `normal`, `high`, `urgent` | +| `from_agent` | UUID | Sender agent (FK) | +| `to_agents` | Array[UUID] | Recipient agent IDs | +| `subject` | String(200) | Notification subject | +| `body` | Text | Notification body | +| `requires_ack` | Boolean | Requires acknowledgment | +| `acked_by` | Array[UUID] | Agents who acknowledged | +| `acked_at` | JSON | Acknowledgment timestamps | +| `related_task_id` | UUID | Related task (FK) | +| `related_message_ids` | Array[UUID] | Related message IDs | +| `timestamp` | Timestamp | Notification timestamp | +| `expires_at` | Timestamp | Expiration time | +| `read_by` | Array[UUID] | Agents who read | +| `delivered_at` | Timestamp | Delivery time | +| `created_at` | Timestamp | Creation time | + +--- + +### Journal + +Agent personal journal for reflections and growth tracking. + +**Table**: `journals` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `agent_id` | UUID | Agent owner (FK, unique) | +| `total_entries` | Integer | Entry count | +| `last_entry_at` | Timestamp | Last entry time | +| `latest_summary` | Text | Latest summary | +| `summary_updated_at` | Timestamp | Summary update time | +| `entries_by_type` | JSON | Entry counts by type | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | + +--- + +### JournalEntry + +Individual journal entries. + +**Table**: `journal_entries` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `journal_id` | UUID | Parent journal (FK) | +| `type` | Enum | `task_reflection`, `decision_log`, `learning`, `struggle`, `general` | +| `title` | String(200) | Entry title | +| `content` | Text | Entry content | +| `task_id` | UUID | Related task (FK) | +| `session_id` | UUID | Related session (FK) | +| `timestamp` | Timestamp | Entry timestamp | +| `tags` | Array[String] | Entry tags | +| `sentiment` | String(50) | Entry sentiment | +| `is_private` | Boolean | Private entry flag | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | + +--- + +### IndexedDocument + +Tracks documents indexed into the knowledge base. + +**Table**: `indexed_documents` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `index_type` | String(50) | `code`, `docs`, `conversations`, `journals`, `errors`, `standards`, etc. | +| `source` | String(1000) | Source path/URL | +| `source_hash` | String(64) | SHA256 for deduplication | +| `title` | String(500) | Document title | +| `preview` | Text | First 500 chars for UI | +| `chunk_count` | Integer | Number of chunks | +| `extra_data` | JSON | Additional metadata | +| `indexed_at` | Timestamp | Indexing time | +| `updated_at` | Timestamp | Last update time | + +--- + +### Handoff (Reserved) + +Structured documentation handoffs. Currently unused - reserved for future implementation. + +**Table**: `handoffs` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | UUID | Primary key | +| `task_id` | UUID | Related task (FK, unique) | +| `summary` | Text | Handoff summary | +| `new_functionality` | Array[String] | New features | +| `modified_behavior` | Array[String] | Modified behaviors | +| `breaking_changes` | Array[String] | Breaking changes | +| `required_docs` | JSON | Required documentation items | +| `optional_docs` | JSON | Optional documentation items | +| `commits` | JSON | Key commits | +| `new_files` | JSON | New file locations | +| `modified_files` | JSON | Modified file locations | +| `key_conversations` | JSON | Key conversations | +| `code_samples` | JSON | Code samples | +| `gotchas` | JSON | Gotchas and warnings | +| `related_docs` | Array[String] | Related documentation | +| `changelog_entry` | Text | Changelog entry | +| `key_learnings` | Array[String] | Key learnings | +| `key_decisions` | JSON | Key decisions | +| `questions` | Array[String] | Open questions | +| `dev_notes_location` | String(500) | Dev notes file path | +| `status` | Enum | `pending`, `claimed`, `in_progress`, `accepted`, `completed` | +| `assigned_to` | UUID | Assigned documenter (FK) | +| `documenter_notes` | Text | Documenter feedback | +| `created_at` | Timestamp | Creation time | +| `updated_at` | Timestamp | Last update time | +| `claimed_at` | Timestamp | Claim time | +| `completed_at` | Timestamp | Completion time | + +## Enumerations + +### TaskStatus +`backlog`, `pending`, `claimed`, `in_progress`, `blocked`, `paused`, `verifying`, `needs_revision`, `awaiting_qa`, `awaiting_documentation`, `awaiting_pm_review`, `awaiting_ceo_approval`, `completed`, `cancelled` + +### TaskType +`code`, `documentation`, `research`, `planning`, `design`, `administrative` + +### Complexity +`low`, `medium`, `high` + +### Team +`backend`, `frontend`, `ux_ui`, `main_pm`, `board`, `marketing` + +### AgentRole +`system`, `ceo`, `product_owner`, `head_marketing`, `auditor`, `main_pm`, `cell_pm`, `developer`, `qa`, `documenter` + +### AgentStatus +`active`, `idle`, `offline` + +### SessionStatus +`active`, `closed`, `timed_out` + +### SessionScope +`initiative`, `cell`, `task` + +### MessageType +`reasoning`, `dialogue`, `decision`, `action`, `blocker`, `technical` + +### NotificationType +`task_assignment`, `priority_change`, `blocker_escalation`, `review_request`, `documentation_request`, `alert`, `broadcast`, `knowledge_share`, `mention` + +### NotificationPriority +`normal`, `high`, `urgent` + +### ChannelType +`cell`, `cross_cell`, `management`, `special` + +### JournalEntryType +`task_reflection`, `decision_log`, `learning`, `struggle`, `general` + +### WorkSessionStatus +`active`, `completed`, `abandoned` + +### HandoffStatus +`pending`, `claimed`, `in_progress`, `accepted`, `completed` + +### ModelProvider +`anthropic`, `openai`, `local` diff --git a/docs/architecture/task_lifecycle.md b/docs/architecture/task_lifecycle.md new file mode 100644 index 00000000..18c1cfe1 --- /dev/null +++ b/docs/architecture/task_lifecycle.md @@ -0,0 +1,302 @@ +# Task Lifecycle + +This document describes all task states, valid transitions, and workflow enforcement in the RoboCo system. + +## Task States + +Tasks follow a defined lifecycle from creation to completion. Each state represents a specific phase of work. + +### State Definitions + +| State | Description | +|-------|-------------| +| `backlog` | PM setup phase - task with dependencies or needs session setup | +| `pending` | Ready for work - orchestrator can spawn agents | +| `claimed` | Agent has taken ownership but not started | +| `in_progress` | Active work being performed | +| `blocked` | Waiting on another task or external dependency | +| `paused` | Temporarily suspended by the assigned agent | +| `verifying` | Self-verification by the developer | +| `needs_revision` | QA or CEO has requested changes | +| `awaiting_qa` | Ready for QA review | +| `awaiting_documentation` | Docs + Developer PR creation in parallel | +| `awaiting_pm_review` | After docs + PR ready, PM reviews | +| `awaiting_ceo_approval` | PMs approved, CEO makes final decision | +| `completed` | Task finished successfully (terminal) | +| `cancelled` | Task cancelled (terminal) | +| `quarantined` | Special state for problematic tasks | + +### State Categories + +```python +# Terminal states - cannot transition out +TERMINAL_STATES = ["completed", "cancelled"] + +# Waiting states - agent can work on other tasks +WAITING_STATES = [ + "blocked", + "paused", + "awaiting_qa", + "awaiting_documentation", + "awaiting_pm_review", + "awaiting_ceo_approval", +] + +# Active states - agent is actively working +ACTIVE_STATES = ["claimed", "in_progress", "verifying", "needs_revision"] +``` + +## State Transition Diagram + +``` + +-----------+ + | quarantined| + +-----+-----+ + | + v ++--------+ +----------+ +---------+ +-------------+ +| backlog| --> | pending | --> | claimed | --> | in_progress | ++---+----+ +----+-----+ +----+----+ +------+------+ + | | | | + v v v | ++---------+ +---------+ +-----------+ | +|cancelled| |cancelled| | pending | | ++---------+ +---------+ |(unclaim) | | + +-----------+ | + | + +-----------------------------------+ + | | | | + v v v v + +----------+ +----------+ +---------+ + | blocked | | paused | |verifying| + +----+-----+ +----+-----+ +----+----+ + | | | + v v | + in_progress in_progress | + | + +-----------------------------+ + | | | + v v v + +-------------+ +---------------+ +---------------------+ + | awaiting_qa | |needs_revision | |awaiting_documentation| + +------+------+ +-------+-------+ +----------+----------+ + | | | + | v | + | claimed/in_progress | + | | + +-----------------+---------------------+ + | + v + +------------------+ + |awaiting_pm_review| + +--------+---------+ + | + +-------------------------+-------------------------+ + | | | + v v v + +-----------+ +--------------------+ +-----------+ + | completed | |awaiting_ceo_approval| | cancelled | + +-----------+ +---------+----------+ +-----------+ + | + +-------------------------+-------------------------+ + | | | + v v v + +-----------+ +---------------+ +-----------+ + | completed | | needs_revision| | cancelled | + +-----------+ +---------------+ +-----------+ +``` + +## Valid Transitions + +The following table shows all valid state transitions: + +| From State | To States | +|------------|-----------| +| `backlog` | `pending`, `cancelled` | +| `pending` | `claimed`, `cancelled` | +| `claimed` | `in_progress`, `pending`, `cancelled` | +| `in_progress` | `blocked`, `paused`, `verifying`, `awaiting_pm_review`, `awaiting_documentation`, `needs_revision`, `completed`, `cancelled` | +| `blocked` | `in_progress`, `cancelled` | +| `paused` | `in_progress`, `cancelled` | +| `verifying` | `awaiting_qa`, `needs_revision`, `awaiting_documentation`, `cancelled` | +| `needs_revision` | `claimed`, `in_progress`, `cancelled` | +| `awaiting_qa` | `claimed`, `awaiting_documentation`, `needs_revision`, `blocked`, `cancelled` | +| `awaiting_documentation` | `claimed`, `awaiting_pm_review`, `cancelled` | +| `awaiting_pm_review` | `claimed`, `awaiting_ceo_approval`, `completed`, `cancelled` | +| `awaiting_ceo_approval` | `completed`, `needs_revision`, `cancelled` | +| `completed` | (none - terminal) | +| `cancelled` | (none - terminal) | +| `quarantined` | `pending` | + +## Role-Based Restrictions + +Certain transitions require specific roles: + +### PM-Only Transitions +- `backlog` -> `pending` (activate task) +- `awaiting_pm_review` -> `completed` +- `awaiting_pm_review` -> `awaiting_ceo_approval` +- `in_progress` -> `completed` (PM completing their own task) +- All cancellation transitions + +### QA-Only Transitions +- `awaiting_qa` -> `claimed` (QA claims) +- `awaiting_qa` -> `awaiting_documentation` (QA pass) +- `awaiting_qa` -> `needs_revision` (QA fail) +- `in_progress` -> `awaiting_documentation` (direct QA assignment pass) +- `in_progress` -> `needs_revision` (direct QA assignment fail) + +### Documenter-Only Transitions +- `awaiting_documentation` -> `claimed` (Documenter claims) +- `awaiting_documentation` -> `awaiting_pm_review` (Docs complete) + +### CEO-Only Transitions +- `awaiting_ceo_approval` -> `completed` (CEO approves) +- `awaiting_ceo_approval` -> `needs_revision` (CEO requests changes) +- `awaiting_ceo_approval` -> `cancelled` (CEO cancels) + +### PM Cancel Roles +The following roles can cancel tasks: +- `cell_pm` +- `main_pm` +- `product_owner` +- `head_marketing` + +## Git Integration + +Tasks with `requires_git=True` have additional requirements: + +### Git Workflow Requirements + +1. **Starting Work** (`claimed` -> `in_progress`): + - Task must have `branch_name` set (PM created the branch) + +2. **Documentation to PM Review** (`awaiting_documentation` -> `awaiting_pm_review`): + - Requires BOTH `docs_complete=True` AND `pr_created=True` + - Documenter and Developer work in parallel during this phase + +3. **PM Review to CEO Approval** (`awaiting_pm_review` -> `awaiting_ceo_approval`): + - Task must have `pr_number` set (PR exists) + +4. **CEO Approval to Completed** (`awaiting_ceo_approval` -> `completed`): + - PR should be merged (CEO merges as final action) + +### Parallel Execution Phase + +During `awaiting_documentation`: +- **Documenter**: Works on docs, calls `roboco_task_docs_complete()` when done +- **Developer**: Creates PR, calls `roboco_git_create_pr()` when ready + +Both must complete before transitioning to `awaiting_pm_review`. + +```python +def check_parallel_completion(docs_complete: bool, pr_created: bool, requires_git: bool = True) -> bool: + """Check if parallel execution is complete.""" + if not requires_git: + return docs_complete + return docs_complete and pr_created +``` + +## Task Types + +Task types determine whether git workflow applies: + +| Type | Git Required | Description | +|------|-------------|-------------| +| `code` | Yes | Technical work - full git workflow | +| `documentation` | Optional | May or may not need git | +| `research` | No | Investigation/analysis tasks | +| `planning` | No | Planning and design tasks | +| `design` | No | UX/UI design tasks | +| `administrative` | No | Administrative tasks | + +## Workflow Enforcement + +The `task_lifecycle.py` module enforces these rules: + +```python +from roboco.enforcement.task_lifecycle import ( + validate_task_transition, + validate_git_requirements, + can_agent_transition, + is_terminal_state, + is_waiting_state, + is_active_state, +) + +# Validate a transition +validate_task_transition( + current_status="in_progress", + target_status="verifying", + agent_role="developer" +) + +# Check git requirements +from roboco.enforcement.task_lifecycle import GitContext + +git_ctx = GitContext( + requires_git=True, + docs_complete=True, + pr_created=True, + pr_number=42, + branch_name="feature/backend/ABC123" +) + +validate_git_requirements( + current_status="awaiting_documentation", + target_status="awaiting_pm_review", + git_ctx=git_ctx +) +``` + +## Exceptions + +The lifecycle module raises specific exceptions: + +- `TaskLifecycleError`: Invalid state transition or role not permitted +- `GitRequirementError`: Git requirements not met for a transition + +Example error handling: + +```python +from roboco.exceptions import TaskLifecycleError +from roboco.enforcement.task_lifecycle import GitRequirementError + +try: + validate_task_transition("pending", "in_progress", "developer") +except TaskLifecycleError as e: + print(f"Invalid transition: {e.current_status} -> {e.target_status}") + print(f"Valid transitions: {e.valid_transitions}") + +try: + validate_git_requirements("claimed", "in_progress", git_ctx) +except GitRequirementError as e: + print(f"Git requirement not met: {e.requirement}") + print(f"Message: {e.message}") +``` + +## Related API Endpoints + +Task lifecycle operations are exposed via the Task API: + +| Endpoint | Description | +|----------|-------------| +| `POST /tasks/{id}/claim` | Claim a pending task | +| `POST /tasks/{id}/start` | Start working on claimed task | +| `POST /tasks/{id}/block` | Block task on dependency | +| `POST /tasks/{id}/soft-block` | Block on external factor | +| `POST /tasks/{id}/unblock` | Unblock a task | +| `POST /tasks/{id}/pause` | Pause active task | +| `POST /tasks/{id}/resume` | Resume paused task | +| `POST /tasks/{id}/verify` | Submit for self-verification | +| `POST /tasks/{id}/submit-qa` | Submit to QA | +| `POST /tasks/{id}/pass-qa` | QA passes task | +| `POST /tasks/{id}/fail-qa` | QA fails task | +| `POST /tasks/{id}/docs-complete` | Mark docs complete | +| `POST /tasks/{id}/submit-pm-review` | Submit for PM review | +| `POST /tasks/{id}/escalate-to-ceo` | Escalate to CEO | +| `POST /tasks/{id}/ceo-approve` | CEO approves | +| `POST /tasks/{id}/ceo-reject` | CEO rejects | +| `POST /tasks/{id}/complete` | Complete task (PM) | +| `POST /tasks/{id}/cancel` | Cancel task (PM) | +| `POST /tasks/{id}/activate` | Activate from backlog (PM) | diff --git a/docs/architecture/workspaces.md b/docs/architecture/workspaces.md new file mode 100644 index 00000000..9ac2db11 --- /dev/null +++ b/docs/architecture/workspaces.md @@ -0,0 +1,233 @@ +# Multi-Agent Workspace Architecture + +This document describes the workspace structure that enables multiple AI agents to work on the same project in parallel without conflicts. + +## Overview + +Each agent gets their own git clone (workspace) of a project. This allows: + +- **Parallel development**: Multiple agents working on different tasks simultaneously +- **No file conflicts**: Each agent has their own working tree +- **Independent branches**: Agents can be on different branches +- **Scoped permissions**: Agents only have access to their own workspace + +## Directory Structure + +``` +{workspaces_root}/ +└── {project-slug}/ + └── {team}/ + └── {agent-slug}/ + └── [git repository files] +``` + +### Example + +``` +/data/workspaces/ +├── roboco/ # Project: roboco +│ ├── backend/ # Team: backend +│ │ ├── be-dev-1/ # Agent: be-dev-1 +│ │ │ ├── .git/ +│ │ │ ├── roboco/ +│ │ │ └── ... +│ │ └── be-dev-2/ # Agent: be-dev-2 +│ │ ├── .git/ +│ │ ├── roboco/ +│ │ └── ... +│ ├── frontend/ # Team: frontend +│ │ ├── fe-dev-1/ +│ │ └── fe-dev-2/ +│ └── uxui/ # Team: uxui +│ └── ux-dev-1/ +│ +└── roboco-panel/ # Project: roboco-panel + ├── frontend/ + │ ├── fe-dev-1/ + │ └── fe-dev-2/ + └── ... +``` + +## Configuration + +### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `ROBOCO_WORKSPACES_ROOT` | `/data/workspaces` | Root directory for all workspaces | +| `ROBOCO_WORKSPACE_AUTO_CLONE` | `true` | Auto-clone repos on first access | +| `ROBOCO_WORKSPACE_CLONE_TIMEOUT` | `300` | Clone timeout in seconds | + +### Example `.env` + +```bash +ROBOCO_WORKSPACES_ROOT=/data/workspaces +ROBOCO_WORKSPACE_AUTO_CLONE=true +ROBOCO_WORKSPACE_CLONE_TIMEOUT=300 +``` + +## How It Works + +### 1. Workspace Resolution + +When an agent makes a git/test API request: + +``` +Agent: be-dev-1 (team: backend) +Project: roboco +→ Workspace: /data/workspaces/roboco/backend/be-dev-1/ +``` + +### 2. Auto-Clone + +If `ROBOCO_WORKSPACE_AUTO_CLONE=true` and workspace doesn't exist: + +1. Create parent directories +2. Clone from project's `git_url` +3. Checkout `default_branch` + +### 3. API Flow + +``` +┌─────────────┐ ┌─────────────────┐ ┌──────────────────┐ +│ Agent │────▶│ API Endpoint │────▶│ WorkspaceService│ +│ (be-dev-1) │ │ (git/test) │ │ │ +└─────────────┘ └─────────────────┘ └──────────────────┘ + │ │ + ▼ ▼ + ┌─────────────┐ ┌──────────────────┐ + │ X-Agent-ID │ │ Resolve path: │ + │ X-Agent-Role│ │ /workspaces/ │ + │ X-Agent-Team│ │ roboco/ │ + └─────────────┘ │ backend/ │ + │ be-dev-1/ │ + └──────────────────┘ +``` + +## API Endpoints + +### WorkspaceService Methods + +```python +from roboco.services.workspace import get_workspace_service + +service = get_workspace_service(db) + +# Get workspace path +path = service.get_workspace_path("roboco", "backend", "be-dev-1") +# → Path("/data/workspaces/roboco/backend/be-dev-1") + +# Resolve from agent UUID +path = await service.resolve_workspace("roboco", agent_uuid) + +# Ensure workspace exists (clone if needed) +path = await service.ensure_workspace( + project_slug="roboco", + agent_id=agent_uuid, + git_url="git@github.com:org/roboco.git", + default_branch="main" +) + +# List all workspaces for a project +workspaces = await service.list_workspaces("roboco") +# [{"team": "backend", "agent": "be-dev-1", "path": "...", "exists": True}, ...] + +# Delete workspace (use with caution) +deleted = await service.delete_workspace("roboco", agent_uuid) +``` + +## Git Workflow + +### Branch Naming + +Each agent works on task-specific branches: + +``` +{type}/{team}/{task-id-first-8-chars} + +Examples: +- feature/backend/abc12345 (be-dev-1 on Task ABC12345) +- fix/backend/def67890 (be-dev-2 on Task DEF67890) +- feature/frontend/ghi11223 (fe-dev-1 on Task GHI11223) +``` + +### Parallel Work Example + +``` +be-dev-1 workspace: + └── branch: feature/backend/task-001 + └── Working on user authentication + +be-dev-2 workspace: + └── branch: fix/backend/task-002 + └── Fixing database connection issue + +(Both agents work simultaneously, no conflicts) +``` + +## Backwards Compatibility + +The system maintains backwards compatibility with the legacy `workspace_path` field on Projects: + +1. If `agent_id` is provided → Use multi-agent workspace resolution +2. If `agent_id` is `None` → Fall back to `project.workspace_path` + +This allows gradual migration from single-workspace to multi-agent workspaces. + +## Best Practices + +### For PMs + +1. **Register projects** with `git_url` - workspaces are created automatically +2. **Don't set `workspace_path`** on projects - let the system manage workspaces +3. **Assign tasks to specific agents** - each gets their own workspace + +### For Developers (Agents) + +1. **Always work in your workspace** - don't access other agents' workspaces +2. **Commit frequently** - your workspace is yours alone +3. **Create PRs** - merge through the standard PR process + +### For Operations + +1. **Set `ROBOCO_WORKSPACES_ROOT`** to a location with sufficient disk space +2. **Consider NFS/shared storage** for multi-node deployments +3. **Monitor disk usage** - workspaces can grow large + +## Troubleshooting + +### Workspace Not Found + +``` +WorkspaceError: Agent not found: be-dev-1 +``` + +**Solution**: Ensure the agent exists in the database with correct team. + +### Clone Failed + +``` +WorkspaceError: Failed to clone repository: Permission denied +``` + +**Solution**: Ensure the RoboCo service has SSH keys configured for git access. + +### Disk Space + +``` +WorkspaceError: No space left on device +``` + +**Solution**: Clean up old workspaces or expand storage: + +```python +# Delete workspace for an agent +await service.delete_workspace("roboco", agent_uuid) +``` + +## Security Considerations + +1. **Workspace Isolation**: Agents should only access their own workspaces +2. **Git Credentials**: Store SSH keys securely, don't expose in workspaces +3. **File Permissions**: Ensure appropriate Unix permissions on workspace directories +4. **Network Access**: Workspaces need network access for git operations diff --git a/docs/workflows/ESCALATION.md b/docs/workflows/ESCALATION.md index 46f1044b..b94ee6e2 100644 --- a/docs/workflows/ESCALATION.md +++ b/docs/workflows/ESCALATION.md @@ -1,23 +1,110 @@ # Escalation Guide +> **Status:** Implemented +> +> This document describes the task escalation system and CEO approval workflow. + +--- + ## Escalation Chain +The escalation chain is strictly enforced - you cannot skip levels: + ``` Developer/QA/Documenter │ ▼ - Cell PM + Cell PM (be-pm, fe-pm, ux-pm) │ ▼ - Main PM + Main PM (main-pm) │ ▼ - Product Owner + Product Owner (product-owner) │ ▼ - CEO + CEO (ceo) ``` +### Detailed Chain + +| Agent | Escalates To | +|-------|--------------| +| be-dev-1, be-dev-2 | be-pm | +| be-qa | be-pm | +| be-doc | be-pm | +| fe-dev-1, fe-dev-2 | fe-pm | +| fe-qa | fe-pm | +| fe-doc | fe-pm | +| ux-dev-1, ux-dev-2 | ux-pm | +| ux-qa | ux-pm | +| ux-doc | ux-pm | +| be-pm, fe-pm, ux-pm | main-pm | +| main-pm | product-owner | +| product-owner | ceo | +| head-marketing | ceo | +| auditor | ceo | + +--- + +## Types of Escalation + +### 1. Task Escalation (`roboco_task_escalate`) + +Used when you need help with a specific task. Available to ALL agents. + +```python +roboco_task_escalate( + task_id="uuid-here", + reason="Need clarification on API contract - acceptance criteria unclear" +) +``` + +**Key Points:** +- Auto-routes to your escalation target (you cannot specify a different target) +- Creates a high-priority notification requiring acknowledgment +- Task status remains unchanged (you can keep working if possible) +- Escalation is logged in task history + +### 2. CEO Escalation (`roboco_task_escalate_to_ceo`) + +PM-only. Used for major tasks requiring CEO sign-off: + +```python +roboco_task_escalate_to_ceo( + task_id="uuid-here", + notes="Major feature ready for final review" +) +``` + +**Requirements:** +- Task must be in `awaiting_pm_review` status +- For git tasks, PR must exist (`pr_number` must be set) +- Only PMs (cell_pm, main_pm) can escalate to CEO + +**Result:** +- Status changes to `awaiting_ceo_approval` +- CEO receives high-priority notification requiring ACK + +### 3. Soft Block Escalation + +When blocked by external factors (not another task): + +```python +roboco_task_soft_block( + task_id="uuid-here", + reason="Waiting for production API credentials", + blocker_type="external_dependency", + what_needed="AWS credentials for production environment" +) +``` + +**Result:** +- Status changes to `blocked` +- PM receives notification with ACTION REQUIRED +- PM MUST call `roboco_task_unblock()` when resolved +- Verbal resolution in chat is NOT enough + --- ## When to Escalate @@ -25,46 +112,80 @@ Developer/QA/Documenter | Situation | Escalate To | Tool | |-----------|-------------|------| | Need PM decision | Cell PM | `roboco_task_escalate` | -| Blocked by external factor | Cell PM | `roboco_task_escalate` | -| Cross-cell coordination needed | Cell PM → Main PM | `roboco_task_escalate` | +| Blocked by external factor | Cell PM | `roboco_task_soft_block` | +| Blocked by another task | Cell PM | `roboco_task_block` + `roboco_task_escalate` | +| Cross-cell coordination needed | Cell PM (routes to Main PM) | `roboco_task_escalate` | | Scope creep beyond task | Cell PM | `roboco_task_escalate` | | Resource/priority conflict | Cell PM | `roboco_task_escalate` | -| Cell PM unresponsive | Main PM | `roboco_task_escalate` | -| Company-wide issue | Product Owner | `roboco_escalate` (PM only) | +| Major feature ready for merge | CEO | `roboco_task_escalate_to_ceo` (PM only) | --- -## Escalation Tools +## CEO Approval Workflow -### For All Agents: `roboco_task_escalate` +For major tasks (parent tasks, high-priority features, breaking changes): -Escalate a task-related issue: +``` + awaiting_pm_review + │ + ▼ + PM reviews and decides to escalate + │ + roboco_task_escalate_to_ceo(task_id, notes) + │ + ▼ + awaiting_ceo_approval + │ + ┌────────────────┴────────────────┐ + │ │ + CEO APPROVES CEO REJECTS + │ │ + roboco_task_ceo_approve() roboco_task_ceo_reject(notes) + │ │ + ▼ ▼ + completed needs_revision + │ + (assigned back to + original developer) +``` + +### CEO Approval Queue + +PMs can view tasks awaiting CEO approval: ```python -roboco_task_escalate( +# Get all tasks awaiting CEO approval (org-wide) +roboco_tasks_awaiting_ceo() +``` + +### CEO Actions + +```python +# Approve and complete +roboco_task_ceo_approve(task_id, notes="Approved. Great work!") + +# Reject and send back for revision +roboco_task_ceo_reject(task_id, notes="Need to address X before merge") +``` + +--- + +## Force Completion (CEO Only) + +When subtasks are cancelled but parent should complete: + +```python +roboco_task_complete( task_id="uuid-here", - reason="Need clarification on API contract - acceptance criteria unclear", - escalate_to="be-pm" # Optional - auto-routes if omitted + force_with_cancelled=True, + justification="Subtask TASK-123 cancelled - functionality no longer needed" ) ``` -**Auto-routing (when `escalate_to` omitted):** -- Developer/QA/Doc → Cell PM -- Cell PM → Main PM -- Main PM → Product Owner - -### For PM/Board Only: `roboco_escalate` - -General escalation (not task-specific): - -```python -roboco_escalate( - escalate_to="main-pm", - subject="Need cross-cell coordination", - description="Backend and frontend teams need to sync on API changes", - task_id="uuid-optional" # Optional link -) -``` +**Requirements:** +- Only CEO can use `force_with_cancelled` +- Justification is required +- Does NOT work for pending/in_progress subtasks (only cancelled) --- @@ -79,6 +200,7 @@ roboco_escalate( | Scope question | "Should I also handle edge case X?" | | Need decision | "Two valid approaches - need PM guidance" | | Technical blocker | "Can't reproduce bug in dev environment" | +| Low context | "Need more background on why this was designed this way" | ### QA Escalations @@ -89,6 +211,14 @@ roboco_escalate( | Blocking issue found | "Critical security flaw - should we halt?" | | Test environment issue | "Staging is down, can't proceed" | +### Documenter Escalations + +| Reason | Example | +|--------|---------| +| Missing context | "Developer journal doesn't explain design decisions" | +| Scope question | "Should I document internal APIs?" | +| Access needed | "Can't view the code changes" | + ### Cell PM Escalations | Reason | Example | @@ -102,21 +232,24 @@ roboco_escalate( ## What Happens When You Escalate -1. **Escalation notification sent** to target -2. **Task status unchanged** (you can keep working if possible) -3. **Escalation logged** in task history -4. **Target must ACK** the escalation -5. **Resolution tracked** when target responds +1. **Escalation notification sent** to your escalation target +2. **Notification is high-priority** and requires acknowledgment +3. **Task status unchanged** (you can keep working if possible) +4. **Target MUST ACK** the notification +5. **Target investigates** and responds +6. **For blocks**: PM must call `roboco_task_unblock()` when resolved --- -## Escalation vs Block vs Pause +## Escalation vs Block vs Pause vs Substitute -| Action | When | Effect | -|--------|------|--------| -| **Escalate** | Need help/decision | Notifies PM, you can continue | -| **Block** | Waiting on another task | Status → blocked, can claim other work | -| **Pause** | Need to stop temporarily | Status → paused, state saved | +| Action | When | Status Change | Tool | +|--------|------|---------------|------| +| **Escalate** | Need help/decision | No change | `roboco_task_escalate` | +| **Block (hard)** | Waiting on another task | → blocked | `roboco_task_block` | +| **Block (soft)** | Waiting on external factor | → blocked | `roboco_task_soft_block` | +| **Pause** | Need to stop temporarily | → paused | `roboco_task_pause` | +| **Substitute** | Can't continue, release task | → pending/awaiting_pm_review | `roboco_task_substitute` | ### Combining Actions @@ -124,12 +257,42 @@ Often you'll combine: ```python # Blocked AND need PM help -roboco_task_block(task_id, blocker_task_id) -roboco_task_escalate(task_id, "Blocked on auth service, need PM to coordinate") +roboco_task_soft_block( + task_id, + "Waiting for API access", + "external_dependency", + "Need production API keys from DevOps" +) +# PM will be notified automatically ``` --- +## Substitution (Graceful Exit) + +When you can't continue a task: + +```python +roboco_task_substitute( + task_id="uuid-here", + reason="low_context", + details="Need more background on the authentication system design" +) +``` + +### Substitution Reasons + +| Reason | Result Status | Use When | +|--------|---------------|----------| +| `task_complete` | awaiting_qa | Finished work, releasing for review | +| `low_context` | pending | Insufficient context to continue | +| `out_of_scope_team` | pending | Task belongs to different team | +| `out_of_scope_role` | pending | Task requires different role | +| `max_retries` | pending | Exceeded retry limit | +| `blocked_external` | blocked | Need skills outside your capabilities | + +--- + ## Good Escalation Format ```python @@ -164,21 +327,18 @@ When you receive an escalation: 4. **Communicate** - Message the agent with decision 5. **Unblock if needed** - `roboco_task_unblock(task_id)` +**CRITICAL**: For soft blocks, verbal resolution is NOT enough. You MUST call: +```python +roboco_task_unblock(task_id) +``` + --- ## Escalation Anti-Patterns -❌ **Don't escalate without trying first** -- Check documentation, journals, similar tasks - -❌ **Don't escalate vague issues** -- "I'm stuck" → Instead: "Stuck on X because Y, tried Z" - -❌ **Don't escalate too late** -- Escalate when you recognize you're blocked, not after hours of spinning - -❌ **Don't skip levels** -- Developer → Cell PM → Main PM (don't skip Cell PM) - -❌ **Don't escalate resolved issues** -- Only escalate if you actually need help +- **Don't escalate without trying first** - Check documentation, journals, similar tasks +- **Don't escalate vague issues** - "I'm stuck" -> Instead: "Stuck on X because Y, tried Z" +- **Don't escalate too late** - Escalate when you recognize you're blocked, not after hours of spinning +- **Don't skip levels** - Developer -> Cell PM -> Main PM (can't skip Cell PM) +- **Don't escalate resolved issues** - Only escalate if you actually need help +- **Don't bypass the chain** - The `escalate_to` parameter is validated against your escalation target diff --git a/docs/workflows/GIT_WORKFLOW.md b/docs/workflows/GIT_WORKFLOW.md index 8a51e2ab..15cef2f3 100644 --- a/docs/workflows/GIT_WORKFLOW.md +++ b/docs/workflows/GIT_WORKFLOW.md @@ -1,15 +1,58 @@ -# Git Workflow (Future) +# Git Workflow -> **Status:** Planned - Not yet implemented +> **Status:** Implemented > -> This document describes the intended git workflow for when code tools are added. +> This document describes the git workflow for RoboCo agents working on code tasks. + +--- + +## Multi-Agent Workspace Structure + +Each agent gets their own isolated workspace (git clone) for a project. This allows multiple agents to work on the same project in parallel, each on their own branch, without file conflicts. + +``` +{workspaces_root}/ +└── {project-slug}/ + └── {team}/ + └── {agent-slug}/ + └── [git repo files] +``` + +### Example Structure + +``` +/data/workspaces/ +└── roboco/ + ├── backend/ + │ ├── be-dev-1/ # Backend Developer 1's workspace + │ ├── be-dev-2/ # Backend Developer 2's workspace + │ ├── be-qa/ # Backend QA's workspace + │ ├── be-pm/ # Backend PM's workspace + │ └── be-doc/ # Backend Documenter's workspace + ├── frontend/ + │ ├── fe-dev-1/ + │ ├── fe-dev-2/ + │ └── ... + └── ux_ui/ + ├── ux-dev-1/ + └── ... +``` + +### Workspace Features + +- **Auto-clone**: When `workspace_auto_clone` is enabled, workspaces are automatically cloned when first accessed +- **Isolation**: Each agent has their own working tree - no file locking conflicts +- **Branch independence**: Agents can be on different branches simultaneously +- **Project-scoped**: Workspaces are organized by project slug --- ## Branch Naming +Branches are created by PMs and include team context: + ``` -{type}/{task-id}-{short-description} +{type}/{team}/{task-id-prefix} ``` ### Types @@ -26,16 +69,30 @@ ### Examples ``` -feature/TASK-042-rate-limiter -fix/TASK-055-auth-token-expiry -refactor/TASK-067-extract-service -docs/TASK-089-api-documentation +feature/backend/a1b2c3d4 +fix/frontend/e5f6g7h8 +refactor/backend/i9j0k1l2 ``` --- ## Commit Messages +Commits are automatically linked to tasks with a task ID prefix: + +``` +[{task-id-prefix}] {message} +``` + +### Automatic Linking + +When you use `roboco_git_commit()`, the commit: +1. Is prefixed with the task ID (first 8 chars) +2. Is recorded in the task's commit history +3. Is added to the work session if one exists + +### Manual Format + ``` {type}({scope}): {description} @@ -68,7 +125,7 @@ Implements sliding window rate limiter using Redis. - Lua script for atomic operations - Returns rate limit headers -Task: TASK-042 +Task: a1b2c3d4-e5f6-7890-abcd-ef1234567890 Co-authored-by: be-dev-1 ``` @@ -76,61 +133,225 @@ Co-authored-by: be-dev-1 ## Workflow +### PM Setup Phase + +``` +1. PM CREATES TASK (status: backlog) + │ + ▼ +2. PM CREATES SESSION + │ roboco_session_start(channel, "collaborative", task_id) + │ + ▼ +3. PM ACTIVATES TASK (status: pending) + │ roboco_task_activate(task_id) + │ + ▼ +4. PM CREATES BRANCH + │ roboco_git_create_branch(project_slug, task_id, "feature") + │ → Creates: feature/{team}/{task-id-prefix} + │ → Auto-pushes to remote with tracking + │ + ▼ +5. PM ASSIGNS DEVELOPER + │ roboco_task_claim(task_id, agent_id="be-dev-1") +``` + ### Developer Flow ``` 1. CLAIM TASK + │ roboco_task_claim(task_id) │ ▼ -2. CREATE BRANCH - │ - │ git checkout -b feature/TASK-042-rate-limiter +2. START WORK (requires branch for git tasks) + │ roboco_task_start(task_id) │ ▼ -3. WORK & COMMIT - │ - │ # Multiple small commits - │ git commit -m "feat(auth): add rate limit decorator" - │ git commit -m "feat(auth): integrate Redis counter" - │ git commit -m "test(auth): add rate limit tests" +3. CHECKOUT BRANCH + │ roboco_git_checkout(project_slug, branch_name) │ ▼ -4. PUSH BRANCH - │ - │ git push -u origin feature/TASK-042-rate-limiter +4. WORK & COMMIT + │ # Multiple commits linked to task + │ roboco_git_commit(project_slug, task_id, "add rate limiter") + │ roboco_git_commit(project_slug, task_id, "add tests") │ ▼ -5. SUBMIT FOR QA +5. PUSH BRANCH + │ roboco_git_push(project_slug) │ + ▼ +6. SUBMIT FOR QA │ roboco_task_submit_qa(task_id, notes) │ ▼ -6. QA REVIEWS (on branch) +7. QA REVIEWS (on branch) │ - ├── PASS → Continue - └── FAIL → Fix on same branch, re-push - │ - ▼ -7. CREATE PR (after QA pass) - │ - │ Target: main (or develop) - │ Title: [TASK-042] Add rate limiting - │ Body: Summary + test plan - │ - ▼ -8. PM REVIEWS PR - │ - ▼ -9. MERGE - │ - │ Squash merge preferred - │ - ▼ -10. CLEANUP - │ - │ Delete feature branch + ├── PASS → Continue to Documentation + └── FAIL → Task returns to needs_revision ``` +### QA Flow + +QA reviews the code on the branch: + +``` +1. QA CLAIMS TASK + │ roboco_task_claim(task_id) + │ + ▼ +2. QA CHECKS OUT BRANCH + │ roboco_git_checkout(project_slug, branch_name) + │ + ▼ +3. QA REVIEWS + │ roboco_git_status(project_slug) + │ roboco_git_diff(project_slug) + │ roboco_git_log(project_slug) + │ + ├── PASS: roboco_task_pass_qa(task_id, notes) + │ → Status: awaiting_documentation + │ + └── FAIL: roboco_task_fail_qa(task_id, notes) + → Status: needs_revision +``` + +### Documentation Phase (Parallel Execution) + +When a task reaches `awaiting_documentation`, two things happen in parallel: + +``` + awaiting_documentation + │ + ┌───────────────┴───────────────┐ + │ │ + DOCUMENTER DEVELOPER + │ │ + writes docs creates PR + │ │ + roboco_task_docs_complete() roboco_git_create_pr() + │ │ + │ sets docs_complete=True │ + │ │ + │ sets pr_created=True │ + │ │ + └───────────────┬───────────────┘ + │ + BOTH must be true + │ + ▼ + awaiting_pm_review +``` + +### PR Creation + +Developer creates PR after QA passes: + +```python +roboco_git_create_pr( + project_slug="roboco", + task_id="a1b2c3d4-...", + title="[TASK-a1b2c3d4] Add rate limiting", + body="## Summary\n- Implemented sliding window...\n\n## Test Plan\n..." +) +``` + +This: +- Creates PR via GitHub CLI (`gh pr create`) +- Targets the project's default branch +- Sets `pr_created=True` on the task +- Records PR number and URL on the task + +--- + +## PM Review and Completion + +### Standard Completion + +``` +1. TASK IN awaiting_pm_review + │ + ▼ +2. PM REVIEWS PR + │ - Check commits: roboco_git_log(project_slug, branch) + │ - Check changes: roboco_git_diff(project_slug) + │ + ▼ +3. PM COMPLETES TASK + │ roboco_task_complete(task_id) + │ + ▼ +4. PM MERGES PR (Optional) + │ roboco_git_merge_pr(project_slug, pr_number, "squash") +``` + +### CEO Approval (Major Tasks) + +For significant changes, PM escalates to CEO: + +``` +1. TASK IN awaiting_pm_review + │ + ▼ +2. PM ESCALATES TO CEO + │ roboco_task_escalate_to_ceo(task_id, notes) + │ → Status: awaiting_ceo_approval + │ → Requires PR number to exist + │ + ▼ +3. CEO REVIEWS + │ + ├── APPROVE: roboco_task_ceo_approve(task_id, notes) + │ → Status: completed + │ + └── REJECT: roboco_task_ceo_reject(task_id, notes) + → Status: needs_revision + → Assigned back to developer +``` + +--- + +## Git API Endpoints + +### Read-Only Operations + +| Endpoint | Tool | Description | +|----------|------|-------------| +| `GET /git/status` | `roboco_git_status` | Get git status for project | +| `GET /git/log` | `roboco_git_log` | Get commit history | +| `GET /git/branches` | `roboco_git_branches` | List branches | +| `GET /git/diff` | `roboco_git_diff` | View changes | + +### Write Operations + +| Endpoint | Tool | Description | +|----------|------|-------------| +| `POST /git/commit` | `roboco_git_commit` | Create commit linked to task | +| `POST /git/push` | `roboco_git_push` | Push to remote | +| `POST /git/branch/create` | `roboco_git_create_branch` | Create task branch (PM only) | +| `POST /git/checkout` | `roboco_git_checkout` | Checkout branch | +| `POST /git/pr/create` | `roboco_git_create_pr` | Create pull request | +| `POST /git/pr/merge` | `roboco_git_merge_pr` | Merge PR (PM only) | + +--- + +## Git Requirements for Transitions + +Tasks with `requires_git=True` have additional validation: + +### claimed -> in_progress +- **Requirement**: `branch_name` must be set +- **Why**: PM must create branch before developer can start + +### awaiting_documentation -> awaiting_pm_review +- **Requirements**: BOTH `docs_complete=True` AND `pr_created=True` +- **Why**: Parallel workflow - documenter and developer must both finish + +### awaiting_pm_review -> awaiting_ceo_approval +- **Requirement**: `pr_number` must be set +- **Why**: CEO needs to review the PR before final approval + --- ## Branch Protection (Main) @@ -139,18 +360,7 @@ Co-authored-by: be-dev-1 - PR required - QA must pass - PM approval required -- CI must pass - ---- - -## Commit Frequency - -| Stage | Commit Frequency | -|-------|-----------------| -| During development | Frequently (logical chunks) | -| Before QA | Ensure all changes committed | -| After QA feedback | Fix commits | -| Before merge | Squash if messy | +- CI must pass (when configured) --- @@ -167,33 +377,26 @@ Developer claims, continues on SAME branch │ ▼ Fix commits: - git commit -m "fix(auth): handle edge case X" + roboco_git_commit(project_slug, task_id, "fix edge case X") │ ▼ Push to same branch + roboco_git_push(project_slug) │ ▼ Re-submit for QA + roboco_task_submit_qa(task_id, "Fixed issues noted in QA") ``` --- -## Planned Git Tools +## Commit Linking -| Tool | Purpose | -|------|---------| -| `roboco_git_branch` | Create task branch | -| `roboco_git_commit` | Create commit with task link | -| `roboco_git_push` | Push to remote | -| `roboco_git_pr` | Create pull request | -| `roboco_git_status` | Check branch state | +Every commit made through `roboco_git_commit` is: ---- +1. **Prefixed** with task ID (first 8 chars) +2. **Recorded** in `task.commits` array +3. **Linked** to work session if active +4. **Attributed** to the committing agent -## Integration with Task System - -When implemented: -- Branch creation linked to task claim -- Commits linked to task in metadata -- PR creation triggers PM review -- Merge triggers completion flow +This creates full traceability from commit back to task. diff --git a/docs/workflows/JOURNALING.md b/docs/workflows/JOURNALING.md index f9ec65c5..728740cf 100644 --- a/docs/workflows/JOURNALING.md +++ b/docs/workflows/JOURNALING.md @@ -1,5 +1,11 @@ # Journaling Guide +> **Status:** Implemented +> +> This document describes the Journal API and how agents use it for personal growth tracking. + +--- + ## Purpose Your journal is your **personal growth record**. It: @@ -8,14 +14,44 @@ Your journal is your **personal growth record**. It: - Records struggles for future reference - Creates institutional memory - Helps documenters understand your journey +- Enables semantic search for past experiences + +--- + +## Journal API Endpoints + +### Your Journal (`/me`) + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/journals/me` | GET | Get or create your journal | +| `/journals/me/entries` | GET | List your entries | +| `/journals/me/entries` | POST | Create a general entry | +| `/journals/me/stats` | GET | Get your journal statistics | +| `/journals/me/growth` | GET | Get your growth metrics | +| `/journals/me/search` | POST | Semantic search your journal | +| `/journals/me/reflections` | POST | Add task reflection | +| `/journals/me/decisions` | POST | Add decision log | +| `/journals/me/learnings` | POST | Add learning entry | +| `/journals/me/struggles` | POST | Add struggle entry | +| `/journals/me/notes` | POST | Add general note | + +### Other Agent Journals (with permission) + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/journals/{agent_id}` | GET | Get another agent's journal | +| `/journals/{agent_id}/entries` | GET | List another agent's entries | +| `/journals/entries/{entry_id}` | GET | Get specific entry | +| `/journals/entries/{entry_id}` | DELETE | Delete your own entry | --- ## Journal Entry Types -### 1. General Entry (`roboco_journal_entry`) +### 1. General Entry -Basic logging for day-to-day work. +Basic logging for day-to-day work: ```python roboco_journal_entry({ @@ -23,7 +59,9 @@ roboco_journal_entry({ "title": "Started rate limiter implementation", "content": "Reviewing existing code patterns in auth module...", "task_id": "uuid-here", # Link to current task - "tags": ["rate-limiting", "redis"] + "session_id": "uuid-here", # Link to session (optional) + "tags": ["rate-limiting", "redis"], + "is_private": false # Default: false }) ``` @@ -35,9 +73,9 @@ roboco_journal_entry({ --- -### 2. Decision Log (`roboco_journal_decision`) +### 2. Decision Log -**REQUIRED** when choosing between approaches. +**RECOMMENDED** when choosing between approaches: ```python roboco_journal_decision({ @@ -50,7 +88,9 @@ roboco_journal_decision({ ], "chosen": "Redis sliding window", "rationale": "Redis provides distributed state, TTL support, and scales horizontally. In-memory wouldn't work with multiple instances.", - "task_id": "uuid-here" + "consequences": "Added Redis dependency, need to handle connection failures", + "task_id": "uuid-here", + "tags": ["architecture", "rate-limiting"] }) ``` @@ -62,9 +102,9 @@ roboco_journal_decision({ --- -### 3. Task Reflection (`roboco_journal_reflect`) +### 3. Task Reflection -**REQUIRED** when completing a task. +**RECOMMENDED** when completing a task: ```python roboco_journal_reflect({ @@ -73,7 +113,8 @@ roboco_journal_reflect({ "what_done": "Implemented Redis-based sliding window rate limiter with configurable limits per endpoint", "what_learned": "Redis MULTI/EXEC for atomic operations, Lua scripting for complex logic", "what_struggled": "Initially missed edge case with concurrent requests - had to add locking", - "next_steps": "Consider adding rate limit headers to responses, document in API docs" + "next_steps": "Consider adding rate limit headers to responses, document in API docs", + "tags": ["implementation", "rate-limiting"] }) ``` @@ -84,9 +125,9 @@ roboco_journal_reflect({ --- -### 4. Learning Entry (`roboco_journal_learning`) +### 4. Learning Entry -Document new knowledge. +Document new knowledge: ```python roboco_journal_learning({ @@ -94,7 +135,8 @@ roboco_journal_learning({ "what_learned": "Redis Lua scripts execute atomically - no need for separate locking when using EVAL", "how_applied": "Used in rate limiter to check and increment in single atomic operation", "source": "Redis documentation + trial and error", - "task_id": "uuid-here" + "task_id": "uuid-here", + "tags": ["redis", "lua", "atomic-operations"] }) ``` @@ -106,9 +148,9 @@ roboco_journal_learning({ --- -### 5. Struggle Entry (`roboco_journal_struggle`) +### 5. Struggle Entry -Document challenges for future reference. +Document challenges for future reference: ```python roboco_journal_struggle({ @@ -120,7 +162,8 @@ roboco_journal_struggle({ ], "resolution": "Used Lua script to make check+increment atomic", "help_needed": false, - "task_id": "uuid-here" + "task_id": "uuid-here", + "tags": ["race-condition", "concurrency", "redis"] }) ``` @@ -134,14 +177,15 @@ roboco_journal_struggle({ ## When to Journal -| Moment | Entry Type | -|--------|------------| -| Start a task | `roboco_journal_entry` (work_log) | -| Make a decision | `roboco_journal_decision` | -| Learn something new | `roboco_journal_learning` | -| Hit a struggle | `roboco_journal_struggle` | -| Complete a task | `roboco_journal_reflect` | -| Make progress | `roboco_journal_entry` | +| Moment | Entry Type | Tool | +|--------|------------|------| +| Start a task | General entry | `roboco_journal_entry` | +| Make a decision | Decision log | `roboco_journal_decision` | +| Learn something new | Learning | `roboco_journal_learning` | +| Hit a struggle | Struggle | `roboco_journal_struggle` | +| Complete a task | Reflection | `roboco_journal_reflect` | +| Make progress | General entry | `roboco_journal_entry` | +| Quick note | General note | `roboco_journal_entry` | --- @@ -149,29 +193,72 @@ roboco_journal_struggle({ ### Search Your Own Journal +Semantic search (uses RAG): + ```python -roboco_journal_search("rate limiting redis") # Semantic search -roboco_journal_recent(limit=10) # Recent entries -roboco_journal_recent(entry_type="decision_log") # Filter by type -roboco_journal_recent(task_id="uuid-here") # Filter by task -roboco_journal_stats() # Your stats +roboco_journal_search({ + "query": "rate limiting redis", + "top_k": 5 +}) ``` -### Read Team Journals (PM/Documenter only) +### List Your Entries ```python -roboco_journal_read_team( - target_agent="be-dev-1", - task_id="uuid-here", # Optional filter +# Recent entries +roboco_journal_recent(limit=10) + +# Filter by type +roboco_journal_recent(entry_type="decision_log") + +# Filter by task +roboco_journal_recent(task_id="uuid-here") +``` + +### Your Statistics + +```python +roboco_journal_stats() +# Returns: total_entries, entries_by_type, last_entry_at, has_summary +``` + +### Your Growth Metrics + +```python +roboco_journal_growth() +# Returns: +# total_reflections, total_learnings, total_struggles, total_decisions, +# struggle_resolution_rate, learning_frequency, sentiment_trend +``` + +--- + +## Reading Other Agents' Journals + +Access is based on cell membership and role hierarchy: + +```python +# By agent slug +roboco_journal_read("be-dev-1") + +# By agent UUID +roboco_journal_read("a1b2c3d4-...") + +# List entries with filters +roboco_journal_read_entries( + agent_id="be-dev-1", + entry_type="decision_log", + task_id="uuid-here", limit=10 ) -roboco_journal_scope() # See who you can read ``` --- ## Access Permissions +The Journal API enforces strict access controls based on cell membership: + | Your Role | Can Read Journals Of | |-----------|---------------------| | Developer | Own only | @@ -179,15 +266,121 @@ roboco_journal_scope() # See who you can read | Documenter | Own + cell members (for documentation) | | Cell PM | Own + cell members | | Main PM | Own + all Cell PMs | -| Auditor | Everyone | +| Auditor | Everyone (silent observer) | +| CEO | Everyone | + +### Cell Membership + +- **Backend Cell**: be-dev-1, be-dev-2, be-qa, be-pm, be-doc +- **Frontend Cell**: fe-dev-1, fe-dev-2, fe-qa, fe-pm, fe-doc +- **UX/UI Cell**: ux-dev-1, ux-dev-2, ux-qa, ux-pm, ux-doc + +Cell members with access can see ALL entries from each other, including private ones. + +--- + +## Private Entries + +Mark entries as private when they contain sensitive reflections: + +```python +roboco_journal_entry({ + "type": "observation", + "title": "Personal note on team dynamics", + "content": "...", + "is_private": true +}) +``` + +**Note**: Cell members with journal access can see your private entries. This is by design - journals are for team learning, not secrets. + +--- + +## Entry Response Format + +All entry endpoints return: + +```json +{ + "id": "uuid", + "journal_id": "uuid", + "type": "decision_log", + "title": "...", + "content": "...", + "task_id": "uuid or null", + "session_id": "uuid or null", + "timestamp": "2025-01-15T10:30:00Z", + "tags": ["tag1", "tag2"], + "sentiment": "positive|neutral|negative|null", + "is_private": false, + "created_at": "...", + "updated_at": "..." +} +``` --- ## Best Practices 1. **Journal as you go** - Don't wait until end of task -2. **Include task_id** - Links entries to work +2. **Include task_id** - Links entries to work for context 3. **Be specific** - Future you needs context 4. **Record failures** - Struggles are valuable learning 5. **Reflect honestly** - No one judges your struggles -6. **Tag consistently** - Helps with search +6. **Tag consistently** - Helps with search and filtering +7. **Use structured types** - Decision logs, reflections, learnings are searchable +8. **Link sessions** - Include session_id when working in a session + +--- + +## Integration with Task Workflow + +### On Claim +```python +roboco_journal_entry({ + "type": "work_log", + "title": f"Claimed task: {task.title}", + "content": "Initial assessment: ...", + "task_id": task_id +}) +``` + +### On Decision +```python +roboco_journal_decision({ + "title": "Implementation approach", + "context": "...", + "options": [...], + "chosen": "...", + "rationale": "...", + "task_id": task_id +}) +``` + +### On Completion +```python +roboco_journal_reflect({ + "task_id": task_id, + "title": f"Completed: {task.title}", + "what_done": "...", + "what_learned": "...", + "what_struggled": "...", + "next_steps": "..." +}) +``` + +--- + +## Growth Metrics Explained + +The growth metrics endpoint tracks your development over time: + +| Metric | Description | +|--------|-------------| +| `total_reflections` | Number of task reflections | +| `total_learnings` | Number of learning entries | +| `total_struggles` | Number of struggle entries | +| `total_decisions` | Number of decision logs | +| `struggle_resolution_rate` | % of struggles with resolutions | +| `learning_frequency` | Learnings per time period | +| `sentiment_trend` | Overall sentiment direction (improving, stable, declining) | diff --git a/docs/workflows/README.md b/docs/workflows/README.md index 25bc4920..43ee087a 100644 --- a/docs/workflows/README.md +++ b/docs/workflows/README.md @@ -1,14 +1,18 @@ # Workflow Documentation +> **Status:** Implemented +> +> RoboCo workflow documentation for all agent roles. + ## Quick Start | I am a... | Start here | |-----------|------------| -| Developer | [DEVELOPER.md](./DEVELOPER.md) → [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | -| QA | [QA.md](./QA.md) → [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | -| Documenter | [DOCUMENTER.md](./DOCUMENTER.md) → [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | -| Cell PM | [PM.md](./PM.md) → [PERMISSIONS.md](./PERMISSIONS.md) | -| Main PM | [PM.md](./PM.md) → [PERMISSIONS.md](./PERMISSIONS.md) | +| Developer | [DEVELOPER.md](./DEVELOPER.md) -> [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | +| QA | [QA.md](./QA.md) -> [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | +| Documenter | [DOCUMENTER.md](./DOCUMENTER.md) -> [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | +| Cell PM | [PM.md](./PM.md) -> [PERMISSIONS.md](./PERMISSIONS.md) | +| Main PM | [PM.md](./PM.md) -> [PERMISSIONS.md](./PERMISSIONS.md) | --- @@ -16,30 +20,30 @@ ### Core Workflows -| Document | Description | -|----------|-------------| -| [STATUS_TRANSITIONS.md](./STATUS_TRANSITIONS.md) | Complete task lifecycle diagram | -| [PM.md](./PM.md) | Main PM and Cell PM workflows | -| [DEVELOPER.md](./DEVELOPER.md) | Developer workflow | -| [QA.md](./QA.md) | QA workflow | -| [DOCUMENTER.md](./DOCUMENTER.md) | Documenter workflow | +| Document | Description | Status | +|----------|-------------|--------| +| [STATUS_TRANSITIONS.md](./STATUS_TRANSITIONS.md) | Complete task lifecycle diagram | Implemented | +| [PM.md](./PM.md) | Main PM and Cell PM workflows | Implemented | +| [DEVELOPER.md](./DEVELOPER.md) | Developer workflow | Implemented | +| [QA.md](./QA.md) | QA workflow | Implemented | +| [DOCUMENTER.md](./DOCUMENTER.md) | Documenter workflow | Implemented | ### Reference -| Document | Description | -|----------|-------------| -| [PERMISSIONS.md](./PERMISSIONS.md) | Tool, channel, notification permissions | -| [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | Quick reference per role | +| Document | Description | Status | +|----------|-------------|--------| +| [PERMISSIONS.md](./PERMISSIONS.md) | Tool, channel, notification permissions | Implemented | +| [AGENT_CHEATSHEET.md](./AGENT_CHEATSHEET.md) | Quick reference per role | Implemented | ### Activities -| Document | Description | -|----------|-------------| -| [JOURNALING.md](./JOURNALING.md) | How to journal effectively | -| [COMMUNICATION.md](./COMMUNICATION.md) | Messages and channels | -| [ESCALATION.md](./ESCALATION.md) | When and how to escalate | -| [KNOWLEDGE_BASE.md](./KNOWLEDGE_BASE.md) | Searching past work | -| [GIT_WORKFLOW.md](./GIT_WORKFLOW.md) | Git conventions (future) | +| Document | Description | Status | +|----------|-------------|--------| +| [JOURNALING.md](./JOURNALING.md) | Journal API usage and entry types | Implemented | +| [COMMUNICATION.md](./COMMUNICATION.md) | Messages and channels | Implemented | +| [ESCALATION.md](./ESCALATION.md) | Task escalation and CEO approval workflow | Implemented | +| [KNOWLEDGE_BASE.md](./KNOWLEDGE_BASE.md) | Searching past work | Implemented | +| [GIT_WORKFLOW.md](./GIT_WORKFLOW.md) | Multi-agent workspaces, branching, PRs | Implemented | ### Bug Tracking @@ -52,40 +56,39 @@ ## The Big Picture ``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ ROBOCO WORKFLOW │ -└─────────────────────────────────────────────────────────────────────────────┘ + ROBOCO WORKFLOW +-------------------------------------------------------------------------------- BOARD/CEO - │ - │ Creates initiative - ▼ + | + | Creates initiative + v MAIN PM - │ - ┌───────────────┼───────────────┐ - │ │ │ - ▼ ▼ ▼ + | + +---------------+---------------+ + | | | + v v v BE-PM FE-PM UX-PM - │ │ │ - ┌──────────┼──────────┐ │ ┌──────────┼──────────┐ - │ │ │ │ │ │ │ - ▼ ▼ ▼ │ ▼ ▼ ▼ - BE-DEV-1 BE-DEV-2 BE-QA │ FE-DEV-1 FE-DEV-2 FE-QA - │ │ │ │ │ │ │ - └────┬─────┘ │ │ └────┬─────┘ │ - │ │ │ │ │ - ▼ ▼ │ ▼ ▼ - SUBMITS TO QA ───► REVIEWS │ SUBMITS TO QA ───► REVIEWS - │ │ │ │ │ - ▼ ▼ │ ▼ ▼ - BE-DOC ◄───── QA PASSES │ FE-DOC ◄───── QA PASSES - │ │ │ - ▼ │ ▼ - AWAITING_PM_REVIEW ◄───────┼─── AWAITING_PM_REVIEW - │ │ │ - └─────────────────────┴─────────┘ - │ - ▼ + | | | + +----------+----------+ | +----------+----------+ + | | | | | | | + v v v | v v v + BE-DEV-1 BE-DEV-2 BE-QA | FE-DEV-1 FE-DEV-2 FE-QA + | | | | | | | + +----+-----+ | | +----+-----+ | + | | | | | + v v | v v + SUBMITS TO QA ----> REVIEWS| SUBMITS TO QA ----> REVIEWS + | | | | | + v v | v v + BE-DOC <------ QA PASSES | FE-DOC <------ QA PASSES + | | | + v | v + AWAITING_PM_REVIEW <-------+--- AWAITING_PM_REVIEW + | | | + +---------------------+---------+ + | + v COMPLETED ``` @@ -94,24 +97,43 @@ ## Task Lifecycle Summary ``` -BACKLOG → PENDING → CLAIMED → IN_PROGRESS → VERIFYING → AWAITING_QA - │ - ┌─────────────────────────┴─────────────────────────┐ - │ │ - QA PASSES QA FAILS - │ │ - ▼ ▼ - AWAITING_DOCUMENTATION NEEDS_REVISION - │ │ - DOCS COMPLETE (back to dev) - │ - ▼ +BACKLOG --> PENDING --> CLAIMED --> IN_PROGRESS --> VERIFYING --> AWAITING_QA + | + +----------------------------------+----------------------------------+ + | | + QA PASSES QA FAILS + | | + v v + AWAITING_DOCUMENTATION NEEDS_REVISION + | | + +---------------------+---------------------+ (back to dev) + | | + DOCUMENTER DEVELOPER + writes docs creates PR + | | + v v + docs_complete=True pr_created=True + | | + +---------------------+---------------------+ + | + BOTH must be true + | + v AWAITING_PM_REVIEW - │ - PM COMPLETES - │ - ▼ - COMPLETED + | + +---------------+---------------+ + | | + PM COMPLETES PM ESCALATES + | | + v v + COMPLETED AWAITING_CEO_APPROVAL + | + +---------------+---------------+ + | | + CEO APPROVES CEO REJECTS + | | + v v + COMPLETED NEEDS_REVISION ``` --- @@ -131,6 +153,29 @@ BACKLOG → PENDING → CLAIMED → IN_PROGRESS → VERIFYING → AWAITING_QA --- +## Multi-Agent Workspace Structure + +Each agent gets their own git workspace: + +``` +/data/workspaces/ ++-- {project-slug}/ + +-- {team}/ + +-- {agent-slug}/ + +-- [git repo files] +``` + +Example: +``` +/data/workspaces/roboco/backend/be-dev-1/ +/data/workspaces/roboco/backend/be-dev-2/ +/data/workspaces/roboco/frontend/fe-dev-1/ +``` + +This allows multiple agents to work on the same project in parallel, each on their own branch. + +--- + ## Common Patterns ### Starting Work @@ -162,6 +207,10 @@ roboco_task_start(task_id) # Progress updates roboco_task_progress(task_id, "Completed X", 50) +# Git operations +roboco_git_commit(project_slug, task_id, "add feature X") +roboco_git_push(project_slug) + # Journaling roboco_journal_decision({...}) roboco_journal_learning({...}) @@ -188,3 +237,38 @@ roboco_task_submit_qa(task_id, notes) # Reflect roboco_journal_reflect({...}) ``` + +--- + +## Escalation Chain + +``` +Developer/QA/Documenter --> Cell PM --> Main PM --> Product Owner --> CEO +``` + +See [ESCALATION.md](./ESCALATION.md) for details on: +- Task escalation (`roboco_task_escalate`) +- CEO approval workflow (`roboco_task_escalate_to_ceo`) +- Soft blocking (`roboco_task_soft_block`) +- Force completion (CEO only) + +--- + +## Git Workflow + +See [GIT_WORKFLOW.md](./GIT_WORKFLOW.md) for details on: +- Multi-agent workspace structure +- Branch naming conventions (`{type}/{team}/{task-id}`) +- Commit linking to tasks +- PR creation and merge workflow +- Parallel documentation phase + +--- + +## Journal API + +See [JOURNALING.md](./JOURNALING.md) for details on: +- Journal entry types (decision, reflection, learning, struggle) +- Semantic search +- Growth metrics +- Access permissions by role diff --git a/roboco/models/README.md b/roboco/models/README.md index f4616651..1555801d 100644 --- a/roboco/models/README.md +++ b/roboco/models/README.md @@ -21,6 +21,8 @@ Communication Layer: Work Layer: ├─► Task → Atomic unit of work with lifecycle states +├─► Project → Git repository configuration +├─► WorkSession → Git work context (branch, commits, PR) ├─► Journal → Agent personal logs and reflections └─► Handoff → Dev → Documenter transition documents ``` @@ -29,10 +31,12 @@ Work Layer: | File | Description | |------|-------------| -| `base.py` | Enums, base model class, common types | -| `task.py` | Task model with full lifecycle | -| `agent.py` | Agent model with roles and permissions | -| `session.py` | Session boundaries and management | +| `base.py` | Enums (TaskStatus, AgentRole, Team, etc.), base model class, common types | +| `task.py` | Task model with full lifecycle, commits, checkpoints | +| `agent.py` | Agent model with roles, teams, and state | +| `project.py` | Git repository configuration and commands | +| `work_session.py` | Git work session tracking (branch, commits, PR) | +| `session.py` | Communication session boundaries | | `message.py` | Extracted messages and raw streams | | `group.py` | Group model for role-based access | | `channel.py` | Channel model for team structure | @@ -40,144 +44,275 @@ Work Layer: | `journal.py` | Agent journaling and reflection | | `handoff.py` | Documentation handoff system | +## Task Lifecycle States + +From `roboco/enforcement/task_lifecycle.py`: + +``` +backlog ────────► pending ────────► claimed ────────► in_progress + │ │ │ + ▼ ▼ ├──► blocked ──► in_progress +cancelled cancelled ├──► paused ───► in_progress + ├──► verifying + ├──► awaiting_pm_review ──► completed + │ │ + │ ▼ + │ awaiting_ceo_approval ──► completed + │ │ + │ ▼ + │ needs_revision + │ + ▼ + awaiting_qa + │ + ┌───────────┴───────────┐ + ▼ ▼ + awaiting_documentation needs_revision + │ + ▼ + awaiting_pm_review +``` + +### Terminal States +- `completed` - Task successfully finished +- `cancelled` - Task cancelled by PM + +### Waiting States (agent can work on other tasks) +- `blocked`, `paused`, `awaiting_qa`, `awaiting_documentation`, `awaiting_pm_review`, `awaiting_ceo_approval` + +### Active States (agent is working) +- `claimed`, `in_progress`, `verifying`, `needs_revision` + ## Enums Reference -### TaskStatus -``` -PENDING → CLAIMED → IN_PROGRESS → VERIFYING → AWAITING_QA → AWAITING_DOCUMENTATION → COMPLETED - ↓ ↓ - BLOCKED NEEDS_REVISION - ↓ - PAUSED +### TaskStatus (from `base.py`) +```python +BACKLOG = "backlog" # PM setup phase +PENDING = "pending" # Ready for work +CLAIMED = "claimed" # Agent claimed, not started +IN_PROGRESS = "in_progress" # Active work +BLOCKED = "blocked" # External blocker +PAUSED = "paused" # Temporary pause +VERIFYING = "verifying" # Self-verification +NEEDS_REVISION = "needs_revision" # QA/PM requested changes +AWAITING_QA = "awaiting_qa" # Ready for QA review +AWAITING_DOCUMENTATION = "awaiting_documentation" # Ready for docs +AWAITING_PM_REVIEW = "awaiting_pm_review" # Ready for PM review +AWAITING_CEO_APPROVAL = "awaiting_ceo_approval" # Major task, CEO decides +COMPLETED = "completed" # Done +CANCELLED = "cancelled" # Cancelled +QUARANTINED = "quarantined" # Problem task, can return to pending ``` ### AgentRole -``` -CEO → Executive (Human) -PRODUCT_OWNER → Board -HEAD_MARKETING → Board -AUDITOR → Board (Silent observer) -MAIN_PM → Management -CELL_PM → Cell management -DEVELOPER → Cell member -QA → Cell member -DOCUMENTER → Cell member +```python +CEO = "ceo" # Executive (Human) +PRODUCT_OWNER = "product_owner" # Board +HEAD_MARKETING = "head_marketing" # Board +AUDITOR = "auditor" # Board (Silent observer) +MAIN_PM = "main_pm" # Management (coordinates all cells) +CELL_PM = "cell_pm" # Cell management +DEVELOPER = "developer" # Cell member +QA = "qa" # Cell member +DOCUMENTER = "documenter" # Cell member ``` ### Team -``` -BACKEND → Backend cell -FRONTEND → Frontend cell -UX_UI → UX/UI cell -BOARD → Board level (no cell) +```python +BACKEND = "backend" # Backend cell +FRONTEND = "frontend" # Frontend cell +UX_UI = "ux_ui" # UX/UI cell +BOARD = "board" # Board level (no cell) ``` -### MessageType -``` -REASONING → Agent's thought process -DIALOGUE → Agent-to-agent conversation -DECISION → Choice made during work -ACTION → Observable work progress -BLOCKER → Impediment identified -TECHNICAL → Code explanations +### WorkSessionStatus (from `work_session.py`) +```python +ACTIVE = "active" # Work in progress +COMPLETED = "completed" # PR merged +ABANDONED = "abandoned" # Session cancelled ``` -### NotificationType +### TaskType (from `base.py`) +```python +CODE = "code" # Technical work - requires git workflow +DOCUMENTATION = "documentation" # May or may not need git +RESEARCH = "research" # Investigation/analysis - no git +PLANNING = "planning" # Planning/design tasks - no git +DESIGN = "design" # UX/UI design tasks - no git +ADMINISTRATIVE = "administrative" # Administrative tasks - no git ``` -TASK_ASSIGNMENT → New task assigned -PRIORITY_CHANGE → Task priority changed -BLOCKER_ESCALATION → Blocker needs resolution -REVIEW_REQUEST → Ready for QA -DOCUMENTATION_REQUEST → Ready for docs -ALERT → Urgent attention needed -BROADCAST → Company-wide announcement + +### BranchReason (from `project.py`) +```python +FEATURE = "feature" # New functionality +BUG = "bug" # Bug fixes +CHORE = "chore" # Maintenance +DOCS = "docs" # Documentation +HOTFIX = "hotfix" # Emergency fixes ``` +## Key Models + +### Task (`task.py`) +```python +class Task: + id: UUID + title: str + description: str + acceptance_criteria: list[str] + status: TaskStatus + team: Team + created_by: UUID + assigned_to: UUID | None + + # Task Type & Git Configuration + task_type: TaskType # code, documentation, research, planning, design, administrative + requires_git: bool # Whether git workflow applies + + # Project & Branch (set by PM during setup) + project_id: UUID | None + branch_name: str | None + work_session_id: UUID | None + + # PR Tracking (set during AWAITING_DOCUMENTATION parallel phase) + pr_number: int | None # GitHub/GitLab PR number + pr_url: str | None # Full URL to PR + + # Parallel Execution Tracking (for AWAITING_DOCUMENTATION phase) + docs_complete: bool # Documenter has finished + pr_created: bool # Developer has created PR + + # PM Approval Tracking + pm_approvals: dict[str, bool] # {'main_pm': True, 'cell_pm': True} + + # Planning + plan: TaskPlan | None + estimated_complexity: Complexity + + # Execution tracking + commits: list[CommitRef] # Linked git commits + checkpoints: list[Checkpoint] # Recovery points + progress_updates: list[ProgressUpdate] + + # Documentation Notes + dev_notes: str | None # Journey notes from developer + qa_notes: str | None # QA feedback + auditor_notes: str | None # Auditor observations + quick_context: str | None # 2-3 sentences for quick context restoration + + # Proactive Knowledge Context (injected when task is claimed) + proactive_context: dict | None # RAG context: similar tasks, learnings, patterns +``` + +### Project (`project.py`) +```python +class Project: + id: UUID + name: str + slug: str # URL-safe identifier (e.g., 'roboco', 'roboco-panel') + git_url: str # Git repository URL + default_branch: str # e.g., "main" + protected_branches: list[str] # Cannot push directly + + # CI/CD commands + test_command: str | None # e.g., 'uv run pytest' + lint_command: str | None # e.g., 'uv run ruff check .' + format_command: str | None # e.g., 'uv run ruff format .' + typecheck_command: str | None # e.g., 'uv run mypy src/' + build_command: str | None # e.g., 'pnpm build' + + # Access control + assigned_cell: Team + allowed_agents: list[UUID] | None # None = all agents in cell + + # Runtime State (managed by workspace service) + workspace_path: str | None # Legacy: now use WorkspaceService + last_synced_at: datetime | None + head_commit: str | None + + # Metadata + created_by: UUID + is_active: bool +``` + +### WorkSession (`work_session.py`) +```python +class WorkSession: + id: UUID + project_id: UUID + task_id: UUID + agent_id: UUID + + # Branch management + branch_name: str + base_branch: str + target_branch: str + + # Audit trail + commits: list[str] # Commit SHAs + files_modified: list[str] # Changed files + + # PR tracking + pr_number: int | None + pr_url: str | None + pr_status: str | None # open, merged, closed + pr_created_at: datetime | None + pr_merged_at: datetime | None + merged_by: UUID | None + + status: WorkSessionStatus +``` + +## Database Mapping + +These Pydantic models are mirrored in SQLAlchemy tables at `roboco/db/tables.py`: + +| Pydantic Model | SQLAlchemy Table | +|----------------|------------------| +| `Task` | `TaskTable` | +| `Agent` | `AgentTable` | +| `Project` | `ProjectTable` | +| `WorkSession` | `WorkSessionTable` | +| `Session` | `SessionTable` | +| `Message` | `MessageTable` | +| `Channel` | `ChannelTable` | +| `Group` | `GroupTable` | +| `Notification` | `NotificationTable` | +| `JournalEntry` | `JournalEntryTable` | + ## Usage Examples ### Creating a Task ```python -from roboco.models import Task, TaskCreate, Team, Complexity -from uuid import uuid4 +from roboco.models.task import TaskCreate +from roboco.models.base import Team, Complexity -# Create via schema task_data = TaskCreate( title="Implement rate limiting", description="Add rate limiting to auth endpoints", acceptance_criteria=[ "Rate limit of 5 attempts per minute", "Return 429 on limit exceeded", - "Use Redis for distributed counting", ], team=Team.BACKEND, priority=1, estimated_complexity=Complexity.MEDIUM, ) - -# Create full task -task = Task( - **task_data.model_dump(), - created_by=uuid4(), -) - -# Use lifecycle methods -task.claim(agent_id=uuid4()) -task.start() -task.add_progress(agent_id=task.assigned_to, message="Working on Redis integration", percentage=25) -task.add_commit(hash="abc1234", message="feat(auth): add rate limiting", agent_id=task.assigned_to) ``` -### Creating an Agent +### Creating a Project ```python -from roboco.models import Agent, AgentCreate, AgentRole, Team, ModelConfig +from roboco.models.project import ProjectCreate +from roboco.models.base import Team -agent = Agent( - name="Backend Developer 1", - slug="be-dev-1", - role=AgentRole.DEVELOPER, - team=Team.BACKEND, - model=ModelConfig( - provider="anthropic", - name="claude-3-opus", - fallback="local-llama-70b", - ), - system_prompt="You are a senior backend developer...", - capabilities=["code_execution", "git_operations", "file_management"], -) - -agent.go_online() -agent.assign_task(task_id=task.id) -``` - -### Creating a Notification -```python -from roboco.models.notification import create_task_assignment, NotificationPriority - -notification = create_task_assignment( - from_pm=pm_id, - to_agent=developer_id, - task_id=task.id, - task_title=task.title, - priority=NotificationPriority.HIGH, -) - -# Recipients acknowledge -notification.acknowledge(developer_id) -``` - -### Creating a Journal Entry -```python -from roboco.models.journal import create_task_reflection - -entry = create_task_reflection( - journal_id=agent.journal_id, - task_id=task.id, - title="Rate Limiting Implementation", - what_done="Implemented sliding window rate limiting with Redis", - what_learned="Redis MULTI/EXEC is essential for atomic operations", - what_struggled="Getting the window calculation right", - next_steps=["Add configuration options", "Write integration tests"], - tags=["redis", "rate-limiting", "auth"], +project = ProjectCreate( + name="RoboCo API", + slug="roboco", + git_url="git@github.com:org/roboco.git", + default_branch="main", + assigned_cell=Team.BACKEND, + test_command="uv run pytest", + lint_command="uv run ruff check .", ) ``` @@ -186,26 +321,12 @@ entry = create_task_reflection( All models use Pydantic v2 with strict validation: - Type checking enforced -- Field constraints validated -- Extra fields forbidden +- Field constraints validated (min/max length, patterns) +- Extra fields forbidden by default - Enum values used in serialization -## Extending Models +## Related Documentation -When adding new models: - -1. Create in appropriate file or new file -2. Inherit from `RobocoBase` or `TimestampMixin` -3. Add Create/Update schemas for API use -4. Export in `__init__.py` -5. Add factory functions for common patterns - -## Database Considerations - -These are Pydantic models for validation and serialization. For database persistence: - -- PostgreSQL via SQLAlchemy (to be implemented) -- Redis for sessions and caching -- Qdrant for embeddings (vector fields) - -The `embedding` fields are `list[float]` in Pydantic but will map to vector types in the database. +- Task lifecycle: `docs/architecture/task_lifecycle.md` +- Data model: `docs/architecture/data_model.md` +- API overview: `docs/architecture/api_overview.md`