A2A wiring up

docs/rag/architecture/config-reference.md

@@ -58,7 +58,7 @@ Environment variables for RoboCo (prefix: `ROBOCO_`).
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `ROBOCO_LOCAL_LLM_MODEL` | `glm-4.6:cloud` | Local LLM for RAG |
+| `ROBOCO_LOCAL_LLM_MODEL` | `glm-4.7:cloud` | Local LLM for RAG |
 | `ROBOCO_LOCAL_LLM_BASE_URL` | `http://roboco-ollama:11434/v1` | OpenAI-compat API |
 | `ROBOCO_OLLAMA_BASE_URL` | `http://roboco-ollama:11434` | Native Ollama API |
 

docs/rag/architecture/tool-permissions.md

@@ -0,0 +1,65 @@
+# Tool Permissions by Role
+
+## Overview
+
+Agents have role-specific tool permissions enforced via Claude Code settings.
+Native tools are blocked; use `roboco_*` MCP tools instead.
+
+## Developer
+
+**Allowed:**
+- `roboco_task_*` - task lifecycle
+- `roboco_git_*` - all git operations
+- `roboco_test_*` - run tests, lint, format
+- `roboco_journal_*` - journaling
+- `roboco_kb_*`, `roboco_rag_*` - knowledge base
+- `Read(*)` - read any file
+- `Write/Edit` - workspace only
+
+**Blocked:**
+- `Bash(git:*)` - use roboco_git_* instead
+- `Write/Edit` outside workspace
+
+**Workspace:** `/data/workspaces/{project}/{team}/{agent-id}/`
+
+## QA
+
+**Allowed:**
+- `roboco_git_status`, `roboco_git_log`, `roboco_git_diff` - read-only
+- `roboco_test_*` - run tests
+- `roboco_task_qa_pass`, `roboco_task_qa_fail`
+- `Read(*)` - read any file
+
+**Blocked:**
+- `roboco_git_commit`, `roboco_git_push` - QA doesn't write code
+- All `Write/Edit` - review only
+
+## Documenter
+
+**Allowed:**
+- `roboco_docs_*` - documentation tools
+- `roboco_git_*` - all git operations
+- `Write/Edit` in `/app/docs/**` only
+
+**Blocked:**
+- `Write/Edit` outside docs directory
+
+## PM (Cell PM, Main PM)
+
+**Allowed:**
+- `roboco_git_*` - all git operations
+- `roboco_docs_*` - documentation
+- `roboco_task_*` - full task management
+- `roboco_notify_send` - send notifications
+
+**Blocked:**
+- `Bash(git:*)` - use roboco_git_*
+
+## Auditor
+
+**Allowed:**
+- `roboco_git_status`, `roboco_git_log`, `roboco_git_diff` - read-only
+- `Read(*)` - read any file
+
+**Blocked:**
+- All write operations - observer role

docs/rag/roles/auditor.md

@@ -61,6 +61,18 @@ roboco_task_create({
 })
 ```
 
+## Tool Restrictions
+
+**Read-only observer.** Cannot modify anything.
+
+| Allowed | Blocked |
+|---------|---------|
+| `roboco_git_status/log/diff` | All `Write/Edit` |
+| `Read(*)` | All git write operations |
+| `roboco_kb_search` | Native git commands |
+
+See: `roboco_kb_search("tool permissions")`
+
 ## Key Tools
 
 | Tool | Purpose |
@@ -74,6 +86,13 @@ roboco_task_create({
 
 The Auditor primarily observes and reports. Direct intervention is NOT the Auditor's role - issues are escalated to CEO for action.
 
+## A2A
+
+```python
+roboco_agent_request("ceo", "escalation", "Found issue...", task_id)
+roboco_a2a_check()  # Check inbox
+```
+
 ## Escalation
 
 Report directly to CEO when:

docs/rag/roles/cell-pm.md

@@ -99,6 +99,18 @@ roboco_notify_list()
 roboco_journal_read_team("be-dev-1", task_id=task_id)
 ```
 
+## Tool Restrictions
+
+**Full MCP access, but use `roboco_git_*` not native git.**
+
+| Allowed | Blocked |
+|---------|---------|
+| `roboco_git_*` | Native `Bash(git:*)` |
+| `roboco_docs_*` | - |
+| `roboco_notify_send` | - |
+
+See: `roboco_kb_search("tool permissions")`
+
 ## Key Tools
 
 | Tool | Purpose |
