Huge refactoring but stuff is working again; minus some issues here and there.

2026-08-03 07:23:24 +02:00 · 2025-12-26 18:01:53 +01:00
parent c813dcfae4
commit 8c3bf9e22c
89 changed files with 3975 additions and 851 deletions
@@ -24,6 +24,8 @@ SCAN → CLAIM → PLAN → START → WORK → VERIFY → SUBMIT_QA
 ✅ roboco_task_escalate(task_id, reason)
 ✅ roboco_task_submit_verification(task_id)
 ✅ roboco_task_submit_qa(task_id, notes)
+✅ roboco_task_submit_pm_review(task_id, notes)  → For non-dev tasks
+✅ roboco_task_substitute(task_id, reason, details)  → Graceful exit

 ✅ roboco_message_send(channel, content, task_id)
 ✅ roboco_channel_history(channel)
@@ -35,6 +37,12 @@ SCAN → CLAIM → PLAN → START → WORK → VERIFY → SUBMIT_QA
 ✅ roboco_journal_learning(...)
 ✅ roboco_journal_struggle(...)
 ✅ roboco_journal_search(query)
+
+✅ roboco_kb_search(query, top_k)       → Search knowledge base
+✅ roboco_rag_query(query)              → AI-generated answer from KB
+✅ roboco_kb_stats()                    → What's indexed
+✅ roboco_kb_index_code(sources)        → Index code for search
+✅ roboco_tokens_estimate(content)      → Estimate token count
 ```

 ### NOT Your Tools
@@ -69,10 +77,16 @@ SCAN (awaiting_qa) → CLAIM → START → REVIEW → PASS or FAIL
 ✅ roboco_task_qa_pass(task_id, notes)
 ✅ roboco_task_qa_fail(task_id, notes, issues)
 ✅ roboco_task_escalate(task_id, reason)
+✅ roboco_task_substitute(task_id, reason, details)  → Graceful exit

 ✅ roboco_message_send(...)
 ✅ roboco_channel_history(...)
 ✅ roboco_journal_entry(...)
+
+✅ roboco_kb_search(query, top_k)       → Search knowledge base
+✅ roboco_rag_query(query)              → AI-generated answer from KB
+✅ roboco_kb_stats()                    → What's indexed
+✅ roboco_tokens_estimate(content)      → Estimate token count
 ```

 ### Rules
@@ -98,11 +112,18 @@ SCAN (awaiting_documentation) → CLAIM → START → WRITE → DOCS_COMPLETE
 ✅ roboco_task_start(task_id)
 ✅ roboco_task_progress(task_id, message, percentage)
 ✅ roboco_task_docs_complete(task_id)
+✅ roboco_task_substitute(task_id, reason, details)  → Graceful exit

 ✅ roboco_journal_read_team(agent_slug)  → Read dev's journey
 ✅ roboco_message_send(...)
 ✅ roboco_channel_history(...)
 ✅ roboco_journal_entry(...)
+
+✅ roboco_kb_search(query, top_k)       → Search knowledge base
+✅ roboco_rag_query(query)              → AI-generated answer from KB
+✅ roboco_kb_stats()                    → What's indexed
+✅ roboco_kb_index_docs(sources)        → Index docs for search
+✅ roboco_tokens_estimate(content)      → Estimate token count
 ```

 ### Rules
@@ -136,8 +157,12 @@ SCAN → CLAIM → START → PLAN → CREATE SUBTASKS → ACTIVATE → NOTIFY
 ✅ roboco_task_pause(task_id, ...)
 ✅ roboco_task_cancel(task_id, reason)

+✅ roboco_task_substitute(task_id, reason, details)  → Graceful exit
+
 ✅ roboco_session_create_for_tasks(data)
 ✅ roboco_session_link_task(data)
+✅ roboco_session_unlink_task(data)
+✅ roboco_session_get_for_task(task_id)
 ✅ roboco_group_create(data)

 ✅ roboco_notify_send(recipient, type, task_id, message)
@@ -147,6 +172,13 @@ SCAN → CLAIM → START → PLAN → CREATE SUBTASKS → ACTIVATE → NOTIFY
 ✅ roboco_journal_read_team(agent_slug)  → Read cell member journals
 ✅ roboco_message_send(...)
 ✅ roboco_channel_history(...)
+
+✅ roboco_kb_search(query, top_k)       → Search knowledge base
+✅ roboco_rag_query(query)              → AI-generated answer from KB
+✅ roboco_kb_stats()                    → What's indexed
+✅ roboco_kb_index_code(sources)        → Index code for search
+✅ roboco_kb_index_docs(sources)        → Index docs for search
+✅ roboco_tokens_estimate(content)      → Estimate token count
 ```

 ### Your Channels
@@ -41,7 +41,16 @@ Developers (be-dev-1, be-dev-2, fe-dev-1, fe-dev-2, ux-dev) execute implementati
   │  └─────────────────────────────────────────────────────────────────┘
   │
   ▼
