NOW RAG is actually usable... might switch to gemma3:4b from glm-4.6 cloud for expenses reasons but we'll see

docs/rag/README.md

@@ -0,0 +1,31 @@
+# RAG Knowledge Base Documentation
+
+Optimized documentation for the RoboCo AI agent knowledge base. Each file is sized for effective RAG chunking.
+
+## Structure
+
+```
+docs/rag/
+├── roles/           # Agent role responsibilities
+├── workflows/       # Step-by-step task flows
+├── standards/       # Coding, security, testing rules
+├── architecture/    # System components
+├── tools/           # MCP tools reference
+└── troubleshooting/ # Common issues and fixes
+```
+
+## Organization Principles
+
+1. **One topic per file** - Each file covers a single concept
+2. **Chunk-friendly** - Content fits in 512-1536 token chunks
+3. **Self-contained** - Each file provides complete context
+4. **Actionable** - Focus on what agents need to DO
+
+## For Agents
+
+When searching the knowledge base:
+- Use `roboco_kb_search()` for semantic search
+- Use `roboco_rag_query()` for AI-synthesized answers
+- Use `roboco_ask_mentor()` for conversational help
+
+See `/docs/workflows/KNOWLEDGE_BASE.md` for full KB tool reference.

docs/rag/architecture/agent-model.md

@@ -0,0 +1,72 @@
+# Agent Model
+
+## Core Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `name` | String | Display name |
+| `slug` | String | URL-safe ID (e.g., `be-dev-1`) |
+| `role` | Enum | Agent role |
+| `team` | Enum | Team affiliation |
+| `status` | Enum | active, idle, offline |
+
+## Roles
+
+| Role | Description |
+|------|-------------|
+| `ceo` | Human executive |
+| `product_owner` | Product strategy |
+| `head_marketing` | External comms |
+| `auditor` | Silent observer |
+| `main_pm` | Coordinates all cells |
+| `cell_pm` | Manages one cell |
+| `developer` | Writes code |
+| `qa` | Reviews and tests |
+| `documenter` | Writes documentation |
+| `system` | Internal orchestrator |
+
+## Teams
+
+| Team | Agents |
+|------|--------|
+| `backend` | be-pm, be-dev-*, be-qa, be-doc |
+| `frontend` | fe-pm, fe-dev-*, fe-qa, fe-doc |
+| `ux_ui` | ux-pm, ux-dev-*, ux-qa, ux-doc |
+| `main_pm` | main-pm |
+| `board` | product-owner, head-marketing, auditor |
+| `marketing` | head-marketing |
+
+## Status
+
+| Status | Meaning |
+|--------|---------|
+| `active` | Currently working |
+| `idle` | Available for work |
+| `offline` | Not available |
+
+## Capabilities
+
+Example capabilities:
+- `code_execution`
+- `git_operations`
+- `documentation`
+- `testing`
+
+## Model Configuration
+
+Stored in `model_config` JSON:
+- LLM provider
+- Model name
+- Temperature
+- Other settings
+
+## Agent-Specific Fields
+
+| Field | Description |
+|-------|-------------|
+| `current_task_id` | Currently assigned task |
+| `journal_id` | Personal journal |
+| `system_prompt` | Base prompt |
+| `permissions` | Channel access |
+| `metrics` | Performance data |

docs/rag/architecture/channels.md

@@ -0,0 +1,70 @@
+# Channel Structure
+
+## Channel Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `cell` | Internal team | #backend-cell |
+| `cross_cell` | Role coordination | #dev-all, #qa-all |
+| `management` | PM/Board | #main-pm-board |
+| `special` | Announcements | #all-hands |
+
+## Cell Channels
+
+| Channel | Members |
+|---------|---------|
+| #backend-cell | be-pm, be-dev-*, be-qa, be-doc |
+| #frontend-cell | fe-pm, fe-dev-*, fe-qa, fe-doc |
+| #uxui-cell | ux-pm, ux-dev-*, ux-qa, ux-doc |
+
+## Cross-Cell Channels
+
+| Channel | Members |
+|---------|---------|
+| #dev-all | All developers |
+| #qa-all | All QAs |
+| #pm-all | All PMs |
+| #doc-all | All documenters |
+
+## Management Channels
+
+| Channel | Members |
+|---------|---------|
+| #main-pm-board | Main PM, Board |
+| #board-private | Board only |
+
+## Special Channels
+
+| Channel | Access |
+|---------|--------|
+| #announcements | Read: all, Write: PM/Board |
+| #all-hands | Read/Write: all |
+
+## Auditor Access
+
+Auditor has **silent read access** to ALL channels:
+- Does not appear in member lists
+- Cannot send messages
+- Observes all activity
+
+## Channel Access Rules
+
+| Role | Own Cell | Cross-Cell | Management |
+|------|----------|------------|------------|
+| Developer | Read/Write | Read/Write | - |
+| QA | Read/Write | Read/Write | - |
+| Documenter | Read/Write | Read/Write | - |
+| Cell PM | Read/Write | Read/Write | - |
+| Main PM | Read/Write | Read/Write | Read/Write |
+| Board | - | - | Read/Write |
+| Auditor | Silent Read | Silent Read | Silent Read |
+
+## Messaging
+
+```python
+roboco_message_send({
+    channel: "backend-cell",
+    content: "Starting work on rate limiting",
+    task_id: task_id
+})
+```

docs/rag/architecture/org-structure.md

@@ -0,0 +1,71 @@
+# Organizational Structure
+
+## Hierarchy
+
+```
+CEO (Renzo - Human)
+    |
+    +-- Board (3 agents)
+         +-- Product Owner
+         +-- Head of Marketing
+         +-- Auditor (silent observer)
+              |
+              +-- Main PM
+                   |
+                   +-- Backend Cell
+                   +-- Frontend Cell
+                   +-- UX/UI Cell
+```
+
+## Agent Count
+
+| Role | Count |
+|------|-------|
+| CEO | 1 (human) |
+| Product Owner | 1 |
+| Head of Marketing | 1 |
+| Auditor | 1 |
+| Main PM | 1 |
+| Cell PMs | 3 |
+| Developers | 6 (2 per cell) |
+| QAs | 3 (1 per cell) |
+| Documenters | 3 (1 per cell) |
+| **Total** | **20** (19 AI + 1 human) |
+
+## Cells
+
+| Cell | PM | Developers | QA | Documenter |
+|------|-----|------------|-----|------------|
+| Backend | be-pm | be-dev-1, be-dev-2 | be-qa | be-doc |
+| Frontend | fe-pm | fe-dev-1, fe-dev-2 | fe-qa | fe-doc |
+| UX/UI | ux-pm | ux-dev-1, ux-dev-2 | ux-qa | ux-doc |
+
+## Teams
+
+| Team | Members |
+|------|---------|
+| executive | ceo |
+| board | product-owner, head-marketing, auditor |
+| management | main-pm, be-pm, fe-pm, ux-pm |
+| developers | all devs |
+| qa | all QAs |
+| documentation | all documenters |
+
+## Escalation Chain
+
+```
+Developer/QA/Documenter → Cell PM → Main PM → Product Owner → CEO
+```
+
+## Communication
+
+Each role can communicate with:
+
+| Role | Can Communicate With |
+|------|---------------------|
+| CEO | Everyone |
+| Board | CEO, other board, Main PM |
+| Auditor | Everyone (silent read all) |
+| Main PM | CEO, Board, Cell PMs |
+| Cell PM | Main PM, cell members |
+| Cell Members | Cell PM, other cell members |

docs/rag/architecture/task-model.md

@@ -0,0 +1,72 @@
+# Task Model
+
+## Core Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `title` | String | Task title |
+| `description` | Text | Detailed description |
+| `acceptance_criteria` | Array | How we know it's done |
+| `status` | Enum | Lifecycle state |
+| `priority` | Int | 0=P0 (highest) to 3=P3 |
+| `team` | Enum | backend, frontend, ux_ui |
+
+## Task Types
+
+| Type | Description |
+|------|-------------|
+| `code` | Development work |
+| `documentation` | Writing docs |
+| `research` | Investigation |
+| `planning` | Task breakdown |
+| `design` | UX/UI design |
+| `administrative` | Admin work |
+
+## Git Fields
+
+| Field | Description |
+|-------|-------------|
+| `requires_git` | Whether git workflow applies |
+| `project_id` | Associated project |
+| `branch_name` | Git branch for task |
+| `work_session_id` | Active work session |
+| `pr_number` | PR number |
+| `pr_url` | Full PR URL |
+| `docs_complete` | Documenter finished |
+| `pr_created` | Developer created PR |
+| `commits` | Linked commits |
+
+## Assignment Fields
+
+| Field | Description |
+|-------|-------------|
+| `created_by` | Agent who created |
+| `assigned_to` | Currently assigned |
+| `parent_task_id` | Parent for subtasks |
+| `dependency_ids` | Blocking tasks |
+
+## Context Fields
+
+| Field | Description |
+|-------|-------------|
+| `plan` | Implementation plan |
+| `quick_context` | 2-3 sentence summary |
+| `proactive_context` | RAG context at claim |
+| `dev_notes` | Developer notes |
+| `qa_notes` | QA feedback |
+
+## Timestamps
+
+| Field | Description |
+|-------|-------------|
+| `claimed_at` | When claimed |
+| `started_at` | When started |
+| `completed_at` | When completed |
+| `target_date` | Target date |
+
+## Indexes
+
+- `ix_tasks_team_status` - Team + Status queries
+- `ix_tasks_assigned_status` - Assignee + Status
+- `ix_tasks_project_status` - Project + Status

docs/rag/architecture/workspaces.md

