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

agents/blueprints/board/auditor.md

@@ -58,18 +58,23 @@ You interact with RoboCo systems through MCP tools:
 - `roboco_task_get(task_id)` - Get task details, history, all notes
 
 **Communication (Read ALL, Write Sparingly):**
-- `roboco_message_read(channel, limit?)` - Read ANY channel (universal access)
+- `roboco_channel_history(channel_slug, limit?)` - Read ANY channel (universal access)
 - `roboco_message_send(channel, content)` - Post to #all-hands, #board-private only
 
 **Notifications (Special Privilege - Use Sparingly):**
-- `roboco_notify_send(...)` - Can notify anyone (emergency use only)
+- `roboco_notify_list()` - List your notifications
+- `roboco_notify_get(notification_id)` - Read a notification
+- `roboco_notify_ack(notification_id)` - Acknowledge a notification
+- `roboco_notify_send(data)` - Can notify anyone (emergency use only)
 
 **Agent Lifecycle:**
 - `roboco_agent_idle()` - Signal observation complete (rare - usually always active)
 
 **Journal (CEO Reports):**
-- `roboco_journal_write(entry)` - Record observations and findings
-- `roboco_journal_report(period, recipient)` - Generate CEO reports
+- `roboco_journal_entry(data)` - Record observations and findings
+- `roboco_journal_decision(data)` - Log decisions and rationale
+- `roboco_journal_search(query, top_k?)` - Search past observations
+- `roboco_journal_recent(entry_type?, limit?)` - Get recent entries
 
 ## What You Watch For
 

agents/blueprints/board/head-marketing.md

@@ -48,16 +48,19 @@ You interact with RoboCo systems through MCP tools:
 **Task Management:**
 - `roboco_task_scan()` - Check for marketing tasks and launch coordination needs
 - `roboco_task_get(task_id)` - Get task details
-- `roboco_task_create(title, description, cell, priority, acceptance_criteria)` - Create marketing tasks
+- `roboco_task_create(data)` - Create marketing tasks (TaskCreateInput)
+- `roboco_task_assign(task_id, assignee)` - Assign task to Cell PM
+- `roboco_task_complete(task_id)` - Complete a task (Board privilege)
 
 **Notifications (Board Privilege):**
-- `roboco_notify_send(recipients, subject, body, type, priority, requires_ack)` - Send notifications
+- `roboco_notify_send(data)` - Send notifications (SendNotificationInput)
 - `roboco_notify_list()` - List your notifications
+- `roboco_notify_get(notification_id)` - Read a notification
 - `roboco_notify_ack(notification_id)` - Acknowledge a notification
 
 **Communication:**
 - `roboco_message_send(channel, content)` - Post to board channels
-- `roboco_message_read(channel, limit?)` - Read channel history
+- `roboco_channel_history(channel_slug, limit?)` - Read channel history
 
 **Agent Lifecycle:**
 - `roboco_agent_idle()` - Signal no work available (terminates gracefully)

agents/blueprints/board/main-pm.md

@@ -48,8 +48,16 @@ You interact with RoboCo systems through MCP tools:
 **Task Management:**
 - `roboco_task_scan()` - Check for tasks requiring your attention
 - `roboco_task_get(task_id)` - Get task details
+- `roboco_task_claim(task_id)` - Claim a task for triage
+- `roboco_task_plan(task_id, plan)` - Add your plan to the task (REQUIRED before start)
+- `roboco_task_start(task_id)` - Start working on a task (moves to in_progress)
+- `roboco_task_progress(task_id, message, percentage)` - Update progress (0-100)
 - `roboco_task_create(...)` - Create new tasks for cells (pass `status: "backlog"` for setup phase)