@@ -120,6 +132,13 @@ When receiving escalation:
 4. Communicate decision
 5. Unblock if needed: `roboco_task_unblock(task_id)`
 
+## A2A
+
+```python
+roboco_agent_request("fe-pm", "coordination", "Cross-cell dependency on...", task_id)
+roboco_a2a_check()  # Check inbox
+```
+
 ## Escalation
 
 Escalate to Main PM when:

docs/rag/roles/ceo.md

@@ -27,6 +27,10 @@
 - Cancel tasks (by design - CEO observes/approves, doesn't manage)
 - Should not be doing day-to-day task management
 
+## Tool Note
+
+Prefer `roboco_git_*` MCP tools over native git for audit trail.
+
 ## CEO Approval Workflow
 
 When PM escalates major task:
@@ -63,6 +67,13 @@ CEO is the final escalation target. Issues escalate:
 Developer → Cell PM → Main PM → Product Owner → CEO
 ```
 
+## A2A
+
+```python
+roboco_agent_request("product-owner", "clarification", "...", task_id)
+roboco_a2a_check()  # Check inbox
+```
+
 ## Communication
 
 CEO has access to all channels including:

docs/rag/roles/developer.md

@@ -36,11 +36,28 @@
 ## Task Flow
 
 ```
-pending → claim → start → work → submit_verification → submit_qa
-                    ↑                                      ↓
-                    └──────── needs_revision ←──── (QA fails)
+pending → claim → plan → start → work → submit_verification → submit_qa
+                   ↑                                              ↓
+                   └──────────── needs_revision ←──────── (QA fails)
 ```
 
+## Workflow States
+
+| State | Meaning |
+|-------|---------|
+| `NEEDS_PLAN` | Must call `roboco_task_plan()` first |
+| `WAITING_FOR_BRANCH` | PM must create branch (git tasks) |
+| `READY_TO_START` | Call `roboco_task_start()` |
+| `EXECUTING` | Work in progress |
+| `REVISION_REQUIRED` | Fix QA/PM feedback |
+
+## Tool Restrictions
+
+Use `roboco_*` MCP tools, not native Claude tools:
+- Git: `roboco_git_*` (native git blocked)
+- Write/Edit: workspace only
+- See: `roboco_kb_search("tool permissions")`
+
 ## Key Tools
 
 | Tool | Purpose |
@@ -67,6 +84,18 @@ pending → claim → start → work → submit_verification → submit_qa
 4. Write journal reflection: `roboco_journal_reflect()`
 5. Push branch: `roboco_git_push()`
 
+## A2A Collaboration
+
+Direct peer-to-peer messaging:
+
+```python
+# Request review (task_id required)
+roboco_agent_request("be-qa", "code_review", "Please review", task_id)
+
+# Check inbox for incoming messages
+roboco_a2a_check()
+```
+
 ## Escalation
 
 Escalate to Cell PM when:

docs/rag/roles/documenter.md

@@ -41,6 +41,18 @@ awaiting_documentation → claim → start → write → docs_complete
                                               awaiting_pm_review
 ```
 
+## Tool Restrictions
+
+**Write access limited to docs directory only.**
+
+| Allowed | Blocked |
+|---------|---------|
+| `roboco_docs_*` | `Write/Edit` outside `/app/docs/` |
+| `roboco_git_*` | Native git commands |
+| `Write/Edit` in `/app/docs/**` | Source code modification |
+
+See: `roboco_kb_search("tool permissions")`
+
 ## Key Tools
 
 | Tool | Purpose |
@@ -121,6 +133,13 @@ If documenter == original_developer, the claim is FORBIDDEN.
 2. Journal your work: `roboco_journal_entry({type: "documentation"})`
 3. Write reflection: `roboco_journal_reflect()`
 
+## A2A
+
+```python
+roboco_agent_request("be-dev-1", "clarification", "Need context on...", task_id)
+roboco_a2a_check()  # Check inbox
+```
+
 ## Escalation
 
 Escalate to Cell PM when:

docs/rag/roles/head-marketing.md

@@ -27,6 +27,10 @@
 - Claim tasks (board observes/approves)
 - Clear/refresh KB indexes
 
+## Tool Note
+
+Use `roboco_git_*` MCP tools, not native git commands.
+
 ## Key Permissions
 
 | Permission | Access |
@@ -46,9 +50,14 @@ Escalates directly to CEO.
 Head Marketing → CEO
 ```
 
-## A2A Skills
+## A2A
 
-- **Market Analysis**: Provide market context and analysis
+```python
+roboco_agent_request("product-owner", "market_analysis", "...", task_id)
+roboco_a2a_check()  # Check inbox
+```
+
+Skills: market_analysis
 
 ## Communication
 

docs/rag/roles/main-pm.md

@@ -80,6 +80,19 @@ roboco_journal_read_team("be-pm")
 roboco_journal_read_team("fe-pm")
 ```
 
+## Tool Restrictions
+
+**Full MCP access, but use `roboco_git_*` not native git.**
+
+| Allowed | Blocked |
+|---------|---------|
+| `roboco_git_*` | Native `Bash(git:*)` |
+| `roboco_docs_*` | - |
+| `roboco_notify_send` | - |
+| All task management | - |
+
+See: `roboco_kb_search("tool permissions")`
+
 ## Key Tools
 
 | Tool | Purpose |
@@ -97,6 +110,13 @@ When Cell PM escalates:
 3. Coordinate with other Cell PMs if needed
 4. Make decision or escalate to Board
 
+## A2A
+
+```python
+roboco_agent_request("be-pm", "coordination", "...", task_id)
+roboco_a2a_check()  # Check inbox
+```
+
 ## Escalation
 
 Escalate to Product Owner when:

docs/rag/roles/product-owner.md

@@ -28,6 +28,10 @@
 - Claim tasks (board observes/approves)
 - Clear/refresh KB indexes
 
+## Tool Note
+
+Use `roboco_git_*` MCP tools, not native git commands.
+
 ## Key Permissions
 
 | Permission | Access |
@@ -48,10 +52,14 @@ Escalates to CEO for final authority.
 Main PM → Product Owner → CEO
 ```
 
-## A2A Skills
+## A2A
 
-- **Requirements Clarification**: Clarify product requirements and priorities
-- **Feature Approval**: Approve feature implementations
+```python
+roboco_agent_request("main-pm", "coordination", "...", task_id)
+roboco_a2a_check()  # Check inbox
+```
+
+Skills: requirements_clarification, feature_approval
 
 ## Communication
 

docs/rag/roles/qa.md

@@ -43,6 +43,18 @@ awaiting_qa → claim → start → review → pass/fail
                           fail: needs_revision (back to developer)
 ```
 
+## Tool Restrictions
+
+**You are read-only.** Cannot modify code or commit.
+
+| Allowed | Blocked |
+|---------|---------|
+| `roboco_git_status/log/diff` | `roboco_git_commit/push` |
+| `roboco_test_*` | All `Write/Edit` |
+| `Read(*)` | Native git commands |
+
+See: `roboco_kb_search("tool permissions")`
+
 ## Key Tools
 
 | Tool | Purpose |
@@ -98,6 +110,15 @@ The `original_developer` is tracked in `quick_context`. If QA agent == original
 2. Write reflection: `roboco_journal_reflect()`
 3. Provide clear reasoning in pass/fail notes
 
+## A2A Requests
+
+Developers send code review requests via A2A:
+
+```python
+# Check inbox (auto-notified via hook)
+roboco_a2a_check()
+```
+
 ## Escalation
 
 Escalate to Cell PM when:

docs/rag/tools/a2a-tools.md

@@ -0,0 +1,82 @@
+# A2A (Agent-to-Agent) Tools
+
+## Overview
+
+A2A enables direct peer-to-peer communication between agents about existing tasks.
+
+**Key points:**
+- Direct HTTP when both agents online (no notification)
+- Fallback to notification only when target offline
+- All requests MUST reference an existing `task_id`
+
+## Tools
+
+### roboco_agent_discover
+
+Find agents by role, team, or skill.
+
+```python
+roboco_agent_discover(
+    role="developer",      # Optional: developer, qa, documenter, cell_pm, etc.
+    team="backend",        # Optional: backend, frontend, ux_ui
+    skill="code_review"    # Optional: specific capability
+)
+```
+
+### roboco_agent_request
+
+Send A2A message to another agent.
+
+```python
+roboco_agent_request(
+    target_agent="be-qa",
+    skill="code_review",
+    message="Please review my changes",
+    task_id="abc123...",              # REQUIRED
+    options={"urgent": False}         # Optional: priority queue
+)
+```
+
+**Returns:** `{status, delivery, message_id}` where `delivery` is `"direct"` or `"notification"`.
+
+### roboco_a2a_check
+
+Poll your inbox for incoming A2A messages.
+
+```python
+roboco_a2a_check()
+```
+
+**Returns:** `{messages: [...], count: N}` - messages from other agents.
+
+**Note:** A hook automatically notifies you of pending messages after tool calls.
+
+## Common Use Cases
+
+| Need | Action |
+|------|--------|
+| Code review | `roboco_agent_request("be-qa", "code_review", "...", task_id)` |
+| Clarification | `roboco_agent_request("be-pm", "clarification", "...", task_id)` |
+| Find reviewer | `roboco_agent_discover(skill="code_review")` |
+| Urgent help | `roboco_agent_request(..., options={"urgent": True})` |
+
+## When to Use A2A
+
+- Communication about an existing task you're working on
+- Requesting code review, clarification, or help
+- Notifying another agent about task progress
+- Urgent questions needing immediate attention
+
+## When NOT to Use A2A
+
+- Creating new work → Only PMs create tasks via `roboco_task_create`
+- Task assignments → PM assigns via `roboco_task_assign`
+- Escalations → Use `roboco_task_escalate`
+- Formal notifications → Use `roboco_notify_send` (PM only)
+
+## Task Creation Rules
+
+Only Cell PMs and Main PM can create tasks (subtasks).
+If an agent receives an A2A request that requires new work:
+1. Escalate to PM: `roboco_task_escalate(task_id, "Needs subtask for...")`
+2. PM decides whether to create a subtask

docs/rag/troubleshooting/blocked-tools.md

@@ -0,0 +1,56 @@
+# Blocked Tools
+
+## Native Git Commands Blocked
+
+**Symptom:** `Bash(git commit)` or similar git command denied
+
+**Cause:** Native git commands are blocked for all agents
+
+**Solution:** Use MCP tools instead:
+| Blocked | Use Instead |
+|---------|-------------|
+| `git commit` | `roboco_git_commit()` |
+| `git push` | `roboco_git_push()` |
+| `git status` | `roboco_git_status()` |
+| `git diff` | `roboco_git_diff()` |
+| `git log` | `roboco_git_log()` |
+
+## Write/Edit Outside Workspace
+
+**Symptom:** `Write()` or `Edit()` denied for a file path
+
+**Cause:** Write operations restricted to your workspace
+
+**Solution:**
+- Developers: Only write in `/data/workspaces/{project}/{team}/{agent-id}/`
+- Documenters: Only write in `/app/docs/`
+- QA: No write access (review only)
+
+## QA Cannot Commit
+
+**Symptom:** `roboco_git_commit()` denied for QA agent
+
+**Cause:** QA role is read-only, cannot modify code
+
+**Solution:** QA reviews and provides feedback. Developers make fixes.
+
+## NO_PLAN Error
+
+**Symptom:** `roboco_task_start()` returns NO_PLAN error
+
+**Cause:** Task has no plan submitted
+
+**Solution:** Call `roboco_task_plan()` before `roboco_task_start()`
+
+See: `roboco_kb_search("task planning workflow")`
+
+## WAITING_FOR_BRANCH
+
+**Symptom:** Can't start git task, state is WAITING_FOR_BRANCH
+
+**Cause:** PM hasn't created the branch yet
+
+**Solution:**
+1. Message PM to create branch
+2. Or escalate: `roboco_task_escalate(task_id, "Need branch")`
+3. Wait for branch_name to be set on task

docs/rag/troubleshooting/common-issues.md

@@ -120,3 +120,24 @@ roboco_docs_write({
 - Check existing: `roboco_docs_list(task_id)` or `roboco_kb_search("topic")`
 
 **Note**: `roboco_docs_write()` auto-deduplicates via RAG by **content similarity**. If content is semantically similar (~75%+), it updates instead of creating new.
+
+## A2A Message Not Delivered
+
+**Problem**: Sent A2A message but no response
+
+**Check**:
+1. Did you include `task_id`? (required)
+2. Check delivery status in response: `"direct"` or `"notification"`
+3. If `"notification"` - target was offline, will be spawned
+
+**Solutions**:
+- Direct delivery: Target should check `roboco_a2a_check()`
+- Notification delivery: Wait for target to be spawned
+
+## A2A SDK Server Unavailable
+
+**Error**: "SDK Server is not available"
+
+**Cause**: SDK Server not running in container
+
+**Solution**: SDK Server starts automatically with agent container. If error persists, container may need restart.

docs/rag/workflows/a2a-collaboration.md

@@ -0,0 +1,74 @@
+# A2A Collaboration Workflow
+
+## Overview
+
+Agents communicate directly via SDK Server (port 9000) for true peer-to-peer messaging.
+
+**Key:** A2A requires `task_id` - it's about existing tasks, NOT task creation.
+
+## Flow
+
+```
+1. Discover → roboco_agent_discover(role, team, skill)
+2. Request  → roboco_agent_request(target, skill, message, task_id)
+3. Check    → roboco_a2a_check() polls your inbox (auto-notified via hook)
+4. Respond  → Work on task or reply via roboco_agent_request
+```
+
+## Delivery
+
+| Target State | Delivery | Creates Notification? |
+|--------------|----------|----------------------|
+| Online | Direct HTTP to SDK | NO |
+| Offline | Fallback via API | YES (spawns target) |
+
+## Example
+
+```python
+# Request code review for task ABC123
+result = roboco_agent_request(
+    target_agent="be-qa",
+    skill="code_review",
+    message="Please review my changes",
+    task_id="ABC123"
+)
+# result.delivery = "direct" or "notification"
+
+# Check for incoming messages
+inbox = roboco_a2a_check()
+# inbox.messages = [{from, task_id, skill, message, priority}, ...]
+```
+
+## Urgency
+
+```python
+roboco_agent_request(..., options={"urgent": True})  # Priority queue
+```
+
+## Agent Skills
+
+| Role | Skills |
+|------|--------|
+| Developer | `code_review`, `implementation`, `debugging`, `revision` |
+| QA | `code_review`, `testing`, `qa_review` |
+| Documenter | `documentation`, `api_docs` |
+| PM | `task_planning`, `coordination`, `clarification` |
+
+## Task Creation Rules
+
+**Only PMs can create tasks.**
+
+If you receive an A2A request that needs new work:
+1. Escalate: `roboco_task_escalate(task_id, "Needs subtask for X")`
+2. PM decides whether to create subtask
+
+## Permissions
+
+All agents can:
+- Discover other agents
+- Send A2A requests (must include task_id)
+- Check request status
+
+All agents CANNOT:
+- Create tasks via A2A (no automatic task creation)
+- Send A2A without a task_id

docs/rag/workflows/task-planning.md

@@ -0,0 +1,49 @@
+# Task Planning Workflow
+
+## Overview
+
+Planning is **required** before starting work. The workflow enforces:
+```
+CLAIM → PLAN → START → EXECUTE
+```
+
+## Workflow States
+
+| State | Meaning | Next Step |
+|-------|---------|-----------|
+| `NEEDS_PLAN` | Task claimed, no plan yet | Call `roboco_task_plan()` |
+| `WAITING_FOR_BRANCH` | Plan approved, git task needs branch | PM creates branch |
+| `READY_TO_START` | Plan approved, ready to work | Call `roboco_task_start()` |
+| `EXECUTING` | Work in progress | Continue development |
+| `REVISION_REQUIRED` | QA/PM requested changes | Reclaim and fix |
+
+## Submitting a Plan
+
+```
+roboco_task_plan(task_id, {
+    "approach": "High-level implementation strategy",
+    "sub_tasks": [
+        {"title": "Step 1", "description": "First action"},
+        {"title": "Step 2", "description": "Second action"}
+    ],
+    "risks": ["Potential blockers or issues"],
+    "open_questions": ["Clarifications needed from PM"]
+})
+```
+
+## Cannot Start Without Plan
+
+Calling `roboco_task_start()` without a plan returns:
+- Error code: `NO_PLAN`
+- Message: "Cannot start without a plan"
+- Hint: Submit plan first
+
+## Git Tasks Need Branch
+
+For tasks with `requires_git=True`:
+1. Submit plan
+2. PM creates branch: `roboco_git_create_branch()`
+3. Task gets `branch_name` field set
+4. Then you can call `roboco_task_start()`
+
+If no branch: workflow state = `WAITING_FOR_BRANCH`