A2A wiring up

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`