@@ -0,0 +1,71 @@
+# Workspace Structure
+
+## Multi-Agent Isolation
+
+Each agent gets their own git clone:
+
+```
+{workspaces_root}/
+└── {project-slug}/
+    └── {team}/
+        └── {agent-slug}/
+            └── [git repo files]
+```
+
+## Example
+
+```
+/data/workspaces/
+└── roboco/
+    ├── backend/
+    │   ├── be-dev-1/    # be-dev-1's workspace
+    │   ├── be-dev-2/    # be-dev-2's workspace
+    │   ├── be-qa/       # be-qa's workspace
+    │   ├── be-pm/       # be-pm's workspace
+    │   └── be-doc/      # be-doc's workspace
+    ├── frontend/
+    │   ├── fe-dev-1/
+    │   └── ...
+    └── ux_ui/
+        └── ...
+```
+
+## Configuration
+
+```bash
+# Environment variables
+ROBOCO_WORKSPACES_ROOT=/data/workspaces
+ROBOCO_WORKSPACE_AUTO_CLONE=true
+ROBOCO_WORKSPACE_CLONE_TIMEOUT=300
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Auto-clone | Workspaces created on first access |
+| Isolation | No file locking conflicts |
+| Branch independence | Agents on different branches |
+| Project-scoped | Organized by project slug |
+
+## Benefits
+
+1. **Parallel Development**: Multiple agents on same project
+2. **No Conflicts**: Each has own working tree
+3. **Branch Flexibility**: Different branches simultaneously
+4. **Clean State**: Fresh clone if needed
+
+## Workspace Resolution
+
+When agent needs workspace:
+
+```python
+# Service resolves path
+workspace_path = await workspace_service.get_workspace(
+    project_slug="roboco",
+    agent_id="be-dev-1"
+)
+# Returns: /data/workspaces/roboco/backend/be-dev-1
+```
+
+If `auto_clone=True` and workspace doesn't exist, it's created automatically.

docs/rag/roles/auditor.md

@@ -0,0 +1,85 @@
+# Auditor Role
+
+## Identity
+
+- **Agent**: auditor
+- **Role**: `auditor`
+- **Team**: board
+- **Reports to**: CEO
+
+## Core Responsibilities
+
+1. Silent observation of all work
+2. Quality oversight
+3. Report issues to CEO
+4. No interference with workflow
+
+## What You CAN Do
+
+- View ALL tasks (organization-wide)
+- View ALL channels (silent observer)
+- Search and query knowledge base
+- View KB statistics
+- Create tasks (for reporting findings)
+- Assign tasks (to escalate issues)
+
+## What You CANNOT Do
+
+- Claim tasks
+- Update tasks
+- Clear KB indexes
+- Write to most channels (silent observer)
+- Cancel tasks
+
+## Silent Observer Mode
+
+The Auditor has **silent read access** to all channels:
+- Can read all channel history
+- Does NOT appear in member lists
+- Cannot send messages (except to CEO)
+- Observations logged privately
+
+## Observation Areas
+
+Monitor for:
+- Quality standards violations
+- Security issues
+- Process deviations
+- Unusual patterns
+- Bottlenecks
+
+## Reporting to CEO
+
+When issues found:
+```python
+# Create task for CEO attention
+roboco_task_create({
+    title: "Audit Finding: [Issue]",
+    description: "Details of finding",
+    team: "board",
+    assigned_to: "ceo"
+})
+```
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_task_scan` | View all tasks |
+| `roboco_channel_history` | Read any channel |
+| `roboco_kb_stats` | View KB metrics |
+| `roboco_journal_read_team` | Read any journal |
+
+## Communication
+
+The Auditor primarily observes and reports. Direct intervention is NOT the Auditor's role - issues are escalated to CEO for action.
+
+## Escalation
+
+Report directly to CEO when:
+- Critical quality issue found
+- Security violation detected
+- Process breakdown observed
+- Systemic pattern identified
+
+Tool: `roboco_task_escalate(task_id, reason)`

docs/rag/roles/cell-pm.md

@@ -0,0 +1,131 @@
+# Cell PM Role
+
+## Identity
+
+- **Agents**: be-pm, fe-pm, ux-pm
+- **Role**: `cell_pm`
+- **Teams**: backend, frontend, ux_ui
+- **Reports to**: Main PM (main-pm)
+
+## Core Responsibilities
+
+1. Create and manage tasks for cell
+2. Activate tasks (backlog → pending)
+3. Assign work to cell members
+4. Complete tasks after full workflow
+5. Handle escalations from cell
+6. Create branches for git tasks
+
+## What You CAN Do
+
+- Create tasks in `backlog` status
+- Activate tasks (`backlog` → `pending`)
+- Assign tasks to cell members
+- Complete `awaiting_pm_review` tasks
+- Cancel any task in cell
+- Unblock blocked tasks
+- Send notifications
+- Index code and documentation
+- Create branches: `roboco_git_create_branch()`
+
+## What You CANNOT Do
+
+- Access other cells' tasks (Main PM only)
+- Clear/refresh KB indexes (Main PM/CEO only)
+- Pass/fail QA (QA only)
+- Complete documentation (Documenter only)
+
+## Task Creation Flow
+
+```python
+# 1. Create task in backlog
+roboco_task_create({
+    title: "Implement rate limiting",
+    description: "Add Redis-based rate limiter",
+    team: "backend",
+    status: "backlog",
+    assigned_to: "be-dev-1"  # Optional pre-assign
+})
+
+# 2. Activate when ready
+roboco_task_activate(task_id)  # backlog → pending
+
+# 3. Notify developer
+roboco_notify_send({
+    recipient: "be-dev-1",
+    type: "task_assignment",
+    task_id: task_id
+})
+```
+
+## Git Tasks
+
+For tasks with `requires_git=True`:
+
+```python
+# Create branch BEFORE developer can start
+roboco_git_create_branch(
+    project_slug="roboco",
+    task_id=task_id,
+    branch_type="feature"
+)
+# Creates: feature/backend/a1b2c3d4
+```
+
+Developer cannot start (`claimed` → `in_progress`) until branch exists.
+
+## Completing Tasks
+
+After QA passes, docs complete, and PR created:
+
+```python
+# Review and complete
+roboco_task_complete(task_id)
+
+# Or escalate major tasks to CEO
+roboco_task_escalate_to_ceo(task_id, notes)
+```
+
+## Monitoring Cell
+
+```python
+# Scan for tasks needing attention
+roboco_task_scan(team="backend")
+
+# Check notifications
+roboco_notify_list()
+
+# Read team journals
+roboco_journal_read_team("be-dev-1", task_id=task_id)
+```
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_task_create` | Create new task |
+| `roboco_task_activate` | backlog → pending |
+| `roboco_task_complete` | Finish task |
+| `roboco_task_cancel` | Cancel task |
+| `roboco_task_unblock` | Unblock blocked task |
+| `roboco_git_create_branch` | Create task branch |
+| `roboco_notify_send` | Send notification |
+
+## Handling Escalations
+
+When receiving escalation:
+1. ACK notification: `roboco_notify_ack(notification_id)`
+2. Investigate: Read task, journals, messages
+3. Decide or escalate to Main PM
+4. Communicate decision
+5. Unblock if needed: `roboco_task_unblock(task_id)`
+
+## Escalation
+
+Escalate to Main PM when:
+- Cross-cell coordination needed
+- Resource conflict
+- Priority conflict
+- Scope change beyond cell
+
+Tool: `roboco_task_escalate(task_id, reason)`

docs/rag/roles/ceo.md

@@ -0,0 +1,71 @@
+# CEO Role
+
+## Identity
+
+- **Agent**: ceo (Renzo - Human)
+- **Role**: `ceo`
+- **Team**: executive
+- **Reports to**: N/A (top of hierarchy)
+
+## Core Responsibilities
+
+1. Final authority on major decisions
+2. Approve major task completions
+3. Set strategic direction
+4. Oversee entire organization
+
+## What You CAN Do
+
+- View ALL tasks organization-wide
+- Approve/reject tasks in `awaiting_ceo_approval`
+- Force complete tasks with cancelled subtasks
+- Send notifications to anyone
+- Full access to all channels
+
+## What You CANNOT Do
+
+- Cancel tasks (by design - CEO observes/approves, doesn't manage)
+- Should not be doing day-to-day task management
+
+## CEO Approval Workflow
+
+When PM escalates major task:
+
+```python
+# Task arrives in awaiting_ceo_approval
+# CEO reviews and decides:
+
+# Approve and complete
+roboco_task_ceo_approve(task_id, notes="Approved. Great work!")
+
+# Reject and send back
+roboco_task_ceo_reject(task_id, notes="Need to address X before merge")
+```
+
+## Force Completion
+
+When subtasks are cancelled but parent should complete:
+
+```python
+roboco_task_complete(
+    task_id,
+    force_with_cancelled=True,
+    justification="Subtask no longer needed"
+)
+```
+
+Only CEO can use `force_with_cancelled`.
+
+## Escalation
+
+CEO is the final escalation target. Issues escalate:
+```
+Developer → Cell PM → Main PM → Product Owner → CEO
+```
+
+## Communication
+
+CEO has access to all channels including:
+- #board-private
+- #announcements (write)
+- All cell and cross-cell channels

docs/rag/roles/developer.md

@@ -0,0 +1,78 @@
+# Developer Role
+
+## Identity
+
+- **Agents**: be-dev-1, be-dev-2, fe-dev-1, fe-dev-2, ux-dev-1, ux-dev-2
+- **Role**: `developer`
+- **Teams**: backend, frontend, ux_ui
+- **Reports to**: Cell PM (be-pm, fe-pm, ux-pm)
+
+## Core Responsibilities
+
+1. Claim and complete coding tasks
+2. Write quality code that passes QA
+3. Create commits linked to tasks
+4. Submit work for verification and QA
+5. Journal decisions and learnings
+
+## What You CAN Do
+
+- Claim tasks in `pending` or `needs_revision` status
+- Start, pause, resume work on claimed tasks
+- Submit for verification (`verifying`) and QA (`awaiting_qa`)
+- Block tasks when waiting on dependencies
+- Index code and documentation
+- Search and query knowledge base
+- Create commits with `roboco_git_commit()`
+
+## What You CANNOT Do
+
+- Create or assign tasks (PM only)
+- Pass or fail QA (QA only)
+- Complete tasks (PM only)
+- Cancel tasks
+- Send notifications
+
+## Task Flow
+
+```
+pending → claim → start → work → submit_verification → submit_qa
+                    ↑                                      ↓
+                    └──────── needs_revision ←──── (QA fails)
+```
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_task_claim` | Take ownership of a task |
+| `roboco_task_start` | Begin work (status: in_progress) |
+| `roboco_git_commit` | Commit with task ID prefix |
+| `roboco_task_submit_qa` | Submit for QA review |
+| `roboco_journal_entry` | Log progress and decisions |
+| `roboco_kb_search` | Search knowledge base |
+
+## Before Starting Any Task
+
+1. Search KB for similar past work: `roboco_kb_search()`
+2. Read proactive context: `roboco_get_proactive_context()`
+3. Check standards: `roboco_get_standards(domain="coding")`
+4. Announce to cell channel: `roboco_message_send()`
+
+## Before Submitting to QA
+
+1. Run tests: `uv run pytest` (backend) or `pnpm test` (frontend)
+2. Run linter: `uv run ruff check .` or `pnpm lint`
+3. Run type check: `uv run mypy roboco/` or `pnpm typecheck`
+4. Write journal reflection: `roboco_journal_reflect()`
+5. Push branch: `roboco_git_push()`
+
+## Escalation
+
+Escalate to Cell PM when:
+- Requirements are unclear
+- Blocked by external factor
+- Scope question arises
+- Need architectural decision
+
+Tool: `roboco_task_escalate(task_id, reason)`

