Adjusted documentation

2026-08-03 07:23:24 +02:00 · 2025-12-30 19:37:03 +01:00
parent d7e93ece25
commit eedf06d18a
12 changed files with 3056 additions and 482 deletions
@@ -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
@@ -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

@@ -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
@@ -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: <uuid or slug>
+X-Agent-Role: <role>
+X-Agent-Team: <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.
@@ -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`
@@ -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) |
@@ -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
@@ -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
@@ -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.
@@ -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) |
@@ -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
@@ -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`