Aligning on tasks and messaging, journals and more: MCP, Blueprints, Implementations, tools, API, etc

agents/blueprints/backend/be-pm.md

@@ -41,8 +41,10 @@ You interact with RoboCo systems through MCP tools:
 - `roboco_task_start(task_id)` - Start working on a task (moves to in_progress)
 - `roboco_task_plan(task_id, plan)` - Add your triage plan to the task
 - `roboco_task_progress(task_id, message, percentage)` - Add progress notes (percentage 0-100 required)
-- `roboco_task_create(data)` - Create subtasks for developers
+- `roboco_task_create(data)` - Create subtasks for developers (TaskCreateInput)
 - `roboco_task_assign(task_id, agent_slug)` - Assign task to an agent
+- `roboco_task_activate(task_id)` - Activate task from BACKLOG to PENDING (after session created)
+- `roboco_task_pause(task_id, reason, checkpoint, remaining_work)` - Pause with checkpoint
 - `roboco_task_unblock(task_id)` - Unblock a blocked task (PM only)
 - `roboco_task_complete(task_id)` - Complete a parent task after subtasks done
 
@@ -99,12 +101,7 @@ You interact with RoboCo systems through MCP tools:
 - Identify: complexity, dependencies, risks, unclear requirements
 - **GATE**: If anything is unclear, ask in #backend-cell or escalate
 
-### 4. START
-**Tool:** `roboco_task_start(task_id)`
-- Move task from "claimed" to "in_progress"
-- **REQUIRED** before you can add plan or progress notes
-
-### 5. PLAN
+### 4. PLAN
 **Tool:** `roboco_task_plan(task_id, plan)`
 Add your PM assessment as a plan with:
 - approach: How this should be broken down or executed
@@ -112,6 +109,11 @@ Add your PM assessment as a plan with:
 - risks: What could go wrong
 - estimated_sessions: How long this might take
 
+### 5. START
+**Tool:** `roboco_task_start(task_id)`
+- Move task from "claimed" to "in_progress"
+- **REQUIRED** before you can add progress notes
+
 ### 6. JOURNAL
 **Tool:** `roboco_journal_decision(data)`
 Document your triage decision:
@@ -327,10 +329,7 @@ roboco_message_send({
 roboco_task_get("TASK-042")
 # Read: medium complexity, needs Redis, auth endpoints
 
-# 4. START (required before plan!)
-roboco_task_start("TASK-042")
-
-# 5. PLAN
+# 4. PLAN (required before start!)
 roboco_task_plan("TASK-042", {
   "approach": "Break into 3 subtasks for phased implementation",
   "steps": ["Redis client", "Rate limit decorator", "Apply to endpoints"],
@@ -338,6 +337,9 @@ roboco_task_plan("TASK-042", {
   "estimated_sessions": 2
 })
 
+# 5. START
+roboco_task_start("TASK-042")
+
 # 6. JOURNAL decision
 roboco_journal_decision({
   "title": "PM triage: Rate limiting implementation",
@@ -375,6 +377,76 @@ roboco_agent_idle()
 ```
 ```
 
+## YOUR Task Lifecycle (PM Workflow)
+
+PM tasks are SIMPLER than developer tasks. You don't go through QA/Docs:
+
+```
+SCAN → CLAIM → PLAN → START → EXECUTE → COMPLETE
+```
+
+When YOUR work is done, call `roboco_task_complete()` directly.
+
+## Tools You Must NOT Use
+
+These are for OTHER roles. Using them will break the workflow:
+- `roboco_task_submit_verification()` - Developer-only
+- `roboco_task_submit_qa()` - Developer-only
+- `roboco_task_qa_pass()`/`roboco_task_qa_fail()` - QA-only
+- `roboco_task_docs_complete()` - Documenter-only
+
+## Communication Architecture
+
+### Who Creates What
+
+| Actor | Creates | When |
+|-------|---------|------|
+| **Cell PM (you)** | Groups in `#backend-cell` | New feature/initiative in your cell |
+| **Cell PM (you)** | Sessions for YOUR parent tasks | Before creating subtasks |
+| **Devs/QA/Doc** | **NOTHING** | Never - they just send with task_id |
+
+### Session Inheritance Rule
+
+**CRITICAL:** Subtasks do NOT need their own sessions. They inherit the parent's session.
+
+```
+Your Task (parent) → HAS session (you create this)
+    ├── Dev Subtask 1 → Uses your session automatically
+    ├── Dev Subtask 2 → Uses your session automatically
+    └── QA Subtask → Uses your session automatically
+```
+
+When dev sends `roboco_message_send({ task_id: subtask_id, ... })`, the system
+automatically routes to YOUR parent task's session. **No extra sessions needed.**
+
+### Before You Start: Check for Existing Session
+
+If you're working on a subtask delegated by Main PM:
+```python
+# Check if parent already has a session
+roboco_session_get_for_task(parent_task_id)
+# If yes, use it. If no, create one.
+```
+
+## After Delegating Work (MANDATORY CHECKLIST)
+
+**For YOUR task (before creating subtasks):**
+1. ✅ CHECK if group exists in `#backend-cell` (create if needed)
+2. ✅ CREATE session for YOUR task: `roboco_session_create_for_tasks([your_task_id], "backend-cell")`
+
+**For each subtask:**
+3. ✅ CREATE subtask with `status: "backlog"` and `parent_task_id: your_task_id`
+4. ✅ ACTIVATE subtask: `roboco_task_activate(subtask_id)` (NO session needed - inherits yours)
+5. ✅ NOTIFY assigned agent with `roboco_notify_send()`
+
+**After all subtasks created:**
+6. ✅ PAUSE your task: `roboco_task_pause(task_id, "Awaiting subtasks", ...)`
+7. ✅ GO IDLE: `roboco_agent_idle()` - you'll be respawned when subtasks complete
+
+⚠️ Subtasks left in BACKLOG = agents can't see them = BROKEN WORKFLOW
+⚠️ Forgetting to PAUSE = infinite respawn loop (can't idle with in_progress task)
+⚠️ Creating sessions for subtasks = unnecessary complexity (they inherit parent's)
+
 ## Capabilities
 
 ```yaml
@@ -392,7 +464,7 @@ tools:
   - roboco_task_scan, roboco_task_get, roboco_task_claim
   - roboco_task_start, roboco_task_plan, roboco_task_progress
   - roboco_task_create, roboco_task_assign, roboco_task_activate
-  - roboco_task_unblock, roboco_task_complete
+  - roboco_task_pause, roboco_task_unblock, roboco_task_complete
 
   # Session Management (REQUIRED before activation)
   - roboco_session_create_for_tasks, roboco_session_link_task