pi-orchestrator-config 4.2.0 → 4.3.2

package/rules/55-coms-protocol.md

@@ -1,30 +1,38 @@
+---
+requires: coms_active
+---
 # Coms Protocol — Inter-Agent Communication
 
 ## Overview
 
-Two communication systems are available for talking to other pi sessions:
+P2P communication system for talking to other pi sessions on the same machine.
 
 | System | Activation | Tool prefix | Transport |
 |--------|-----------|-------------|-----------|
 | **P2P** (coms) | `/coms start` | `coms_` | Direct peer-to-peer |
-| **Networked** (coms-net) | `/coms-net start` | `coms_net_` | Hub server relay |
-
-Both systems can be active. When asked to list peers, send messages, or interact with coms —
-**try both** `coms_list` and `coms_net_list`. If one fails, use the other.
-Don't assume which system is active.
 
 ## Activation
 
-Tools are unavailable until the user runs `/coms start` (P2P) or `/coms-net start` (networked).
-Use `coms_list` / `coms_net_list` to see connected peers.
+Tools are unavailable until the user runs `/coms start`.
+Use `coms_list` to see connected peers.
 
 ## Tool Reference
 
-| Action | P2P (coms) | Networked (coms-net) |
-|--------|-----------|---------------------|
-| List peers | `coms_list` | `coms_net_list` |
-| Send message | `coms_send` | `coms_net_send` |
-| Poll for response | `coms_get` | `coms_net_get` |
+| Action | Tool |
+|--------|------|
+| List peers | `coms_list` |
+| Send message | `coms_send` |
+| Poll for response | `coms_get` |
+| Clear your queued msgs | `coms_queue_clear` |
+| Delete queued msg | `coms_queue_delete` |
+| Edit queued msg | `coms_queue_edit` |
+| Prioritize queued msg | `coms_queue_prioritize` |
+| View local queue | `/coms-queue` |
+| Create task on peer | `coms_tasks_create` |
+| Delete task on peer | `coms_task_delete` |
+| List peer's tasks | `coms_task_list` |
+| Get peer's task | `coms_task_get` |
+| Update task on peer | `coms_task_update` |
 
 ## Inbound Messages — How to Reply
 
@@ -36,15 +44,50 @@ Inbound messages appear as `[from <peer> @ <cwd>] <message>`. Your assistant tex
 
 To start a conversation: call the send tool, then **end your turn**.
 The peer's response auto-delivers as a followUp message — no polling needed.
-Use `coms_get` / `coms_net_get` only for non-blocking status checks.
+Use `coms_get` only for non-blocking status checks.
 
 ## Message Queue
 
 Inbound messages process in FIFO order. If multiple arrive while the peer is busy, they queue — each gets its own turn and response, nothing is dropped.
 
+## Queue Management
+
+When sending corrected or updated instructions that supersede previous messages, use queue management to prevent peers from processing stale messages:
+
+### Clear previous messages before sending
+
+```text
+coms_send(target="peer", prompt="Updated instructions", clearPrevious=true)
+```
+
+This clears all YOUR pending (unprocessed) messages from the peer's queue before delivering the new one. Use when previous messages are outdated.
+
+### Manual queue operations
+
+| Action | Tool |
+|--------|------|
+| Clear all your pending | `coms_queue_clear(target)` |
+| Delete specific message | `coms_queue_delete(target, msg_id)` |
+| Edit queued message | `coms_queue_edit(target, msg_id, new_content)` |
+| Move to front | `coms_queue_prioritize(target, msg_id)` |
+
+**Rules:**
+
+- You can only manage YOUR OWN messages in a peer's queue
+- Cannot touch messages from other senders
+- Cannot touch the message currently being processed
+- `msg_id` is returned by `coms_send` — track it to manage later
+- Use `clearPrevious` when sending corrections — it's the most common pattern
+
+**Note:** Queue management operations (`coms_queue_edit`, `coms_queue_delete`,
+`coms_queue_prioritize`) are fire-and-forget — they receive transport-level
+acknowledgement but do not confirm whether the target actually applied the change.
+A dequeue race, not-found `msg_id`, or ownership mismatch can cause silent no-ops.
+Callers should not assume success without verifying via subsequent responses.
+
 ## Structured Task Delegation
 
-Use the `tasks` parameter to delegate structured work items alongside messages. Tasks appear in the peer's task widget (requires `@tintinweb/pi-tasks`):
+Use the `tasks` parameter to delegate structured work items alongside messages. Tasks appear in the peer's task widget:
 
 ```text
 coms_send(target="coder", prompt="Implement these features", tasks=[
@@ -53,11 +96,34 @@ coms_send(target="coder", prompt="Implement these features", tasks=[
 ])
 ```
 
+### Recommended Pattern
+
+1. Create tasks on the peer via `coms_tasks_create`
+   - Automatically adds a "Report completion to sender" task, blocked by all other tasks
+   - Automatically sends a message to the peer to start working
+2. Monitor progress via `coms_task_list` / `coms_task_get` (no message sent)
+3. The peer works through tasks, updates status, reports when done via the final report task
+
+## Remote Task Management
+
+Manage tasks on peer sessions directly — no message sent, no peer notification:
+
+| Tool | Description |
+|------|-------------|
+| `coms_tasks_create` | Create a task on peer's session (with coms_origin tracking) |
+| `coms_task_update` | Update a task YOU created on peer's session |
+| `coms_task_delete` | Delete a task YOU created on peer's session |
+| `coms_task_list` | List all tasks on peer's session |
+| `coms_task_get` | Get a specific task from peer's session |
+
+Ownership: update/delete only work on tasks with matching `coms_origin` — you can only modify tasks you created.
+
+Tasks are written directly to the peer's task store file. The peer's fs.watch detects the change and updates their task widget instantly.
+
 ## Key Rules
 
 1. **Responses auto-deliver** — after send, end your turn; the reply arrives as a followUp
 2. **Never call send tools to reply** to inbound messages — your assistant text is the reply
 3. **Always check peers first** — use list tools before sending
-4. **Try both systems** — try `coms_` and `coms_net_` when system isn't specified
-5. **Messages are never lost** — busy peers queue messages in FIFO order
-6. **Use tasks for structured work** — use `tasks` parameter instead of prose lists
+4. **Messages are never lost** — busy peers queue messages in FIFO order
+5. **Use tasks for structured work** — use `tasks` parameter instead of prose lists

package/rules/60-task-tracking.md

@@ -45,7 +45,9 @@ Answer the question, then resume the next unchecked task immediately — the per
 ## Integration & Key Rules
 
 Task tracking works alongside existing workflow rules — include issue-first, code review, and documentation steps as individual tasks.
+{{IF:task_reminder_enabled}}
 Tasks are code-enforced (reminders after 4+ ignored turns).
+{{/IF}}
 Never abandon tasks — if scope changes, use `TaskUpdate` with `status: "deleted"` to remove obsolete tasks; the task list is your contract.
 
 ---