docs/rag/roles/documenter.md

@@ -0,0 +1,119 @@
+# Documenter Role
+
+## Identity
+
+- **Agents**: be-doc, fe-doc, ux-doc
+- **Role**: `documenter`
+- **Teams**: backend, frontend, ux_ui
+- **Reports to**: Cell PM (be-pm, fe-pm, ux-pm)
+
+## Core Responsibilities
+
+1. Create documentation from developer work
+2. Write API docs, usage examples, architecture notes
+3. Index documentation for knowledge base
+4. Ensure future developers can understand the work
+
+## What You CAN Do
+
+- Claim tasks in `awaiting_documentation` status
+- Claim `pending` tasks (direct documentation tasks from PM)
+- Complete documentation (`docs_complete`)
+- Index documentation: `roboco_kb_index_docs()`
+- Search and query knowledge base
+
+## What You CANNOT Do
+
+- Claim developer tasks
+- Index code (developer/PM only)
+- Create or assign tasks (PM only)
+- Pass or fail QA (QA only)
+- Cancel tasks
+- Send notifications
+- Complete tasks (only submits for PM review)
+- Document your own development work (self-documentation prevention)
+
+## Task Flow
+
+```
+awaiting_documentation → claim → start → write → docs_complete
+                                                       ↓
+                                              awaiting_pm_review
+```
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_task_claim` | Take ownership |
+| `roboco_task_start` | Begin documentation |
+| `roboco_task_docs_complete` | Submit for PM review |
+| `roboco_journal_read_team` | Read developer's journey |
+| `roboco_kb_index_docs` | Index new documentation |
+
+## Gather Context First
+
+Before writing documentation:
+
+```python
+# Read developer's journey (REQUIRED)
+roboco_journal_read_team(original_developer, task_id=task_id)
+
+# Check existing docs
+roboco_kb_search("similar documentation")
+
+# Read channel discussions
+roboco_channel_history("backend-cell")
+```
+
+## Documentation Deliverables
+
+Depending on task, create:
+- API documentation
+- Usage examples with code snippets
+- Architecture notes
+- README updates
+- Changelog entries
+
+## Completing Documentation
+
+```python
+roboco_task_docs_complete(task_id)
+```
+
+This:
+- Sets `docs_complete=True` on task
+- Advances to `awaiting_pm_review` (if PR also created)
+- Sends notification to PM
+
+## Parallel Execution
+
+In `awaiting_documentation`, two things happen in parallel:
+
+| Agent | Action | Flag Set |
+|-------|--------|----------|
+| Documenter | Write docs | `docs_complete=True` |
+| Developer | Create PR | `pr_created=True` |
+
+Task advances to `awaiting_pm_review` only when BOTH are done.
+
+## Self-Documentation Prevention
+
+System enforces: Documenter cannot document tasks they originally developed.
+
+If documenter == original_developer, the claim is FORBIDDEN.
+
+## Before Completing
+
+1. Journal your work: `roboco_journal_entry({type: "documentation"})`
+2. Write reflection: `roboco_journal_reflect()`
+3. Index new docs: `roboco_kb_index_docs(["docs/new-feature.md"])`
+
+## Escalation
+
+Escalate to Cell PM when:
+- Missing context from developer
+- Scope unclear
+- Cannot access code changes
+
+Tool: `roboco_task_escalate(task_id, reason)`

docs/rag/roles/head-marketing.md

@@ -0,0 +1,60 @@
+# Head of Marketing Role
+
+## Identity
+
+- **Agent**: head-marketing
+- **Role**: `head_marketing`
+- **Team**: board
+- **Reports to**: CEO
+
+## Core Responsibilities
+
+1. Marketing and external communications
+2. Market analysis and context
+3. Support product positioning
+
+## What You CAN Do
+
+- View ALL tasks organization-wide
+- Create and assign tasks
+- Cancel tasks
+- Send notifications
+- Index documentation
+- Access management channels
+
+## What You CANNOT Do
+
+- Claim tasks (board observes/approves)
+- Clear/refresh KB indexes
+
+## Key Permissions
+
+| Permission | Access |
+|------------|--------|
+| VIEW_ALL tasks | Yes |
+| CREATE tasks | Yes |
+| ASSIGN tasks | Yes |
+| CANCEL tasks | Yes |
+| CLOSE tasks | Yes |
+| INDEX_DOCS | Yes |
+
+## Escalation
+
+Escalates directly to CEO.
+
+```
+Head Marketing → CEO
+```
+
+## A2A Skills
+
+- **Market Analysis**: Provide market context and analysis
+
+## Communication
+
+Access to:
+- #main-pm-board
+- #board-private
+- #announcements (write)
+
+Can notify: Main PM, Product Owner, Auditor, CEO

docs/rag/roles/main-pm.md

@@ -0,0 +1,108 @@
+# Main PM Role
+
+## Identity
+
+- **Agent**: main-pm
+- **Role**: `main_pm`
+- **Team**: main_pm
+- **Reports to**: Product Owner
+
+## Core Responsibilities
+
+1. Coordinate work across all cells
+2. Break down initiatives into cell tasks
+3. Handle cross-cell dependencies
+4. Monitor organization-wide progress
+5. Escalate to Board when needed
+
+## What You CAN Do
+
+Everything Cell PM can do, PLUS:
+- Access ALL cells' tasks
+- Clear and refresh KB indexes
+- Coordinate cross-cell work
+- Create sessions for initiatives
+
+## Task Breakdown Flow
+
+When receiving work from Board/CEO:
+
+```python
+# 1. Claim the initiative
+roboco_task_claim(initiative_id)
+roboco_task_start(initiative_id)
+
+# 2. Plan and document
+roboco_task_plan(initiative_id, approach, steps)
+roboco_journal_decision({
+    title: "Task breakdown for [feature]",
+    options: ["Option A", "Option B"],
+    chosen: "Option A",
+    rationale: "Because..."
+})
+
+# 3. Create subtasks for each cell
+roboco_task_create({
+    title: "Backend: Implement API",
+    team: "backend",
+    parent_task_id: initiative_id,
+    status: "backlog",
+    assigned_to: "be-pm"
+})
+
+# 4. Create session for coordination
+roboco_session_create_for_tasks({
+    title: "Feature X Implementation",
+    task_ids: [subtask_1_id, subtask_2_id]
+})
+
+# 5. Activate and notify Cell PMs
+roboco_task_activate(subtask_id)
+roboco_notify_send({
+    recipient: "be-pm",
+    type: "task_assignment",
+    task_id: subtask_id
+})
+```
+
+## Cross-Cell Coordination
+
+Monitor via:
+```python
+# Check all cells
+roboco_task_scan()  # No team filter = all teams
+
+# PM channel discussions
+roboco_channel_history("pm-all")
+
+# Read Cell PM journals
+roboco_journal_read_team("be-pm")
+roboco_journal_read_team("fe-pm")
+```
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_task_scan` | Scan all cells |
+| `roboco_kb_clear_index` | Clear KB index |
+| `roboco_reindex_all` | Trigger full reindex |
+| `roboco_session_create_for_tasks` | Group related tasks |
+
+## Handling Cell PM Escalations
+
+When Cell PM escalates:
+1. ACK immediately
+2. Review cross-cell impact
+3. Coordinate with other Cell PMs if needed
+4. Make decision or escalate to Board
+
+## Escalation
+
+Escalate to Product Owner when:
+- Strategic direction needed
+- Major scope change
+- Resource constraints
+- Cross-initiative conflicts
+
+Tool: `roboco_task_escalate(task_id, reason)`

docs/rag/roles/product-owner.md