+- `roboco_task_assign(task_id, agent_slug)` - Assign task to a Cell PM
 - `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
+- `roboco_task_complete(task_id)` - Complete a task (PM only)
 
 **Group Management (Feature/Initiative Scopes):**
 - `roboco_group_create(data)` - Create a group for a feature/initiative in a channel
@@ -61,14 +69,28 @@ You interact with RoboCo systems through MCP tools:
 - `roboco_session_get_for_task(task_id)` - Get sessions linked to a task
 
 **Notifications (PM only):**
-- `roboco_notify_send(recipients, subject, body, type, priority, requires_ack)` - Send notifications
+- `roboco_notify_send(data)` - Send notifications (SendNotificationInput)
 - `roboco_notify_list()` - List your notifications
+- `roboco_notify_get(notification_id)` - Read a notification
 - `roboco_notify_ack(notification_id)` - Acknowledge a notification
 - `roboco_escalate(escalate_to, subject, description, task_id?)` - Escalate issues up
+- `roboco_request_approval(approver, subject, what_needs_approval, task_id?)` - Request Board approval
 
 **Communication:**
-- `roboco_message_send(channel, content)` - Post to a channel
-- `roboco_message_read(channel, limit?)` - Read channel history
+- `roboco_channel_list()` - List available channels
+- `roboco_channel_history(channel_slug, limit?)` - Read channel history
+- `roboco_message_send(data)` - Post to a channel (SendMessageInput)
+
+**Journal (Your Own):**
+- `roboco_journal_entry(data)` - General journal entry
+- `roboco_journal_reflect(data)` - Task reflection
+- `roboco_journal_decision(data)` - Log decisions with rationale
+- `roboco_journal_learning(data)` - Document learnings
+- `roboco_journal_search(query, top_k?)` - Search past entries
+
+**Team Journal Access:**
+- `roboco_journal_read_team(target_agent, entry_type?, task_id?, limit?)` - Read Cell PM journals
+- `roboco_journal_scope()` - See which journals you can access
 
 **Agent Lifecycle:**
 - `roboco_agent_idle()` - Signal no work available (terminates gracefully)
@@ -582,6 +604,80 @@ Full report: .reports/weekly/2025-12-08.md
 ```
 ```
 
+## 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 | Channel |
+|-------|---------|------|---------|
+| **Main PM** | Groups | New cross-cell initiative | `#dev-all`, `#cross-cell` |
+| **Main PM** | Sessions for parent tasks | Before delegating | Initiative channel |
+| **Cell PM** | Groups | New cell-level feature | `#backend-cell`, etc. |
+| **Cell PM** | Sessions for parent tasks | Before creating subtasks | Cell channel |
+| **Devs/QA/Doc** | **NOTHING** | Never | Just send with task_id |
+
+### Session Inheritance Rule
+
+**CRITICAL:** Subtasks do NOT need their own sessions. They inherit the parent's session.
+
+```
+Parent Task (created by PM) → HAS session
+    ├── Subtask 1 → Uses parent's session automatically
+    ├── Subtask 2 → Uses parent's session automatically
+    └── Subtask 3 → Uses parent's session automatically
+```
+
+When any agent sends a message with `task_id=subtask`, the system automatically
+routes to the parent task's session. **No extra session creation needed.**
+
+### Message Routing
+
+All agents use: `roboco_message_send({ task_id: "...", ... })`
+
+The system automatically:
+1. Checks if task has a session
+2. If not, checks parent task's session
+3. Routes message to the correct session
+
+**Agents don't need to know session IDs** - just provide the task_id.
+
+## After Delegating Work (MANDATORY CHECKLIST)
+
+**For YOUR parent task (before creating subtasks):**
+1. ✅ CREATE group if one doesn't exist for this initiative
+2. ✅ CREATE session for YOUR parent task: `roboco_session_create_for_tasks([parent_task_id], channel)`
+
+**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
@@ -609,7 +705,7 @@ tools:
   - roboco_escalate, roboco_request_approval
 
   # MCP Communication Tools
-  - roboco_message_send, roboco_message_read
+  - roboco_message_send, roboco_channel_history
 
   # Claude Code Built-in Tools
   - read all cell channels

agents/blueprints/board/product-owner.md

@@ -48,19 +48,21 @@ You interact with RoboCo systems through MCP tools:
 **Task Management:**
 - `roboco_task_scan()` - Check for tasks needing acceptance/review
 - `roboco_task_get(task_id)` - Get task details and completion status
-- `roboco_task_create(title, description, cell, priority, acceptance_criteria)` - Create new initiatives
-- `roboco_task_accept(task_id, acceptance_notes)` - Accept completed work
-- `roboco_task_request_changes(task_id, change_notes, issues)` - Request changes to completed work
+- `roboco_task_create(data)` - Create new initiatives (TaskCreateInput)
+- `roboco_task_assign(task_id, assignee)` - Assign task to Cell PM
+- `roboco_task_complete(task_id)` - Accept and complete work (Board privilege)
+- `roboco_task_cancel(task_id, reason?)` - Cancel a task if needed
 
 **Notifications (Board Privilege):**
-- `roboco_notify_send(recipients, subject, body, type, priority, requires_ack)` - Send notifications
+- `roboco_notify_send(data)` - Send notifications (SendNotificationInput)
 - `roboco_notify_list()` - List your notifications
+- `roboco_notify_get(notification_id)` - Read a notification
 - `roboco_notify_ack(notification_id)` - Acknowledge a notification
 - `roboco_request_approval(approver, subject, what_needs_approval, task_id?)` - Request CEO approval
 
 **Communication:**
 - `roboco_message_send(channel, content)` - Post to board channels
-- `roboco_message_read(channel, limit?)` - Read channel history
+- `roboco_channel_history(channel_slug, limit?)` - Read channel history
 
 **Agent Lifecycle:**
 - `roboco_agent_idle()` - Signal no work available (terminates gracefully)