-4. PLAN
+4. RESEARCH (before planning)
+   │
+   │  roboco_kb_search("similar implementations")
+   │  roboco_rag_query("how does X work in this codebase?")
+   │  roboco_journal_search("past decisions about X")
+   │
+   │  → Learn from past work before planning
+   │
+   ▼
+5. PLAN
   │
   │  roboco_task_plan(
   │    task_id,
@@ -57,38 +66,56 @@ Developers (be-dev-1, be-dev-2, fe-dev-1, fe-dev-2, ux-dev) execute implementati
   │  If questions → roboco_message_send() to PM
   │
   ▼
-5. START WORK
+6. START WORK
   │
   │  roboco_task_start(task_id)
   │
+   │  # REQUIRED: Announce to cell
+   │  roboco_message_send({
+   │    channel: "backend-cell",
+   │    content: "Starting work on [task title]",
+   │    task_id: task_id
+   │  })
+   │
   │  STATUS: claimed → in_progress
   │
   ▼
-6. EXECUTE (loop)
+7. EXECUTE (loop)
   │
   │  ┌─────────────────────────────────────────────────────────────────┐
-   │  │ While working:                                                  │
-   │  │                                                                 │
+   │  │ REQUIRED - Progress updates:                                    │
   │  │   roboco_task_progress(task_id, "Completed X", 25)              │
   │  │   roboco_task_progress(task_id, "Working on Y", 50)             │
-   │  │   roboco_task_progress(task_id, "Almost done", 75)              │
   │  │                                                                 │
-   │  │   roboco_journal_entry({                                        │
-   │  │     type: "work_log",                                           │
-   │  │     content: "What I did and learned"                           │
-   │  │   })                                                            │
+   │  │ REQUIRED - Journal as you go:                                   │
+   │  │   roboco_journal_entry(type="work_log", ...)  # General notes   │
+   │  │   roboco_journal_decision(...)     # When choosing approaches   │
+   │  │   roboco_journal_learning(...)     # When learning something    │
+   │  │   roboco_journal_struggle(...)     # When hitting issues        │
   │  │                                                                 │
   │  │ If BLOCKED:                                                     │
-   │  │   roboco_task_block(task_id, blocker_task_id)  ← blocked by     │
-   │  │   OR                                             another task   │
-   │  │   roboco_task_escalate(task_id, reason)       ← need PM help    │
+   │  │   roboco_task_block(task_id, blocker_task_id)                   │
+   │  │   roboco_journal_struggle(what="...", resolution="pending")     │
+   │  │   roboco_task_escalate(task_id, reason)  # Notify PM            │
   │  │                                                                 │
   │  │ If need to PAUSE:                                               │
   │  │   roboco_task_pause(task_id, reason, checkpoint, remaining)     │
   │  └─────────────────────────────────────────────────────────────────┘
   │
   ▼
-7. SELF-VERIFY
+8. REFLECT (before submitting)
+   │
+   │  # REQUIRED before QA submission
+   │  roboco_journal_reflect({
+   │    task_id: task_id,
+   │    what_done: "What I built",
+   │    what_learned: "New knowledge gained",
+   │    what_struggled: "Challenges faced",
+   │    next_steps: "For QA/documenter"
+   │  })
+   │
+   ▼
+9. SELF-VERIFY
   │
   │  roboco_task_submit_verification(task_id)
   │
@@ -103,7 +130,7 @@ Developers (be-dev-1, be-dev-2, fe-dev-1, fe-dev-2, ux-dev) execute implementati
   │  └─────────────────────────────────────────────────────────────────┘
   │
   ▼
-8. SUBMIT FOR QA
+10. SUBMIT FOR QA
   │
   │  roboco_task_submit_qa(task_id, {
   │    notes: "What I built and how to test it",
@@ -160,9 +187,40 @@ SUBMIT:
 ## Key Rules

 1. **CLAIM before anything** - Must claim to own the task
-2. **PLAN before START** - roboco_task_plan() required before start()
-3. **PROGRESS updates** - Keep PM informed with percentage
-4. **JOURNAL your work** - Document decisions, learnings, struggles
-5. **SELF-VERIFY first** - Check your own work before QA
-6. **Cannot COMPLETE** - Only PM completes tasks after full workflow
-7. **One task at a time** - Can't claim new task while one is in_progress
+2. **RESEARCH before PLAN** - Search KB and journals for past work
+3. **PLAN before START** - roboco_task_plan() required before start()
+4. **MESSAGE when starting** - Announce to cell channel
+5. **PROGRESS updates** - Keep PM informed with percentage
+6. **JOURNAL as you go** - Decisions, learnings, struggles (REQUIRED)
+7. **REFLECT before submit** - roboco_journal_reflect() REQUIRED
+8. **SELF-VERIFY first** - Check your own work before QA
+9. **Cannot COMPLETE** - Only PM completes tasks after full workflow
+10. **One task at a time** - Can't claim new task while one is in_progress
+
+## Substitution (Graceful Exit)
+
+If you can't continue a task, use substitution instead of getting stuck:
+
+```
+roboco_task_substitute(task_id, reason, details)
+```
+
+**Reasons:**
+- `low_context` - Not enough context to continue safely
+- `out_of_scope_team` - Task belongs to a different team
+- `out_of_scope_role` - Task requires QA or documenter, not dev
+- `task_complete` - Done with your part, releasing for next stage
+- `max_retries` - Tried multiple times, need fresh perspective
+- `blocked_external` - Need skills outside your capabilities
+
+After substitution, you are **FREE to claim new work** immediately.
+
+## Non-Dev Tasks (Alternate Path)
+
+If you receive a non-code task (validation, research, audit):
+
+```
+roboco_task_submit_pm_review(task_id, notes)
+```
+
+This skips the QA/docs workflow and goes directly to PM review.
@@ -36,21 +36,30 @@ Documenters (be-doc, fe-doc, ux-doc) create production documentation from develo
   │
   │  roboco_task_start(task_id)
   │
+   │  # REQUIRED: Announce to cell
+   │  roboco_message_send({
+   │    channel: "backend-cell",
+   │    content: "Starting documentation for [task title]",
+   │    task_id: task_id
+   │  })
+   │
   │  STATUS: claimed → in_progress
   │
   ▼
 4. GATHER CONTEXT
   │
   │  ┌─────────────────────────────────────────────────────────────────┐
-   │  │ Read:                                                           │
-   │  │ ├── Developer's handoff notes (in quick_context)                │
-   │  │ ├── Developer's journal entries                                 │
-   │  │ ├── QA review notes                                             │
-   │  │ ├── Related commits                                             │
-   │  │ └── Code changes                                                │
+   │  │ REQUIRED - Read dev's journey:                                  │
+   │  │   roboco_journal_read_team(original_developer, task_id=task_id) │
   │  │                                                                 │
-   │  │ roboco_journal_read_team("be-dev-1") → Read dev's journal       │
-   │  │ roboco_channel_history("backend-cell") → Related discussion     │
+   │  │ Also review:                                                    │
+   │  │ ├── Developer's handoff notes (in quick_context)                │
+   │  │ ├── QA review notes                                             │
+   │  │ ├── roboco_channel_history("backend-cell")                      │
+   │  │ └── roboco_kb_search("similar documentation")                   │
+   │  │                                                                 │
+   │  │ Journal what you gathered:                                      │
+   │  │   roboco_journal_entry({type: "research", ...})                 │
   │  └─────────────────────────────────────────────────────────────────┘
   │
   ▼
@@ -63,12 +72,31 @@ Documenters (be-doc, fe-doc, ux-doc) create production documentation from develo
   │  │ ├── Architecture notes                                          │
   │  │ └── Update README if needed                                     │
   │  │                                                                 │
-   │  │ roboco_task_progress(task_id, "Writing API docs", 50)           │
-   │  │ roboco_task_progress(task_id, "Adding examples", 75)            │
+   │  │ REQUIRED - Progress updates:                                    │
+   │  │   roboco_task_progress(task_id, "Writing API docs", 50)         │
+   │  │   roboco_task_progress(task_id, "Adding examples", 75)          │
+   │  │                                                                 │
+   │  │ REQUIRED - Journal as you write:                                │
+   │  │   roboco_journal_entry({type: "documentation", ...})            │
+   │  │   roboco_journal_decision(...) # For doc structure choices      │
   │  └─────────────────────────────────────────────────────────────────┘
   │
   ▼
-6. COMPLETE DOCUMENTATION
+6. REFLECT & INDEX (before completing)
+   │
+   │  # REQUIRED: Reflect on documentation work
+   │  roboco_journal_reflect({
+   │    task_id: task_id,
+   │    what_done: "Created X docs with Y examples",
+   │    what_learned: "Doc patterns for this codebase",
+   │    what_struggled: "Understanding Z component"
+   │  })
+   │
+   │  # Index your new docs for future search
+   │  roboco_kb_index_docs(["docs/new-feature.md"])
+   │
+   ▼
+7. COMPLETE DOCUMENTATION
   │
   │  roboco_task_docs_complete(task_id)
   │
@@ -103,10 +131,29 @@ COMPLETE:
  in_progress ──docs_complete──► awaiting_pm_review
 ```

+## Using Knowledge Base
+
+Documenters have KB access including doc indexing:
+
+```python
+roboco_kb_search("similar documentation")      # Find related docs
+roboco_rag_query("how is X documented?")       # AI-generated answers
+roboco_journal_read_team("be-dev-1")           # Read developer's journey
+
+# Indexing (Documenter)
+roboco_kb_index_docs(["docs/**/*.md"])         # Index your docs for search
+```
+
+See [KNOWLEDGE_BASE.md](./KNOWLEDGE_BASE.md) for full documentation.
+
 ## Key Rules

 1. **Only claim awaiting_documentation or pending** - Can't claim dev tasks
 2. **Cannot self-document** - Can't document your own dev work
-3. **Read developer's journey** - Use journals and handoff notes
-4. **Quality docs** - Future developers depend on this
-5. **Cannot COMPLETE task** - Only submits for PM review
+3. **MESSAGE when starting** - Announce to cell channel
+4. **READ dev's journey** - roboco_journal_read_team() REQUIRED
+5. **JOURNAL your work** - Document decisions, learnings
+6. **REFLECT before submit** - roboco_journal_reflect() REQUIRED
+7. **INDEX your docs** - roboco_kb_index_docs() for future search
+8. **Quality docs** - Future developers depend on this
+9. **Cannot COMPLETE task** - Only submits for PM review
@@ -3,15 +3,87 @@
 ## Overview

 The knowledge base is built from:
+- **Code** - Indexed source files
+- **Documentation** - Indexed docs and READMEs
 - **Journals** - Your entries and team entries
 - **Task history** - Past tasks, decisions, outcomes
 - **Messages** - Channel discussions
- **Documentation** - Produced docs

 All content is **embedded** (vectorized) for semantic search.

 ---

+## Knowledge Base Tools
+
+### Semantic Search
+
+```python
+roboco_kb_search(
+    query="rate limiting redis implementation",
+    top_k=5,                    # Results to return (1-20)
+    project="roboco",           # Optional project filter
+    task_id="uuid-here",        # Optional task filter
+    index_types=["code", "docs"]  # Filter by type
+)
+```
+
+Returns semantically similar content from indexed code, docs, and learnings.
+
+### RAG Queries (AI-Generated Answers)
+
+```python
+roboco_rag_query(
+    query="How does authentication work in this codebase?",
+    top_k=5,                    # Context chunks to use
+    project="roboco"            # Optional project filter
+)
+```
+
+Returns an AI-synthesized answer with citations to sources.
+
+**Good for questions like:**
+- "How does authentication work?"
+- "What pattern should I use for error handling?"
+- "What decisions were made about the database schema?"
+
+### Check What's Indexed
+
+```python
+roboco_kb_stats()
+# Returns: indexed content counts by type
+```
+
+### Estimate Token Count
+
+```python
+roboco_tokens_estimate(content="...", model="claude-sonnet-4")
+# Returns: token count for context planning
+```
+
+---
+
+## Indexing Content (PM/Developer/Documenter)
+
+### Index Code (PM, Developer)
+
+```python
+roboco_kb_index_code(
+    sources=["src/**/*.py", "lib/**/*.ts"],
+    project="roboco"
+)
+```
+
+### Index Documentation (PM, Documenter)
+
+```python
+roboco_kb_index_docs(
+    sources=["docs/**/*.md", "README.md"],
+    project="roboco"
+)
+```
+
+---
+
 ## Searching the Knowledge Base

 ### Search Your Journal
@@ -151,12 +223,15 @@ Everything you journal becomes searchable:

 ---

-## Future: RAG Queries (Planned)
+## Tool Quick Reference

-Eventually you'll be able to:
- Query across all knowledge (tasks, docs, code)
- Get AI-synthesized answers
- Find relevant code examples
- Cross-reference decisions with outcomes
-
-For now, journal search is your primary tool.
+| Tool | Purpose | Who Can Use |
+|------|---------|-------------|
+| `roboco_kb_search` | Semantic search | Everyone |
+| `roboco_rag_query` | AI-generated answers | Everyone |
+| `roboco_kb_stats` | What's indexed | Everyone |
+| `roboco_kb_index_code` | Index code files | PM, Developer |
+| `roboco_kb_index_docs` | Index documentation | PM, Documenter |
+| `roboco_tokens_estimate` | Token count | Everyone |
+| `roboco_journal_search` | Search your journal | Everyone |
+| `roboco_journal_read_team` | Read team journals | PM, Documenter |
@@ -0,0 +1,267 @@
+# MCP Tool Test Matrix
+
+Comprehensive test matrix for validating all MCP tools work correctly for each agent role.
+
+## Test Environment Setup
+
+```bash
+# Start services
+docker-compose up -d postgres redis qdrant
+cd roboco && uv run python -m roboco.api.main
+
+# Test agent endpoints
+curl -H "X-Agent-ID: be-dev-1" http://localhost:8000/health
+```
+
+---
+
+## Task MCP Tools (55 total tools)
+
+### Core Lifecycle Tools (All Agents)
+
+| Tool | Developer | QA | PM | Documenter | Board | Test Case |
+|------|-----------|----|----|------------|-------|-----------|
+| `roboco_task_scan` | Y | Y | Y | Y | Y | Scan returns tasks filtered by role/team |
+| `roboco_task_get` | Y | Y | Y | Y | Y | Fetch task by ID returns full details |
+| `roboco_task_claim` | Y | Y | Y | Y | N | Only claimable statuses for role |
+| `roboco_task_plan` | Y | N | Y | N | N | Saves plan, requires claimed status |
+| `roboco_task_start` | Y | Y | Y | Y | N | Status → in_progress, requires plan |
+| `roboco_task_progress` | Y | Y | Y | Y | N | Updates percentage (0-100) |
+| `roboco_task_escalate` | Y | Y | Y | Y | N | Routes to correct manager |
+| `roboco_task_substitute` | Y | Y | Y | Y | N | Graceful exit with reason |
+| `roboco_agent_idle` | Y | Y | Y | Y | N | Signals no work available |
+
+### Blocking Tools (Developer + PM)
+
+| Tool | Developer | QA | PM | Documenter | Board | Test Case |
+|------|-----------|----|----|------------|-------|-----------|
+| `roboco_task_block` | Y | N | Y | N | N | Status → blocked, records reason |
+| `roboco_task_unblock` | Y (own) | N | Y (cell) | N | N | Status → in_progress |
+| `roboco_task_pause` | Y | N | Y | N | N | Status → paused, saves checkpoint |
+
+### Developer Submit Tools
+
+| Tool | Developer | QA | PM | Documenter | Board | Test Case |
+|------|-----------|----|----|------------|-------|-----------|
+| `roboco_task_submit_verification` | Y | N | N | N | N | Status → verifying |
+| `roboco_task_submit_qa` | Y | N | N | N | N | Status → awaiting_qa |
+| `roboco_task_submit_pm_review` | Y | N | N | N | N | Status → awaiting_pm_review (non-dev tasks) |
+
+### QA Tools
+
+| Tool | Developer | QA | PM | Documenter | Board | Test Case |
+|------|-----------|----|----|------------|-------|-----------|
+| `roboco_task_qa_pass` | N | Y | N | N | N | Status → awaiting_documentation |
+| `roboco_task_qa_fail` | N | Y | N | N | N | Status → needs_revision, records issues |
+
+### Documenter Tools
+
+| Tool | Developer | QA | PM | Documenter | Board | Test Case |
+|------|-----------|----|----|------------|-------|-----------|
+| `roboco_task_docs_complete` | N | N | N | Y | N | Status → awaiting_pm_review |
+
+### PM/Management Tools
+
+| Tool | Developer | QA | PM | Documenter | Board | Test Case |
+|------|-----------|----|----|------------|-------|-----------|
+| `roboco_task_create` | N | N | Y | N | Y | Creates task in backlog |
+| `roboco_task_assign` | N | N | Y | N | Y | Sets assigned_to field |
+| `roboco_task_activate` | N | N | Y | N | Y | Status: backlog → pending |
+| `roboco_task_complete` | N | N | Y | N | Y | Status → completed |
+| `roboco_task_cancel` | N | N | Y | N | Y | Status → cancelled |
+
+### Session Tools (PM/Board)
+
+| Tool | Developer | QA | PM | Documenter | Board | Test Case |
+|------|-----------|----|----|------------|-------|-----------|
+| `roboco_session_create_for_tasks` | N | N | Y | N | Y | Creates linked session |
+| `roboco_session_link_task` | N | N | Y | N | Y | Links existing session to task |
+| `roboco_session_unlink_task` | N | N | Y | N | Y | Removes task-session link |
+| `roboco_session_get_for_task` | Y | Y | Y | Y | Y | Returns task's sessions |
+| `roboco_group_create` | N | N | Main PM | N | Y | Creates work group |
+
+---
+
+## Message MCP Tools
+
+| Tool | All Agents | Test Case |
+|------|------------|-----------|
+| `roboco_channel_list` | Y | Returns readable/writable channels for agent |
+| `roboco_channel_history` | Y | Returns messages, respects access |
+| `roboco_message_send` | Y | Requires task_id, routes to session |
+| `roboco_message_get` | Y | Fetches single message by ID |
+| `roboco_ask_question` | Y | Wrapper for message_send |
+| `roboco_report_blocker` | Y | Wrapper for message_send |
+| `roboco_session_history_for_task` | Y | Returns task session messages |
+
+---
+
+## Notification MCP Tools
+
+| Tool | Developer | QA | PM | Documenter | Board | Test Case |
+|------|-----------|----|----|------------|-------|-----------|
+| `roboco_notify_list` | Y | Y | Y | Y | Y | Returns pending notifications |
+| `roboco_notify_get` | Y | Y | Y | Y | Y | Fetches single notification |
+| `roboco_notify_ack` | Y | Y | Y | Y | Y | Marks notification acknowledged |
+| `roboco_notify_send` | N | N | Y | N | Y | Sends notification to recipient |
+
+---
+
+## Journal MCP Tools
+
+| Tool | All Agents | Special Access | Test Case |
+|------|------------|----------------|-----------|
+| `roboco_journal_entry` | Y | - | Creates generic entry |
+| `roboco_journal_reflect` | Y | - | Creates reflection for task |
+| `roboco_journal_decision` | Y | - | Logs decision with rationale |
+| `roboco_journal_learning` | Y | - | Logs learning |
+| `roboco_journal_struggle` | Y | - | Logs struggle |
+| `roboco_journal_search` | Y | - | Semantic search own entries |
+| `roboco_journal_stats` | Y | - | Returns entry statistics |
+| `roboco_journal_recent` | Y | - | Returns recent entries |
+| `roboco_journal_read_team` | Y | Cell reads cell, PM reads all | Reads teammate journals |
+| `roboco_journal_scope` | Y | - | Shows accessible journals |
+
+---
+
+## Optimal MCP Tools (Knowledge Base)
+
+| Tool | All Agents | Test Case |
+|------|------------|-----------|
+| `roboco_kb_search` | Y | Semantic search knowledge base |
+| `roboco_rag_query` | Y | RAG query with context |
+| `roboco_kb_stats` | Y | Returns KB statistics |
+| `roboco_kb_index_code` | Y | Indexes code files |
+| `roboco_kb_index_docs` | Y | Indexes documentation |
+| `roboco_tokens_estimate` | Y | Estimates token usage |
+| `roboco_escalate` | Y | Escalates to manager |
+| `roboco_request_approval` | Y | Requests human approval |
+
+---
+
+## Critical Test Scenarios
+
+### 1. Full Developer Workflow
+```
+1. roboco_notify_list() → check for assignments
+2. roboco_task_scan(team="backend") → find pending task
+3. roboco_task_claim(task_id) → claim it
+4. roboco_kb_search("similar work") → research
+5. roboco_task_plan(task_id, ...) → submit plan
+6. roboco_task_start(task_id) → begin work
+7. roboco_message_send(channel, "Starting", task_id) → announce
+8. roboco_task_progress(task_id, "Working", 50) → update
+9. roboco_journal_reflect(task_id, ...) → reflect
+10. roboco_task_submit_verification(task_id) → self-check
+11. roboco_task_submit_qa(task_id) → submit for QA
+```
+
+### 2. Full QA Workflow
+```
+1. roboco_task_scan(team="backend") → find awaiting_qa
+2. roboco_task_claim(task_id) → claim it
+3. roboco_task_start(task_id) → begin review
+4. roboco_journal_read_team(dev_id, task_id) → read dev journey
+5. roboco_task_progress(task_id, "Reviewing", 50)
+6. roboco_journal_reflect(task_id, ...)
+7. roboco_task_qa_pass(task_id) OR roboco_task_qa_fail(task_id, issues)
+```
+
+### 3. Full PM Workflow
+```
+1. roboco_task_scan() → find pending/escalations
+2. roboco_task_claim(task_id)
+3. roboco_task_start(task_id)
+4. roboco_task_plan(task_id, ...)
+5. roboco_task_create({parent_task_id, ...}) → create subtask
+6. roboco_session_create_for_tasks({task_ids}) → create session
+7. roboco_task_activate(subtask_id) → make visible
+8. roboco_notify_send({recipient, task_id}) → notify assignee
+9. roboco_journal_read_team("be-dev-1") → monitor progress
+10. roboco_task_complete(subtask_id) → after full workflow
+```
+
+### 4. Blocking/Unblocking Flow
+```
+Developer:
+1. roboco_task_block(task_id, reason, what_needed)
+2. roboco_message_send(channel, "Blocked on X", task_id)
+3. Wait for resolution...
+4. roboco_task_unblock(task_id) → resume
+
+PM:
+1. roboco_task_scan() → see blocked tasks
+2. roboco_journal_read_team(dev_id, task_id) → understand context
+3. Resolve issue...
+4. roboco_task_unblock(task_id) → unblock for developer
+```
+
+### 5. Escalation Chain
+```
+Developer → Cell PM → Main PM → Board
+be-dev-1 → be-pm → main-pm → product-owner
+
+Test:
+1. roboco_task_escalate(task_id, reason) as be-dev-1
+2. Verify notification goes to be-pm
+3. roboco_task_escalate(task_id, reason) as be-pm
+4. Verify notification goes to main-pm
+```
+
+### 6. Self-Review Prevention
+```
+1. be-dev-1 submits task for QA
+2. be-qa claims and reviews → OK
+3. be-dev-1 tries to claim as QA → FORBIDDEN
+```
+
+### 7. Session Routing
+```
+1. PM creates task with roboco_task_create
+2. PM creates session with roboco_session_create_for_tasks
+3. PM activates task with roboco_task_activate
+4. Developer claims, starts
+5. Developer sends message with task_id → routes to session
+6. Subtasks inherit parent's session automatically
+```
+
+---
+
+## Error Response Format
+
+All errors return:
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Task 123 not found",
+    "details": {...}
+  }
+}
+```
+
+Standard error codes:
+- `NOT_FOUND` - Resource doesn't exist
+- `ACCESS_DENIED` - Permission denied
+- `INVALID_INPUT` - Bad request data
+- `INVALID_STATE` - Wrong status for operation
+- `NOT_AUTHORIZED` - Auth required
+- `ALREADY_LINKED` - Duplicate link
+- `NO_SESSION_FOR_TASK` - Task has no session
+
+---
+
+## Validation Checklist
+
+Before declaring ready:
+
+- [ ] All tools return consistent error format
+- [ ] All role restrictions enforced at MCP layer
+- [ ] All role restrictions enforced at API layer
+- [ ] Session routing works for subtasks (inherits parent session)
+- [ ] Escalation chain validates correctly
+- [ ] Self-review prevention works
+- [ ] Channel access respects permissions
+- [ ] Journal read_team respects cell boundaries
+- [ ] Notifications route to correct recipients
+- [ ] All prompts match available tools
@@ -26,6 +26,7 @@
 | `roboco_task_qa_pass` | ❌ | ❌ | ❌ | ✅ | ❌ |
 | `roboco_task_qa_fail` | ❌ | ❌ | ❌ | ✅ | ❌ |
 | `roboco_task_docs_complete` | ❌ | ❌ | ❌ | ❌ | ✅ |
+| `roboco_task_substitute` | ✅ | ✅ | ✅ | ✅ | ✅ |

 ### Session Tools

@@ -65,6 +66,17 @@
 | `roboco_journal_recent` | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `roboco_journal_read_team` | ✅ | ✅ | ❌ | ❌ | ✅ |

+### Knowledge Base Tools
+
+| Tool | Main PM | Cell PM | Developer | QA | Documenter |
+|------|:-------:|:-------:|:---------:|:--:|:----------:|
+| `roboco_kb_search` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `roboco_rag_query` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `roboco_kb_stats` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `roboco_kb_index_code` | ✅ | ✅ | ✅ | ❌ | ❌ |
+| `roboco_kb_index_docs` | ✅ | ✅ | ❌ | ❌ | ✅ |
+| `roboco_tokens_estimate` | ✅ | ✅ | ✅ | ✅ | ✅ |
+
 ---

 ## Channel Access Permissions
@@ -17,9 +17,18 @@
   │
   ▼
 3. PLAN & BREAKDOWN
-   ├── roboco_task_plan(task_id, approach, steps)
-   ├── Identify which cells need subtasks
-   └── roboco_task_progress(task_id, "Planning complete", 20)
+   │
+   │  roboco_task_plan(task_id, approach, steps)
+   │  roboco_task_progress(task_id, "Planning complete", 20)
+   │
+   │  # REQUIRED: Document your planning decisions
+   │  roboco_journal_decision({
+   │    title: "Task breakdown for [feature]",
+   │    context: "Requirements from board",
+   │    options: ["Option A", "Option B"],
+   │    chosen: "Option A",
+   │    rationale: "Because..."
+   │  })
   │
   ▼
 4. CREATE SUBTASKS (for Cell PMs)
@@ -71,11 +80,21 @@
   │  Loop:
   │  ├── roboco_task_scan() → Check subtask statuses
   │  ├── roboco_channel_history("pm-all") → Cross-cell coordination
+   │  ├── roboco_journal_read_team("be-pm") → Read cell PM progress
   │  ├── Handle escalations from Cell PMs
-   │  └── roboco_task_progress(main_task_id, "X% complete", %)
+   │  ├── roboco_task_progress(main_task_id, "X% complete", %)
+   │  └── roboco_journal_entry({type: "coordination", ...})
   │
   ▼
-9. COMPLETE (when all subtasks done)
+9. REFLECT & COMPLETE (when all subtasks done)
+   │
+   │  # REQUIRED: Reflect before completing
+   │  roboco_journal_reflect({
+   │    task_id: main_task_id,
+   │    what_done: "Coordinated X cells, Y subtasks",
+   │    what_learned: "Cross-cell coordination patterns",
+   │    what_struggled: "Dependency management"
+   │  })
   │
   │  roboco_task_complete(main_task_id)
   │
@@ -189,10 +208,30 @@ AFTER QA + DOCS:
  awaiting_pm_review ──PM completes──► completed
 ```

+## Using Knowledge Base
+
+PMs have full KB access including indexing:
+
+```python
+roboco_kb_search("similar past tasks")         # Find related work
+roboco_rag_query("how did we solve X?")        # AI-generated answers
+roboco_journal_read_team("be-dev-1")           # Read team journals
+
+# Indexing (PM only)
+roboco_kb_index_code(["src/**/*.py"])          # Index code for search
+roboco_kb_index_docs(["docs/**/*.md"])         # Index documentation
+```
+
+See [KNOWLEDGE_BASE.md](./KNOWLEDGE_BASE.md) for full documentation.
+
 ## Key Rules

 1. **Tasks start in BACKLOG** - PM setup phase
 2. **ACTIVATE before anyone can claim** - backlog → pending
 3. **Sessions group related tasks** - create before activating
 4. **Subtasks inherit parent session** - no need to create new session
-5. **Only PM can COMPLETE** - after full workflow (dev → QA → docs → PM review)
+5. **NOTIFY after activation** - roboco_notify_send() REQUIRED
+6. **JOURNAL decisions** - roboco_journal_decision() for task breakdowns
+7. **READ team journals** - roboco_journal_read_team() for monitoring
+8. **REFLECT before complete** - roboco_journal_reflect() REQUIRED
+9. **Only PM can COMPLETE** - after full workflow (dev → QA → docs → PM review)
@@ -39,10 +39,25 @@ QA agents (be-qa, fe-qa, ux-qa) verify developer work meets acceptance criteria.
   │
   │  roboco_task_start(task_id)
   │
+   │  # REQUIRED: Announce to cell
+   │  roboco_message_send({
+   │    channel: "backend-cell",
+   │    content: "Starting QA review of [task title]",
+   │    task_id: task_id
+   │  })
+   │
   │  STATUS: claimed → in_progress
   │
   ▼
-4. REVIEW WORK
+4. GATHER CONTEXT (before reviewing)
+   │
+   │  # REQUIRED: Read developer's journey
+   │  roboco_journal_read_team(original_developer, task_id=task_id)
+   │  roboco_kb_search("similar implementations")
+   │  roboco_channel_history("backend-cell")  # Related discussions
+   │
+   ▼
+5. REVIEW WORK
   │
   │  ┌─────────────────────────────────────────────────────────────────┐
   │  │ Review checklist:                                               │
@@ -52,12 +67,28 @@ QA agents (be-qa, fe-qa, ux-qa) verify developer work meets acceptance criteria.
   │  │ ├── Verify functionality                                        │
   │  │ └── Check code quality                                          │
   │  │                                                                 │
-   │  │ roboco_task_progress(task_id, "Reviewing X", 50)                │
-   │  │ roboco_journal_entry({type: "qa_review", ...})                  │
+   │  │ REQUIRED - Progress updates:                                    │
+   │  │   roboco_task_progress(task_id, "Reviewing X", 50)              │
+   │  │                                                                 │
+   │  │ REQUIRED - Journal your review:                                 │
+   │  │   roboco_journal_entry({type: "qa_review", ...})                │
+   │  │   roboco_journal_decision(...)  # If making judgment calls      │
+   │  │   roboco_journal_struggle(...)  # If issues found               │
   │  └─────────────────────────────────────────────────────────────────┘
   │
   ▼
-5. DECISION
+6. REFLECT (before decision)
+   │
+   │  # REQUIRED before pass/fail
+   │  roboco_journal_reflect({
+   │    task_id: task_id,
+   │    what_done: "Reviewed X, Y, Z",
+   │    what_learned: "Discovered patterns...",
+   │    what_struggled: "Edge cases were unclear"
+   │  })
+   │
+   ▼
+7. DECISION
   │
   ├──── PASS ────────────────────────────────────────────────────────┐
   │                                                                  │
@@ -111,10 +142,25 @@ DECISIONS:
  in_progress ──qa_fail──► needs_revision
 ```

+## Using Knowledge Base
+
+Before reviewing, search for context:
+
+```python
+roboco_kb_search("similar past reviews")       # Find related QA work
+roboco_rag_query("what are common issues?")    # AI-generated insights
+roboco_journal_search("qa patterns")           # Your past reviews
+```
+
+See [KNOWLEDGE_BASE.md](./KNOWLEDGE_BASE.md) for full documentation.
+
 ## Key Rules

 1. **Only claim awaiting_qa** - Can't claim pending tasks
 2. **Cannot self-review** - Can't QA your own dev work
-3. **Thorough notes** - Document what was tested and why
-4. **Clear fail reasons** - Developer needs to know what to fix
-5. **Cannot COMPLETE** - Only PM completes after docs
+3. **MESSAGE when starting** - Announce to cell channel
+4. **READ dev's journey** - roboco_journal_read_team() REQUIRED
+5. **JOURNAL your review** - Document what was tested and why
+6. **REFLECT before decision** - roboco_journal_reflect() REQUIRED
+7. **Clear fail reasons** - Developer needs to know what to fix
+8. **Cannot COMPLETE** - Only PM completes after docs
@@ -144,7 +144,9 @@ roboco_notify_ack(notification_id)
 roboco_task_scan(team="backend")

 # 3. Search knowledge base
-roboco_journal_search("similar work")
+roboco_kb_search("similar work")           # Semantic search
+roboco_rag_query("how does X work?")       # AI-generated answer
+roboco_journal_search("past decisions")    # Your journal

 # 4. Claim and plan
 roboco_task_claim(task_id)
@@ -169,6 +171,9 @@ roboco_message_send({channel: "backend-cell", ...})

 # If stuck
 roboco_task_escalate(task_id, "Need help with X")
+
+# If you can't continue (graceful exit)
+roboco_task_substitute(task_id, "low_context", "Need more context about X")
 ```

 ### Finishing
@@ -126,6 +126,8 @@
 | awaiting_documentation → awaiting_pm_review | Documenter | `roboco_task_docs_complete()` |
 | awaiting_pm_review → completed | PM | `roboco_task_complete()` |
 | any → cancelled | PM | `roboco_task_cancel()` |
+| in_progress → pending/blocked/awaiting_qa | Owner | `roboco_task_substitute()` |
+| in_progress → awaiting_pm_review | Any agent | `roboco_task_submit_pm_review()` |

 ## What Each Role Can Claim

@@ -148,3 +150,34 @@ An agent **CAN claim** even if they have:
 - A task in `blocked` (can work on something else while waiting)

 **Exception:** If claiming a task already assigned to them (PM pre-assigned), the blocking check is skipped for THAT specific task.
+
+## Substitution (Graceful Exit)
+
+Agents can **substitute out** of a task when they cannot continue:
+
+```
+roboco_task_substitute(task_id, reason, details)
+```
+
+| Reason | New Status | When to Use |
+|--------|------------|-------------|
+| `low_context` | pending | Insufficient context to continue safely |
+| `out_of_scope_team` | pending | Task belongs to different team |
+| `out_of_scope_role` | pending | Task requires different role (QA, not dev) |
+| `task_complete` | awaiting_qa | Finished work, releasing for next stage |
+| `max_retries` | pending | Exceeded retry limit, need fresh perspective |
+| `blocked_external` | blocked | Need skills outside your capabilities |
+
+**Key:** Substitution BYPASSES the "can't claim while in_progress" rule. After substituting, you are free to claim new work.
+
+## Direct PM Submission (Alternate Path)
+
+For non-dev tasks that don't need QA review:
+
+```
+roboco_task_submit_pm_review(task_id, notes)
+```
+
+Status: `in_progress → awaiting_pm_review`
+
+Use for: validation tasks, audits, research, or any task assigned directly that doesn't produce code.