@@ -0,0 +1,63 @@
+# Product Owner Role
+
+## Identity
+
+- **Agent**: product-owner
+- **Role**: `product_owner`
+- **Team**: board
+- **Reports to**: CEO
+
+## Core Responsibilities
+
+1. Product strategy and direction
+2. Clarify requirements
+3. Approve feature implementations
+4. Handle escalations from Main PM
+
+## What You CAN Do
+
+- View ALL tasks organization-wide
+- Create and assign tasks
+- Cancel tasks
+- Send notifications
+- Index documentation
+- Access management channels
+
+## What You CANNOT Do
+
+- Claim tasks (board observes/approves)
+- Clear/refresh KB indexes
+
+## Key Permissions
+
+| Permission | Access |
+|------------|--------|
+| VIEW_ALL tasks | Yes |
+| CREATE tasks | Yes |
+| ASSIGN tasks | Yes |
+| CANCEL tasks | Yes |
+| CLOSE tasks | Yes |
+| INDEX_DOCS | Yes |
+
+## Escalation
+
+Receives escalations from Main PM.
+Escalates to CEO for final authority.
+
+```
+Main PM → Product Owner → CEO
+```
+
+## A2A Skills
+
+- **Requirements Clarification**: Clarify product requirements and priorities
+- **Feature Approval**: Approve feature implementations
+
+## Communication
+
+Access to:
+- #main-pm-board
+- #board-private
+- #announcements (write)
+
+Can notify: Main PM, Head Marketing, Auditor, CEO

docs/rag/roles/qa.md

@@ -0,0 +1,109 @@
+# QA Role
+
+## Identity
+
+- **Agents**: be-qa, fe-qa, ux-qa
+- **Role**: `qa`
+- **Teams**: backend, frontend, ux_ui
+- **Reports to**: Cell PM (be-pm, fe-pm, ux-pm)
+
+## Core Responsibilities
+
+1. Review developer work for quality
+2. Verify acceptance criteria are met
+3. Run tests and check code quality
+4. Pass or fail QA with clear reasoning
+5. Journal review findings
+
+## What You CAN Do
+
+- Claim tasks in `awaiting_qa` status
+- Pass QA (`awaiting_qa` → `awaiting_documentation`)
+- Fail QA (`awaiting_qa` → `needs_revision`)
+- Block tasks when waiting on information
+- Search and query knowledge base
+
+## What You CANNOT Do
+
+- Claim `pending` tasks (developer only)
+- Create or assign tasks (PM only)
+- Index content
+- Complete documentation
+- Complete tasks (PM only)
+- Cancel tasks
+- Send notifications
+- Review your own development work (self-review prevention)
+
+## Task Flow
+
+```
+awaiting_qa → claim → start → review → pass/fail
+                                          ↓
+                          pass: awaiting_documentation
+                          fail: needs_revision (back to developer)
+```
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_task_claim` | Take ownership for QA |
+| `roboco_task_start` | Begin review |
+| `roboco_task_qa_pass` | Approve and advance |
+| `roboco_task_qa_fail` | Reject with issues |
+| `roboco_journal_read_team` | Read developer's journey |
+| `roboco_git_diff` | View code changes |
+
+## Review Checklist
+
+Before passing QA:
+1. Read developer's journal: `roboco_journal_read_team(developer_id, task_id=task_id)`
+2. Check acceptance criteria in task
+3. Run tests: `uv run pytest` or `pnpm test`
+4. Review code changes: `roboco_git_diff()`
+5. Verify functionality works as expected
+6. Check code quality and standards
+
+## Passing QA
+
+```python
+roboco_task_qa_pass(task_id, {
+    notes: "All acceptance criteria met. Tests pass. Code follows standards."
+})
+```
+
+## Failing QA
+
+```python
+roboco_task_qa_fail(task_id, {
+    notes: "Issues found during review",
+    issues: [
+        "Bug: Login fails with special characters in password",
+        "Missing: Error handling for timeout case"
+    ]
+})
+```
+
+Task returns to original developer with `needs_revision` status.
+
+## Self-Review Prevention
+
+System enforces: QA agent cannot review tasks they originally developed.
+
+The `original_developer` is tracked in `quick_context`. If QA agent == original developer, the claim is FORBIDDEN.
+
+## Before Making Decision
+
+1. Journal your review: `roboco_journal_entry({type: "qa_review"})`
+2. Write reflection: `roboco_journal_reflect()`
+3. Provide clear reasoning in pass/fail notes
+
+## Escalation
+
+Escalate to Cell PM when:
+- Cannot reproduce reported issue
+- Test criteria unclear
+- Critical security flaw found
+- Test environment issues
+
+Tool: `roboco_task_escalate(task_id, reason)`

docs/rag/standards/python-basics.md

@@ -0,0 +1,101 @@
+# Python Coding Standards
+
+## Package Manager
+
+Use `uv` for all Python operations.
+
+```bash
+# Add dependency
+uv add package-name
+
+# Add dev dependency
+uv add --dev package-name
+
+# Sync dependencies
+uv sync
+
+# Run command
+uv run pytest
+```
+
+## Before Every Commit
+
+```bash
+uv run ruff format .      # Format code
+uv run ruff check .       # Lint
+uv run mypy roboco/       # Type check
+uv run pytest             # Tests
+```
+
+## Type Hints Required
+
+All functions MUST have type hints:
+
+```python
+# Good
+async def fetch_user(user_id: UUID) -> User | None:
+    ...
+
+# Bad - no type hints
+def fetch_user(user_id):
+    ...
+```
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Classes | PascalCase | `TaskService` |
+| Functions | snake_case | `get_user` |
+| Variables | snake_case | `user_id` |
+| Constants | SCREAMING | `MAX_RETRIES` |
+| Private | Leading `_` | `_cache` |
+
+## Line Length
+
+Maximum 88 characters (Black default).
+
+## Imports
+
+Sorted order: stdlib, third-party, local.
+
+```python
+import asyncio
+from pathlib import Path
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+from roboco.models import Task
+from roboco.services import TaskService
+```
+
+## Async by Default
+
+ALL I/O operations must be async:
+
+```python
+# Good
+async def fetch_user(user_id: str) -> User:
+    return await db.users.get(user_id)
+
+# Bad - blocking
+def fetch_user(user_id: str) -> User:
+    return db.users.get(user_id)  # Blocks!
+```
+
+## Concurrent Operations
+
+Use `asyncio.gather` for independent async calls:
+
+```python
+# Good - parallel
+task, comments = await asyncio.gather(
+    get_task(task_id),
+    get_comments(task_id),
+)
+
+# Bad - sequential
+task = await get_task(task_id)
+comments = await get_comments(task_id)  # Waits unnecessarily
+```

docs/rag/standards/python-errors.md

@@ -0,0 +1,93 @@
+# Python Error Handling
+
+## Never Bare Except
+
+Always catch specific exceptions:
+
+```python
+# Good
+try:
+    result = await service.process(data)
+except ValidationError as e:
+    logger.warning("Validation failed", error=str(e))
+    raise
+except ServiceUnavailableError:
+    await retry_with_backoff(service.process, data)
+
+# Bad - NEVER do this
+try:
+    result = await service.process(data)
+except:
+    pass
+```
+
+## Custom Exceptions
+
+Define domain-specific exceptions:
+
+```python
+class TaskError(Exception):
+    """Base exception for task operations."""
+
+class TaskNotFoundError(TaskError):
+    """Task does not exist."""
+
+class TaskAlreadyClaimedError(TaskError):
+    """Task is already claimed."""
+
+# Usage
+if task is None:
+    raise TaskNotFoundError(f"Task {task_id} not found")
+```
+
+## Preserve Exception Chain
+
+When re-raising:
+
+```python
+# Good - preserves chain
+try:
+    result = await external_api.call()
+except ExternalAPIError as e:
+    raise ServiceError("External API failed") from e
+
+# Bad - loses traceback
+except ExternalAPIError:
+    raise ServiceError("External API failed")
+```
+
+## Structured Logging
+
+Use structlog, NEVER print:
+
+```python
+import structlog
+logger = structlog.get_logger(__name__)
+
+# Good
+logger.info(
+    "Task completed",
+    task_id=task.id,
+    duration_ms=elapsed,
+)
+
+# Bad - NEVER use print
+print(f"Task {task.id} completed")
+```
+
+## Validation at Boundaries
+
+Validate external input at API boundaries:
+
+```python
+# API boundary - validate
+@router.post("/tasks")
+async def create_task(request: TaskCreate) -> TaskResponse:
+    # Pydantic validates automatically
+    ...
+
+# Internal service - trust validated data
+async def process_task(task: Task) -> None:
+    # No need to re-validate
+    ...
+```

docs/rag/standards/python-security.md

@@ -0,0 +1,86 @@
+# Python Security Standards
+
+## No Hardcoded Secrets
+
+NEVER hardcode secrets:
+
+```python
+# Bad - NEVER
+API_KEY = "sk-abc123xyz789"
+DATABASE_URL = "postgresql://user:password@host/db"
+
+# Good - environment variables
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    api_key: str
+    database_url: str
+    model_config = {"env_prefix": "ROBOCO_"}
+```
+
+## SQL Injection Prevention
+
+NEVER use string concatenation for SQL:
+
+```python
+# Bad - SQL injection vulnerability
+query = f"SELECT * FROM users WHERE id = '{user_id}'"
+
+# Good - parameterized query
+result = await session.execute(
+    select(User).where(User.id == user_id)
+)
+```
+
+## Command Injection Prevention
+
+NEVER pass user input directly to shell:
+
+```python
+# Bad - command injection
+import os
+os.system(f"process_file {filename}")
+
+# Good - use subprocess with list
+import subprocess
+subprocess.run(["process_file", filename], check=True)
+```
+
+## No eval() or exec()
+
+NEVER use on untrusted input:
+
+```python
+# Bad - code injection
+result = eval(user_input)
+
+# Good - safe parsing
+import ast
+result = ast.literal_eval(user_input)  # Only literals
+```
+
+## Non-Security Hashes
+
+When hashing for non-security purposes:
+
+```python
+import hashlib
+
+content_hash = hashlib.md5(
+    content.encode(),
+    usedforsecurity=False  # Required flag
+).hexdigest()[:12]
+```
+
+## Security Tools
+
+Run before merge:
+
+```bash
+# Security scan
+uv run bandit -r roboco/ -ll
+
+# Dependency audit
+uv run pip-audit
+uv run safety scan
+```

docs/rag/standards/testing.md

@@ -0,0 +1,81 @@
+# Testing Standards
+
+## Coverage Target
+
+Minimum 80% code coverage for all modules.
+
+```bash
+# Run with coverage
+uv run pytest --cov=roboco --cov-report=term-missing
+```
+
+## Async Tests
+
+Use pytest-asyncio:
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_fetch_user() -> None:
+    user = await fetch_user("test-123")
+    assert user.name == "Test User"
+```
+
+## Test Structure
+
+Follow AAA pattern: Arrange, Act, Assert.
+
+```python
+@pytest.mark.asyncio
+async def test_task_claim_success() -> None:
+    # Arrange
+    task = await create_test_task(status=TaskStatus.PENDING)
+    agent = await create_test_agent()
+
+    # Act
+    claimed_task = await task_service.claim(task.id, agent.id)
+
+    # Assert
+    assert claimed_task.status == TaskStatus.CLAIMED
+    assert claimed_task.assigned_to == agent.id
+```
+
+## Test Factories
+
+Use factory-boy for test data:
+
+```python
+from factory import Factory, Faker, LazyAttribute
+
+class TaskFactory(Factory):
+    class Meta:
+        model = Task
+
+    title = Faker('sentence')
+    status = TaskStatus.PENDING
+    created_at = LazyAttribute(lambda _: datetime.now(UTC))
+```
+
+## Before Submitting to QA
+
+Run full test suite:
+
+```bash
+# Backend
+uv run pytest
+uv run ruff check .
+uv run mypy roboco/
+
+# Frontend
+pnpm test
+pnpm lint
+pnpm typecheck
+```
+
+## Quality Gates
+
+All tests MUST pass before:
+- Submitting for verification
+- Creating pull request
+- Merging to main

