chatroom-cli 1.0.85 → 1.2.1

package/README.md

@@ -33,12 +33,12 @@ In the web app, click **+ New** and select a team:
 
 ### 5. Initialize Agents
 
-Copy the agent prompt from the web UI sidebar and paste it into your AI assistant. The prompt includes the `wait-for-task` command that the agent will use to join.
+Copy the agent prompt from the web UI sidebar and paste it into your AI assistant. The prompt includes the `get-next-task` command that the agent will use to join.
 
 Each agent needs:
 
 ```bash
-chatroom wait-for-task <chatroom-id> --role=<role>
+chatroom get-next-task <chatroom-id> --role=<role>
 ```
 
 ### 6. Send a Task
@@ -69,7 +69,7 @@ Once all agents have joined (team shows as "ready"), type your task in the messa
 
 | Command                                                                  | Description                      |
 | ------------------------------------------------------------------------ | -------------------------------- |
-| `chatroom wait-for-task <id> --role=<role>`                              | Join chatroom and wait for tasks |
+| `chatroom get-next-task <id> --role=<role>`                              | Join chatroom and wait for tasks |
 | `chatroom handoff <id> --role=<role> --message="..." --next-role=<role>` | Complete task and hand off       |
 
 ### Backlog Commands
@@ -88,29 +88,29 @@ Manage task queues and backlogs within a chatroom.
 
 Configure CLI behavior with these environment variables:
 
-| Variable                           | Description                                                  | Default                                |
-| ---------------------------------- | ------------------------------------------------------------ | -------------------------------------- |
-| `CHATROOM_CONVEX_URL`              | Override the default Convex backend URL                      | `https://chatroom-cloud.duskfare.com`  |
-| `CHATROOM_ENABLE_CLIENT_LOGGING`   | Enable Convex client logs (backend console.log) in CLI output | `false`                                |
+| Variable                         | Description                                                   | Default                               |
+| -------------------------------- | ------------------------------------------------------------- | ------------------------------------- |
+| `CHATROOM_CONVEX_URL`            | Override the default Convex backend URL                       | `https://chatroom-cloud.duskfare.com` |
+| `CHATROOM_ENABLE_CLIENT_LOGGING` | Enable Convex client logs (backend console.log) in CLI output | `false`                               |
 
 ### Examples
 
 **Connect to local development backend:**
 
 ```bash
-CHATROOM_CONVEX_URL=http://127.0.0.1:3210 chatroom wait-for-task <id> --role=<role>
+CHATROOM_CONVEX_URL=http://127.0.0.1:3210 chatroom get-next-task <id> --role=<role>
 ```
 
 **Enable debug logging:**
 
 ```bash
-CHATROOM_ENABLE_CLIENT_LOGGING=true chatroom wait-for-task <id> --role=<role>
+CHATROOM_ENABLE_CLIENT_LOGGING=true chatroom get-next-task <id> --role=<role>
 ```
 
 **Combine multiple environment variables:**
 
 ```bash
-CHATROOM_CONVEX_URL=http://127.0.0.1:3210 CHATROOM_ENABLE_CLIENT_LOGGING=true chatroom wait-for-task <id> --role=<role>
+CHATROOM_CONVEX_URL=http://127.0.0.1:3210 CHATROOM_ENABLE_CLIENT_LOGGING=true chatroom get-next-task <id> --role=<role>
 ```
 
 ---
@@ -144,6 +144,78 @@ Messages are routed by priority (lower = higher priority):
 User → Builder → Reviewer → User
 ```
 
+## Agent Integration Guide
+
+This section is designed to be copied into your agent's `AGENTS.md` file or system prompt to enable chatroom participation and automatic crash recovery.
+
+### Copy-Paste Template
+
+````markdown
+## 6. CHATROOM INTEGRATION
+
+If you are given a role in the chatroom ecosystem, you MUST always direct your questions to the user via the chatroom handoff command with the user as the target chatroom.
+
+The chatroom get-next-task command is of this format:
+
+```
+CHATROOM_CONVEX_URL=<endpoint> \
+chatroom get-next-task --chatroom-id=<chatroom-id> --role=<role>
+```
+
+The chatroom handoff command is of this format:
+
+```
+CHATROOM_CONVEX_URL=<endpoint> \
+chatroom handoff --chatroom-id=<id> --role=<role> --next-role=<role>
+```
+
+### CRITICAL: Execution Rules for Chatroom Commands
+
+**`get-next-task` MUST be executed immediately via the `bash` tool — not documented, not deferred.**
+
+The correct session loop is:
+
+1. **Immediately run** `get-next-task` via `bash` and block until a task arrives
+2. **Process** the task
+3. **Run** `handoff` via `bash` to signal completion and pass control
+4. **Immediately run** `get-next-task` again to wait for the next task
+
+**Common mistakes to avoid:**
+
+- ❌ Adding `get-next-task` to the todo list and then returning a summary to the user instead of running it
+- ❌ Treating `get-next-task` as something to document rather than execute
+- ❌ Skipping the `bash` tool call and just describing what you would do
+
+The todo list is for _tracking_, not _executing_. The `bash` tool is what actually runs the command. Both must be used — add the task to the todo list AND call `bash` to execute it.
+
+To ensure that you always get this right, even after compaction, you should always add executing the get-next-task as a todo item, with the full command example and CHATROOM_CONVEX_URL so that you never forget.
+
+### Context Recovery After Compaction
+
+**If you suspect context compaction or summarization has occurred** — for example, if your context window appears to contain only a high-level summary with next steps rather than the full conversation history — re-fetch your system prompt immediately before continuing:
+
+```
+CHATROOM_CONVEX_URL=<endpoint> \
+chatroom get-system-prompt --chatroom-id=<chatroom-id> --role=<role>
+```
+
+This prints your complete role instructions to stdout. Read them carefully, then resume the session loop.
+
+**Signs that compaction has occurred:**
+
+- Your context begins with something like "Summary of prior conversation:" or "Context so far:"
+- You are unsure of your role, responsibilities, or which commands to run
+- You can see "next steps" but no actual conversation history leading up to them
+
+**Recovery procedure:**
+
+1. Run `get-system-prompt` to reload your full instructions
+2. Check your todo list for the last known next step
+3. Resume with `get-next-task` or `handoff` as appropriate
+````
+
+---
+
 ## License
 
 MIT