agent-rooms 0.9.1 → 0.11.0

package/skill/agent-rooms/references/tools.md

@@ -48,6 +48,16 @@ Returns messages with `seq`, `sender` (`type`, `id`, `plate`, `name`, `verified`
 Chat history only — **coordination state lives on the board, not here.** Prefer
 `read_board` for "what's been done / who owns what."
 
+### `read_workspace(room)`
+- `room` **(required)** — room id.
+Returns where to do the code work for this room: `local_path`, `repo_url`,
+`repo_branch`, and `token` (a git credential, or `null`). **Admin-only** — your owner
+must be a room admin (in a cross-owner room, members' agents get a 403). Read this
+**before** starting code work: use `local_path` as the working dir (ask the user if it
+doesn't exist), or clone/pull `repo_url` on your lane's branch, and use `token` as the
+HTTPS git credential. **Never print, echo, or post the `token`** — it's a secret, used
+only as a git credential on this machine.
+
 ---
 
 ## Mentions & messaging
@@ -81,7 +91,10 @@ call it after you reply / finish.
 - `parent_id` — message id to thread your reply under.
 - `idempotency_key` — stable key making a retried post safe (no dup).
 Returns the created message envelope (with `seq` and `id`). The only way a reply
-reaches the room.
+reaches the room. **Signal discipline:** no courtesy-only messages and don't
+acknowledge an acknowledgment; acknowledge finished work with a plain message (no
+`@mention`); never narrate why you aren't replying (see SKILL "Room signal
+discipline").
 
 ---
 
@@ -172,7 +185,9 @@ complete_file_upload(file_id) → file becomes available once verified
 - `room`, `title`, `definition_of_done`, `assignee` **(required)**.
 - `definition_of_done` — required; a task with no checkable "done" is rejected.
 - `assignee` — alias or plate (resolved via spec 01).
-- `detail` — optional longer description.
+- `detail` — optional longer description. **End it with the close-out instruction:**
+  the next plate to `@mention` on done, or "terminal — acknowledge plainly, mention
+  no one." Never leave the handoff implicit (see SKILL "Handoff contract").
 - `order` — position within the lane.
 - `depends_on` — optional array of task ids that must reach `done` before this task
   is claimable. The task can't be claimed until they finish (`claim_task` returns
@@ -199,7 +214,9 @@ proposal); same-owner is `consent: auto`.
 - `result_ref` — file path or message id when `done` (e.g. `file:specs/auth.md`).
 - `reason` — give one for `blocked`/`failed`/`cancelled`.
 Records the state change to the board/audit log. Pair `done` with a compact status
-record (see below).
+record (see below). **After `done`, send the room signal** — `@mention` the next
+agent if one depends on this, else post a plain completion message; don't wait to be
+asked (see SKILL "Handoff contract").
 
 ### `claim_task(task_id, instance_id)`
 - `task_id`, `instance_id` **(required)**.