docs/rag/standards/typescript.md

@@ -0,0 +1,119 @@
+# TypeScript Coding Standards
+
+## Package Manager
+
+Use `pnpm` for all TypeScript/JavaScript operations.
+
+```bash
+# Install dependencies
+pnpm install
+
+# Add dependency
+pnpm add package-name
+
+# Add dev dependency
+pnpm add -D package-name
+```
+
+## Before Every Commit
+
+```bash
+pnpm format       # Format code
+pnpm lint         # Lint
+pnpm typecheck    # Type check
+pnpm test         # Tests
+```
+
+## Type Safety
+
+Enable strict mode in tsconfig:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+## Avoid `any`
+
+Never use `any`. Use `unknown` or generics:
+
+```typescript
+// Bad
+function process(data: any): any { ... }
+
+// Good
+function process<T>(data: T): ProcessedData<T> { ... }
+```
+
+## Null Checks
+
+Use optional chaining and nullish coalescing:
+
+```typescript
+// Good
+const name = user?.profile?.name ?? "Anonymous";
+
+// Bad
+const name = user && user.profile && user.profile.name || "Anonymous";
+```
+
+## Async/Await
+
+Use async/await over raw Promises:
+
+```typescript
+// Good
+async function fetchUser(id: string): Promise<User> {
+  const response = await api.get(`/users/${id}`);
+  return response.data;
+}
+
+// Bad
+function fetchUser(id: string): Promise<User> {
+  return api.get(`/users/${id}`).then(r => r.data);
+}
+```
+
+## Error Handling
+
+Use typed errors:
+
+```typescript
+class ApiError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number
+  ) {
+    super(message);
+  }
+}
+
+try {
+  await api.call();
+} catch (error) {
+  if (error instanceof ApiError) {
+    // Handle API error
+  }
+  throw error;
+}
+```
+
+## Component Props
+
+Define explicit prop types:
+
+```typescript
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+}
+
+export function Button({ label, onClick, disabled }: ButtonProps) {
+  // ...
+}
+```

docs/rag/tools/git-tools.md

@@ -0,0 +1,94 @@
+# Git Tools
+
+## Read Operations
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_git_status` | View working tree status |
+| `roboco_git_log` | View commit history |
+| `roboco_git_branch_list` | List branches |
+| `roboco_git_diff` | View changes |
+
+## Status and Diff
+
+```python
+# Check status
+status = roboco_git_status(project_slug="roboco")
+
+# View changes
+diff = roboco_git_diff(project_slug="roboco")
+
+# View history
+log = roboco_git_log(
+    project_slug="roboco",
+    branch="feature/backend/a1b2c3d4"
+)
+```
+
+## Branch Operations
+
+```python
+# List branches
+branches = roboco_git_branch_list(project_slug="roboco")
+
+# Create branch (PM only)
+roboco_git_create_branch(
+    project_slug="roboco",
+    task_id=task_id,
+    branch_type="feature"  # feature, fix, refactor, docs
+)
+# Creates: feature/backend/a1b2c3d4
+
+# Checkout branch
+roboco_git_checkout(
+    project_slug="roboco",
+    branch="feature/backend/a1b2c3d4"
+)
+```
+
+## Commit and Push
+
+```python
+# Commit with task link
+roboco_git_commit(
+    project_slug="roboco",
+    task_id=task_id,
+    message="Add rate limiting endpoint"
+)
+# Creates: [a1b2c3d4] Add rate limiting endpoint
+
+# Push to remote
+roboco_git_push(project_slug="roboco")
+```
+
+## Pull Requests
+
+```python
+# Create PR
+roboco_git_create_pr(
+    project_slug="roboco",
+    task_id=task_id,
+    title="[TASK-a1b2c3d4] Add rate limiting",
+    body="## Summary\n..."
+)
+
+# Merge PR (PM only)
+roboco_git_merge_pr(
+    project_slug="roboco",
+    pr_number=123,
+    merge_method="squash"  # squash, merge, rebase
+)
+```
+
+## Branch Naming
+
+```
+{type}/{team}/{task-id-prefix}
+```
+
+| Type | Use |
+|------|-----|
+| `feature/` | New functionality |
+| `fix/` | Bug fixes |
+| `refactor/` | Code restructuring |
+| `docs/` | Documentation |

docs/rag/tools/journal-tools.md

@@ -0,0 +1,92 @@
+# Journal Tools
+
+## Creating Entries
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_journal_entry` | General entry |
+| `roboco_journal_decision` | Decision log |
+| `roboco_journal_learning` | Learning capture |
+| `roboco_journal_struggle` | Problem/solution |
+| `roboco_journal_reflect` | Task reflection |
+
+## General Entry
+
+```python
+roboco_journal_entry({
+    type: "learning",
+    title: "Redis SCAN vs KEYS",
+    content: "SCAN is better for large datasets",
+    task_id: task_id,
+    tags: ["redis", "performance"]
+})
+```
+
+Entry types: `task_reflection`, `decision_log`, `learning`, `struggle`, `general`
+
+## Decision Log
+
+```python
+roboco_journal_decision({
+    title: "Session storage choice",
+    context: "Need fast session lookups",
+    options: ["PostgreSQL", "Redis"],
+    chosen: "Redis",
+    rationale: "Sub-ms reads, ephemeral data"
+})
+```
+
+## Learning
+
+```python
+roboco_journal_learning({
+    content: "asyncio.gather for parallel calls",
+    how_applied: "Reduced latency 50%",
+    category: "performance",
+    tags: ["async"]
+})
+```
+
+## Struggle (Problem/Solution)
+
+```python
+roboco_journal_struggle({
+    task_id: task_id,
+    problem: "Tests failing intermittently",
+    attempts: ["Timeout increase", "Retry logic"],
+    resolution: "Race condition in setup"
+})
+```
+
+## Reflection (Required)
+
+```python
+roboco_journal_reflect({
+    task_id: task_id,
+    what_done: "Implemented rate limiting",
+    what_learned: "Lua scripts for atomicity",
+    what_struggled: "Testing concurrency"
+})
+```
+
+## Reading Journals
+
+```python
+# Search your journal
+roboco_journal_search("rate limiting", top_k=5)
+
+# Recent entries
+roboco_journal_recent(limit=10)
+
+# Read team journals (if permitted)
+roboco_journal_read_team(
+    target_agent="be-dev-1",
+    task_id=task_id
+)
+
+# Your stats
+roboco_journal_stats()
+
+# Check access scope
+roboco_journal_scope()
+```

docs/rag/tools/kb-tools.md

@@ -0,0 +1,111 @@
+# Knowledge Base Tools
+
+## Search and Query
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_kb_search` | Semantic search |
+| `roboco_rag_query` | AI-synthesized answer |
+| `roboco_ask_mentor` | Conversational help |
+| `roboco_kb_stats` | Index statistics |
+
+## Semantic Search
+
+```python
+roboco_kb_search(
+    query="rate limiting redis",
+    top_k=5,
+    project="roboco",
+    index_types=["code", "docs"]
+)
+```
+
+## AI-Generated Answers
+
+```python
+roboco_rag_query(
+    query="How does authentication work?",
+    top_k=5
+)
+```
+
+## Mentor (Conversational)
+
+```python
+response = roboco_ask_mentor(
+    question="How do I handle auth?",
+    domain="coding"
+)
+
+# Follow-up
+roboco_ask_mentor(
+    question="What about refresh tokens?",
+    conversation_id=response["conversation_id"]
+)
+```
+
+## Indexing
+
+```python
+# Index code (PM, Developer)
+roboco_kb_index_code(
+    sources=["src/**/*.py"],
+    project="roboco"
+)
+
+# Index docs (PM, Documenter)
+roboco_kb_index_docs(
+    sources=["docs/**/*.md"],
+    project="roboco"
+)
+```
+
+## Error Tracking
+
+```python
+# Search for similar errors
+roboco_search_error(
+    error_message="Redis connection timed out",
+    context="startup"
+)
+
+# Record solution
+roboco_record_error_solution(
+    error_message="Redis connection timed out",
+    solution="Added retry with backoff",
+    worked=True
+)
+```
+
+## Decision Tracking
+
+```python
+# Check for similar decisions
+roboco_check_decision(topic="session storage")
+
+# Record decision
+roboco_record_decision(params={
+    topic: "Session storage",
+    decision: "Use Redis",
+    rationale: "Sub-ms reads"
+})
+```
+
+## Standards
+
+```python
+# Get standards
+roboco_get_standards(domain="coding", language="python")
+
+# Validate action
+roboco_validate_action(
+    action_type="create_endpoint",
+    context="Adding user API"
+)
+
+# Code review
+roboco_review_code(
+    code="def handle(...):",
+    file_path="src/api/auth.py"
+)
+```

docs/rag/tools/messaging-tools.md

@@ -0,0 +1,84 @@
+# Messaging Tools
+
+## Sending Messages
+
+```python
+roboco_message_send({
+    channel: "backend-cell",
+    content: "Starting work on rate limiting",
+    task_id: task_id
+})
+```
+
+## Channel History
+
+```python
+# Read channel history
+roboco_channel_history(
+    channel="backend-cell",
+    limit=50
+)
+```
+
+## Notifications
+
+### Sending (PM/Board only)
+
+```python
+roboco_notify_send({
+    recipient: "be-dev-1",
+    type: "task_assignment",
+    task_id: task_id,
+    message: "Task ready for you"
+})
+```
+
+### Receiving
+
+```python
+# List notifications
+notifications = roboco_notify_list()
+
+# Acknowledge
+roboco_notify_ack(notification_id)
+```
+
+### Notification Types
+
+| Type | Purpose |
+|------|---------|
+| `task_assignment` | New task assigned |
+| `priority_change` | Priority updated |
+| `blocker_escalation` | Task blocked |
+| `review_request` | Review needed |
+| `documentation_request` | Docs needed |
+| `alert` | General alert |
+| `broadcast` | Org-wide message |
+
+## Sessions
+
+```python
+# Create session for tasks
+roboco_session_create_for_tasks({
+    title: "Feature X Implementation",
+    task_ids: [task_1_id, task_2_id]
+})
+
+# Start collaborative session
+roboco_session_start(
+    channel="backend-cell",
+    session_type="collaborative",
+    task_id=task_id
+)
+```
+
+## Message Types
+
+| Type | Use For |
+|------|---------|
+| `reasoning` | Thought process |
+| `dialogue` | Discussion |
+| `decision` | Decisions made |
+| `action` | Actions taken |
+| `blocker` | Blocking issues |
+| `technical` | Technical details |

docs/rag/tools/task-tools.md

@@ -0,0 +1,92 @@
+# Task Management Tools
+
+## Core Operations
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_task_get` | Get task details |
+| `roboco_task_scan` | Find available tasks |
+| `roboco_task_claim` | Take ownership |
+| `roboco_task_start` | Begin work |
+
+## Task Retrieval
+
+```python
+# Get specific task
+task = roboco_task_get(task_id)
+
+# Scan for available tasks
+tasks = roboco_task_scan(
+    team="backend",        # Optional filter
+    status="pending"       # Optional filter
+)
+```
+
+## Task Lifecycle
+
+```python
+# Claim task
+roboco_task_claim(task_id)
+
+# Start work (also resumes paused tasks)
+roboco_task_start(task_id)
+
+# Pause work
+roboco_task_pause(task_id, reason="Waiting for clarification")
+
+# Resume paused work (use start)
+roboco_task_start(task_id)  # Works on paused tasks
+
+# Block (waiting on another task)
+roboco_task_block(task_id, blocker_task_id, reason)
+
+# Unblock (PM only)
+roboco_task_unblock(task_id)
+```
+
+## Submission
+
+```python
+# Submit for verification
+roboco_task_submit_verification(task_id)
+
+# Submit for QA
+roboco_task_submit_qa(task_id, notes)
+
+# QA actions
+roboco_task_qa_pass(task_id, {notes: "..."})
+roboco_task_qa_fail(task_id, {notes: "...", issues: [...]})
+
+# Documentation complete
+roboco_task_docs_complete(task_id)
+
+# PM complete
+roboco_task_complete(task_id)
+```
+
+## PM Operations
+
+```python
+# Create task
+roboco_task_create({
+    title: "...",
+    description: "...",
+    team: "backend",
+    status: "backlog"
+})
+
+# Activate (backlog -> pending)
+roboco_task_activate(task_id)
+
+# Cancel
+roboco_task_cancel(task_id, reason)
+
+# Plan
+roboco_task_plan(task_id, approach, steps)
+```
+
+## Progress Updates
+
+```python
+roboco_task_progress(task_id, "Implementing API", 50)
+```

docs/rag/troubleshooting/common-issues.md

@@ -0,0 +1,89 @@
+# Common Issues
+
+## Permission Denied
+
+**Error**: "Not authorized for this action"
+
+**Cause**: Your role doesn't have permission
+
+**Check Permissions**:
+| Action | Allowed Roles |
+|--------|---------------|
+| Create task | PM, Board |
+| Cancel task | PM |
+| Pass/fail QA | QA only |
+| Complete docs | Documenter only |
+| Complete task | PM only |
+| Send notification | PM, Board |
+
+**Solution**: Request appropriate role to perform action
+
+## Task Stuck in Status
+
+**Problem**: Task won't transition
+
+**Causes**:
+1. Missing required fields
+2. Waiting on parallel action
+3. Invalid transition attempted
+
+**Check**:
+- For git tasks: branch exists?
+- For `awaiting_pm_review`: both `docs_complete` AND `pr_created`?
+- Is transition valid from current status?
+
+## Notification Not Received
+
+**Problem**: Expected notification didn't arrive
+
+**Causes**:
+1. Sender doesn't have notification permission
+2. Notification filtering
+3. Already acknowledged
+
+**Solutions**:
+- Check `roboco_notify_list()` for all notifications
+- Verify sender has PM/Board role
+- Check if already in `acked_by`
+
+## Escalation Not Routing
+
+**Problem**: Escalation went to wrong person
+
+**Cause**: Escalation auto-routes to your escalation target
+
+**Chain**:
+```
+Developer → Cell PM → Main PM → Product Owner → CEO
+```
+
+Cannot skip levels or choose target.
+
+## Tests Failing Before Submit
+
+**Problem**: Tests fail, can't submit to QA
+
+**Checklist**:
+```bash
+# Backend
+uv run pytest           # Tests
+uv run ruff check .     # Linting
+uv run mypy roboco/     # Type check
+
+# Frontend
+pnpm test
+pnpm lint
+pnpm typecheck
+```
+
+Fix all issues before submitting.
+
+## Lost Context After Pause
+
+**Problem**: Resuming task, forgot context
+
+**Solutions**:
+- Read `quick_context` field on task
+- Read your journal for this task
+- Get proactive context: `roboco_get_proactive_context(task_id)`
+- Read channel history for discussions

docs/rag/troubleshooting/git-errors.md

@@ -0,0 +1,72 @@
+# Git Error Troubleshooting
+
+## Workspace Not Found
+
+**Error**: "Workspace does not exist"
+
+**Cause**: Workspace not cloned yet
+
+**Solutions**:
+- If auto_clone enabled: workspace creates on first access
+- Manual: Wait for workspace service to clone
+- Check config: `ROBOCO_WORKSPACE_AUTO_CLONE=true`
+
+## Cannot Push
+
+**Error**: "Push failed"
+
+**Causes**:
+1. No commits to push
+2. Remote branch doesn't exist
+3. Conflicts with remote
+
+**Solutions**:
+- Create commits first: `roboco_git_commit(...)`
+- Check branch exists: `roboco_git_branches()`
+- Pull and resolve conflicts
+
+## Branch Already Exists
+
+**Error**: "Branch already exists"
+
+**Cause**: Trying to create existing branch
+
+**Solution**: Checkout existing branch:
+```python
+roboco_git_checkout(project_slug, branch_name)
+```
+
+## Merge Conflicts
+
+**Error**: "Merge conflict"
+
+**Cause**: Conflicting changes between branches
+
+**Solutions**:
+1. Pull latest from target branch
+2. Resolve conflicts manually
+3. Commit resolution
+4. Push again
+
+## PR Creation Failed
+
+**Error**: "PR creation failed"
+
+**Causes**:
+1. No commits on branch
+2. Branch not pushed
+3. GitHub CLI not configured
+
+**Solutions**:
+- Push branch first: `roboco_git_push()`
+- Verify commits exist: `roboco_git_log()`
+
+## Checkout Failed
+
+**Error**: "Cannot checkout - uncommitted changes"
+
+**Cause**: Working directory has uncommitted changes
+
+**Solutions**:
+- Commit changes: `roboco_git_commit(...)`
+- Or stash changes (if supported)

docs/rag/troubleshooting/kb-errors.md

@@ -0,0 +1,74 @@
+# Knowledge Base Troubleshooting
+
+## Empty Search Results
+
+**Problem**: `roboco_kb_search()` returns nothing
+
+**Causes**:
+1. Content not indexed yet
+2. Query too specific
+3. Wrong index type filter
+
+**Solutions**:
+- Check what's indexed: `roboco_kb_stats()`
+- Broaden query terms
+- Remove index_types filter
+- Trigger reindex: `roboco_reindex_all()`
+
+## Empty RAG Response
+
+**Problem**: `roboco_rag_query()` returns empty answer
+
+**Causes**:
+1. No relevant context found
+2. LLM returned thinking tags only
+3. Query too vague
+
+**Solutions**:
+- Check KB has relevant content
+- Rephrase query to be more specific
+- Use `roboco_kb_search()` first to verify content exists
+
+## Mentor Not Responding
+
+**Problem**: `roboco_ask_mentor()` fails or empty
+
+**Causes**:
+1. LLM timeout
+2. No relevant KB content
+3. Service temporarily unavailable
+
+**Solutions**:
+- Retry the query
+- Check KB stats
+- Use `roboco_kb_search()` as fallback
+
+## Index Failed
+
+**Problem**: `roboco_kb_index_code()` or `roboco_kb_index_docs()` fails
+
+**Causes**:
+1. Invalid file patterns
+2. Files not accessible
+3. Embedding service down
+
+**Solutions**:
+- Verify file patterns match files
+- Check file permissions
+- Verify Ollama is running
+
+## Cannot Clear Index
+
+**Problem**: "Not authorized to clear index"
+
+**Cause**: Only PM/CEO can clear indexes
+
+**Solution**: Ask PM or CEO to clear if needed
+
+## Proactive Context Empty
+
+**Problem**: `roboco_get_proactive_context()` returns empty
+
+**Cause**: No relevant context found for task
+
+**Solution**: Manual search with `roboco_kb_search()` using task keywords

docs/rag/troubleshooting/task-errors.md

@@ -0,0 +1,67 @@
+# Task Error Troubleshooting
+
+## Cannot Claim Task
+
+**Error**: "Task cannot be claimed"
+
+**Causes**:
+1. Task not in claimable status for your role
+2. Task already assigned to someone else
+3. Wrong role for this task type
+
+**Solutions**:
+- Check task status: `roboco_task_get(task_id)`
+- Verify your role can claim from current status
+- Contact PM if task needs reassignment
+
+**Claimable Status by Role**:
+| Role | Can Claim From |
+|------|----------------|
+| Developer | pending, needs_revision |
+| QA | awaiting_qa |
+| Documenter | awaiting_documentation |
+
+## Cannot Start Task
+
+**Error**: "Cannot transition to in_progress"
+
+**Causes**:
+1. Task not claimed by you
+2. For git tasks: branch not created yet
+3. Task in wrong status
+
+**Solutions**:
+- Claim first: `roboco_task_claim(task_id)`
+- Wait for PM to create branch (git tasks)
+- Check current status
+
+## Cannot Submit for QA
+
+**Error**: "Invalid transition from current status"
+
+**Causes**:
+1. Task not in `in_progress` or `verifying`
+2. Missing required fields
+
+**Solutions**:
+- Move through verification first
+- Ensure task is actively being worked
+
+## Self-Review Prevented
+
+**Error**: "Cannot review own work"
+
+**Cause**: QA/Documenter trying to claim task they developed
+
+**Solution**: Another QA/Documenter must handle this task
+
+## Git Task: No Branch
+
+**Error**: "Branch name required for git tasks"
+
+**Cause**: PM hasn't created branch yet
+
+**Solution**: Wait for PM or ask PM to create branch:
+```python
+roboco_git_create_branch(project_slug, task_id, "feature")
+```

docs/rag/workflows/escalation.md

@@ -0,0 +1,94 @@
+# Escalation Workflow
+
+## Escalation Chain
+
+```
+Developer/QA/Documenter
+         ↓
+      Cell PM
+         ↓
+      Main PM
+         ↓
+   Product Owner
+         ↓
+        CEO
+```
+
+You CANNOT skip levels in the chain.
+
+## How to Escalate
+
+```python
+roboco_task_escalate(
+    task_id="uuid-here",
+    reason="Need clarification on API contract"
+)
+```
+
+Auto-routes to your escalation target (you cannot choose).
+
+## When to Escalate
+
+| Situation | Escalate To |
+|-----------|-------------|
+| Unclear requirements | Cell PM |
+| Blocked by external factor | Cell PM |
+| Blocked by another task | Cell PM |
+| Cross-cell coordination | Main PM (via Cell PM) |
+| Major feature ready | CEO (PM only) |
+
+## Escalation vs Block vs Pause
+
+| Action | When | Tool |
+|--------|------|------|
+| **Escalate** | Need help/decision | `roboco_task_escalate` |
+| **Block** | Waiting on another task | `roboco_task_block` |
+| **Pause** | Temporarily stop work | `roboco_task_pause` |
+
+## Blocking a Task
+
+```python
+# Block on another task
+roboco_task_block(
+    task_id="uuid-here",
+    blocker_task_id="blocker-uuid",
+    reason="Waiting for auth service"
+)
+```
+
+PM receives notification with ACTION REQUIRED.
+
+## CEO Escalation (PM Only)
+
+For major tasks requiring CEO approval:
+
+```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`
+- PR must exist (for git tasks)
+- Only PMs can do this
+
+## Good Escalation Format
+
+Include:
+- What's the issue
+- What context you have
+- Specific question
+- What you already tried
+- How it's affecting work
+
+## Handling Escalations (PM)
+
+1. ACK immediately: `roboco_notify_ack(notification_id)`
+2. Investigate: Read task, journals, messages
+3. Decide or escalate further
+4. Communicate decision
+5. Unblock if needed: `roboco_task_unblock(task_id)`
+
+CRITICAL: Verbal resolution is NOT enough. You MUST call `roboco_task_unblock()`.

docs/rag/workflows/git-commits.md

@@ -0,0 +1,81 @@
+# Git Commit Workflow
+
+## Commit Format
+
+All commits are automatically prefixed with task ID:
+
+```
+[{task-id-prefix}] {message}
+```
+
+Example:
+```
+[a1b2c3d4] Add rate limiting endpoint
+```
+
+## Creating Commits
+
+```python
+roboco_git_commit(
+    project_slug="roboco",
+    task_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    message="Add rate limiting endpoint"
+)
+```
+
+This automatically:
+1. Prefixes commit with task ID (first 8 chars)
+2. Records commit in task's commit history
+3. Links to work session
+
+## Commit Message Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation |
+| `style` | Formatting |
+| `refactor` | Code restructure |
+| `test` | Tests |
+| `chore` | Maintenance |
+| `perf` | Performance |
+
+## Full Commit Format
+
+```
+{type}({scope}): {description}
+
+{body}
+
+Task: {task-id}
+Co-authored-by: {agent-name}
+```
+
+## Before Committing
+
+1. Run tests: `uv run pytest` or `pnpm test`
+2. Run linter: `uv run ruff check .` or `pnpm lint`
+3. Run type check: `uv run mypy roboco/` or `pnpm typecheck`
+4. Format code: `uv run ruff format .` or `pnpm format`
+
+## Push Commits
+
+```python
+roboco_git_push(project_slug="roboco")
+```
+
+Push before:
+- Submitting for QA
+- Creating PR
+- Ending work session
+
+## Viewing Commits
+
+```python
+# View commit history
+roboco_git_log(project_slug="roboco", branch="feature/backend/a1b2c3d4")
+
+# View changes
+roboco_git_diff(project_slug="roboco")
+```

docs/rag/workflows/journaling.md

@@ -0,0 +1,87 @@
+# Journaling Workflow
+
+## Why Journal
+
+1. Becomes searchable knowledge for future agents
+2. Helps with task handoffs
+3. Documents decisions and learnings
+4. Required before key transitions
+
+## Entry Types
+
+| Type | Use For |
+|------|---------|
+| `task_reflection` | End of task summary |
+| `decision_log` | Architectural decisions |
+| `learning` | New knowledge gained |
+| `struggle` | Problems and solutions |
+| `general` | Other observations |
+
+## Creating Entries
+
+```python
+# General entry
+roboco_journal_entry({
+    type: "learning",
+    title: "Redis SCAN vs KEYS",
+    content: "SCAN is better for large datasets",
+    task_id: task_id,
+    tags: ["redis", "performance"]
+})
+
+# Decision log
+roboco_journal_decision({
+    title: "Session storage choice",
+    context: "Need fast session lookups",
+    options: ["PostgreSQL", "Redis", "In-memory"],
+    chosen: "Redis",
+    rationale: "Sub-millisecond reads, ephemeral data"
+})
+
+# Struggle (problem and solution)
+roboco_journal_struggle({
+    task_id: task_id,
+    problem: "Tests failing intermittently",
+    attempts: ["Increased timeout", "Added retry"],
+    resolution: "Race condition in setup"
+})
+
+# Learning
+roboco_journal_learning({
+    content: "Use asyncio.gather for parallel calls",
+    how_applied: "Reduced endpoint latency 50%",
+    category: "performance",
+    tags: ["async", "performance"]
+})
+```
+
+## Required Reflections
+
+Before submitting for QA or completing:
+
+```python
+roboco_journal_reflect({
+    task_id: task_id,
+    what_done: "Implemented rate limiting with Redis",
+    what_learned: "Lua scripts for atomic operations",
+    what_struggled: "Testing concurrent requests"
+})
+```
+
+## Searching Journals
+
+```python
+# Semantic search your journal
+roboco_journal_search("rate limiting patterns", top_k=5)
+
+# Search team journals (if permitted)
+roboco_journal_read_team("be-dev-1", task_id=task_id)
+```
+
+## Best Practices
+
+1. **Journal as you go** - Don't wait until end
+2. **Be specific** - Generic entries are less searchable
+3. **Use tags** - Helps categorization
+4. **Record failures** - They're valuable learning
+5. **Include context** - Future searchers need it

docs/rag/workflows/kb-search.md

@@ -0,0 +1,90 @@
+# Knowledge Base Search
+
+## Search Types
+
+| Tool | Purpose |
+|------|---------|
+| `roboco_kb_search` | Semantic search across indexes |
+| `roboco_rag_query` | AI-synthesized answer |
+| `roboco_ask_mentor` | Conversational help |
+
+## Semantic Search
+
+```python
+roboco_kb_search(
+    query="rate limiting redis implementation",
+    top_k=5,                      # Results to return
+    project="roboco",             # Optional project filter
+    index_types=["code", "docs"]  # Filter by type
+)
+```
+
+Returns similar content - not just keyword matches.
+
+## RAG Query (AI Answer)
+
+```python
+roboco_rag_query(
+    query="How does authentication work in this codebase?",
+    top_k=5
+)
+```
+
+Returns AI-synthesized answer with citations.
+
+Good for:
+- "How does X work?"
+- "What pattern should I use?"
+- "What decisions were made about Y?"
+
+## Mentor (Conversational)
+
+```python
+# First question
+response = roboco_ask_mentor(
+    question="How do I handle authentication?",
+    domain="coding"
+)
+
+# Follow-up
+roboco_ask_mentor(
+    question="What about refresh tokens?",
+    conversation_id=response["conversation_id"]
+)
+```
+
+## Index Types
+
+| Type | Content |
+|------|---------|
+| `code` | Source files |
+| `docs` | Documentation |
+| `conversations` | Channel discussions |
+| `journals` | Agent journal entries |
+| `errors` | Error patterns & fixes |
+| `standards` | Coding rules |
+| `decisions` | Architectural decisions |
+| `reviews` | Code review patterns |
+| `learnings` | Captured learnings |
+
+## Before Starting a Task
+
+Always search first:
+```python
+roboco_kb_search("implementing rate limiter")
+roboco_journal_search("rate limit decisions")
+```
+
+This helps you:
+- Avoid repeating mistakes
+- Find proven patterns
+- Learn from others' experiences
+
+## Proactive Context
+
+System auto-provides context when you claim:
+```python
+roboco_get_proactive_context(task_id)
+# Returns: similar_tasks, relevant_learnings, code_patterns,
+#          applicable_standards, recent_decisions, known_issues
+```

docs/rag/workflows/pr-creation.md

@@ -0,0 +1,75 @@
+# Pull Request Creation
+
+## When to Create PR
+
+Create PR in `awaiting_documentation` phase (parallel with documenter).
+
+## Creating a PR
+
+```python
+roboco_git_create_pr(
+    project_slug="roboco",
+    task_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    title="[TASK-a1b2c3d4] Add rate limiting",
+    body="## Summary\n- Implemented sliding window...\n\n## Test Plan\n..."
+)
+```
+
+This automatically:
+1. Creates PR via GitHub CLI (`gh pr create`)
+2. Targets project's default branch
+3. Sets `pr_created=True` on task
+4. Records PR number and URL
+
+## PR Title Format
+
+```
+[TASK-{id-prefix}] {description}
+```
+
+Example: `[TASK-a1b2c3d4] Add rate limiting endpoint`
+
+## PR Body Template
+
+```markdown
+## Summary
+- What was implemented
+- Key changes
+
+## Test Plan
+- How to test the changes
+- Test coverage
+
+Task: {task-id}
+```
+
+## Parallel Execution
+
+In `awaiting_documentation`:
+
+| Agent | Action | Flag |
+|-------|--------|------|
+| Developer | Creates PR | `pr_created=True` |
+| Documenter | Writes docs | `docs_complete=True` |
+
+Task advances to `awaiting_pm_review` when BOTH are done.
+
+## Before Creating PR
+
+1. Push all commits: `roboco_git_push()`
+2. Verify tests pass
+3. Ensure code quality checks pass
+4. Branch is up to date with target
+
+## PM Merges PR
+
+After completing task:
+```python
+roboco_git_merge_pr(
+    project_slug="roboco",
+    pr_number=123,
+    merge_method="squash"  # or "merge", "rebase"
+)
+```
+
+Only PM can merge PRs.

docs/rag/workflows/qa-review.md

@@ -0,0 +1,88 @@
+# QA Review Workflow
+
+## When QA Starts
+
+Task must be in `awaiting_qa` status.
+
+## QA Review Steps
+
+```python
+# 1. Claim the task
+roboco_task_claim(task_id)
+
+# 2. Start review
+roboco_task_start(task_id)
+
+# 3. Announce to cell
+roboco_message_send({
+    channel: "backend-cell",
+    content: "Starting QA review of [task title]",
+    task_id: task_id
+})
+
+# 4. Read developer's journey (REQUIRED)
+roboco_journal_read_team(original_developer, task_id=task_id)
+
+# 5. Checkout branch and review
+roboco_git_checkout(project_slug, branch_name)
+roboco_git_diff(project_slug)
+
+# 6. Run tests
+# Backend: uv run pytest
+# Frontend: pnpm test
+```
+
+## Review Checklist
+
+Before making decision:
+- [ ] Read developer's handoff notes
+- [ ] Check all acceptance criteria
+- [ ] Run tests (must pass)
+- [ ] Verify functionality
+- [ ] Check code quality
+- [ ] Review against standards
+
+## Passing QA
+
+```python
+roboco_task_qa_pass(task_id, {
+    notes: "All acceptance criteria met. Tests pass. Code follows standards."
+})
+```
+
+Result: Task advances to `awaiting_documentation`
+
+## Failing QA
+
+```python
+roboco_task_qa_fail(task_id, {
+    notes: "Issues found during review",
+    issues: [
+        "Bug: X doesn't work",
+        "Missing: Y not implemented"
+    ]
+})
+```
+
+Result:
+- Task returns to `needs_revision`
+- Assigned back to original developer
+- Developer receives notification
+
+## Before Decision
+
+Write reflection (REQUIRED):
+```python
+roboco_journal_reflect({
+    task_id: task_id,
+    what_done: "Reviewed X, Y, Z",
+    what_learned: "Discovered patterns...",
+    what_struggled: "Edge cases unclear"
+})
+```
+
+## Self-Review Prevention
+
+QA CANNOT review tasks they originally developed.
+
+System tracks `original_developer` in `quick_context`. If QA == original_developer, claim is FORBIDDEN.

docs/rag/workflows/task-claiming.md

@@ -0,0 +1,59 @@
+# Task Claiming Workflow
+
+## Who Can Claim What
+
+| Role | Can Claim From Status |
+|------|----------------------|
+| Developer | `pending`, `needs_revision` |
+| QA | `awaiting_qa` |
+| Documenter | `awaiting_documentation`, `pending` |
+| PM | `pending`, `backlog` |
+
+## Claiming a Task
+
+```python
+# 1. Find available tasks
+roboco_task_scan(team="backend")
+
+# 2. Claim the task
+roboco_task_claim(task_id)
+
+# Result:
+# - status: claimed
+# - assigned_to: your agent ID
+```
+
+## Before Claiming
+
+1. Check you have capacity (one task at a time recommended)
+2. Verify dependencies are completed
+3. Read task description and acceptance criteria
+
+## After Claiming
+
+1. Start work: `roboco_task_start(task_id)`
+2. Announce to cell: `roboco_message_send({channel, content, task_id})`
+3. Get proactive context: `roboco_get_proactive_context(task_id)`
+4. Search KB for similar work: `roboco_kb_search()`
+
+## Claiming Rules
+
+- **One at a time**: Don't claim multiple in_progress tasks
+- **Self-review prevention**: QA cannot claim tasks they developed
+- **Self-documentation prevention**: Documenter cannot claim tasks they developed
+- **Git requirement**: For git tasks, branch must exist before starting
+
+## Status After Claim
+
+```
+pending → claimed (Developer/PM)
+needs_revision → claimed (Developer)
+awaiting_qa → claimed (QA)
+awaiting_documentation → claimed (Documenter)
+```
+
+## Cannot Claim
+
+- `completed` or `cancelled` (terminal states)
+- Tasks assigned to others
+- Tasks you cannot work on (wrong role/team)

docs/rag/workflows/task-states.md

@@ -0,0 +1,72 @@
+# Task States Reference
+
+## State Categories
+
+### Active States (Work happening)
+- `claimed` - Agent has ownership, about to start
+- `in_progress` - Active work
+- `verifying` - Self-verification
+- `needs_revision` - Fixing QA issues
+
+### Waiting States (On hold)
+- `blocked` - Waiting on dependency
+- `paused` - Temporarily stopped
+- `awaiting_qa` - Ready for QA review
+- `awaiting_documentation` - Ready for docs
+- `awaiting_pm_review` - Ready for PM approval
+- `awaiting_ceo_approval` - Major task, CEO review
+
+### Terminal States (Done)
+- `completed` - Work finished
+- `cancelled` - Work cancelled
+
+### Special States
+- `quarantined` - Problematic task, can return to pending
+
+### Setup State
+- `backlog` - PM setup phase, not ready for work
+
+## State Transitions
+
+### Developer Flow
+```
+pending → claimed → in_progress → verifying → awaiting_qa
+                         ↑                         ↓
+                         └── needs_revision ←──────┘
+```
+
+### QA Flow
+```
+awaiting_qa → claimed → in_progress → pass/fail
+                                         ↓
+                        pass: awaiting_documentation
+                        fail: needs_revision
+```
+
+### Documenter Flow
+```
+awaiting_documentation → claimed → in_progress → awaiting_pm_review
+```
+
+### PM Activation
+```
+backlog → pending (via roboco_task_activate)
+```
+
+## Role-Restricted Transitions
+
+| Transition | Allowed Roles |
+|------------|---------------|
+| `backlog → pending` | cell_pm, main_pm |
+| `awaiting_qa → awaiting_documentation` | qa only |
+| `awaiting_qa → needs_revision` | qa only |
+| `awaiting_documentation → awaiting_pm_review` | documenter only |
+| `awaiting_pm_review → completed` | cell_pm, main_pm |
+| `any → cancelled` | cell_pm, main_pm |
+
+## Checking State
+
+```python
+task = roboco_task_get(task_id)
+# task.status contains current state
+```