talking-stick 0.1.0 → 0.1.1

package/README.md

@@ -2,32 +2,52 @@
 
 An MCP coordination server that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.1.0. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
+**Version:** 0.1.1. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
 
 ## Quickstart
 
-Three commands from zero to coordinated agents. No repo clone required.
+Three steps, then you're coordinating two agents in the same repo.
+
+### 1. Install the `tt` binary
 
 ```bash
-# 1. Install the `tt` binary from npm
 npm i -g talking-stick
+```
+
+### 2. Register the MCP server and skill in every harness
 
-# 2. Register Talking Stick as an MCP server + install the coordination skill
-#    across every harness detected on your machine
+```bash
 tt install --all
 tt install-skill --all
-
-# 3. Restart your agent harness (Claude Code, Codex, Gemini, OpenCode).
-#    The `talking_stick` tools now appear in any workspace.
 ```
 
-That's it. The next time two agents `cd` into the same repo, they see each other as members of one room, take turns automatically, and hand off structured context when they release the stick.
+Restart any harness that was already running so it loads the new MCP server. The `talking_stick` tools and skill now appear in every workspace.
+
+### 3. Try it: two agents, one repo
+
+Open two terminal panes side by side — tmux split, iTerm split, two windows, whatever you like. `cd` into the same repo in each, and launch a different harness in each pane:
+
+| Pane A — Claude Code | Pane B — Codex |
+|---|---|
+| `cd ~/myrepo && claude [--dangerously-skip-permissions]` | `cd ~/myrepo && codex` |
+
+Then prompt them.
+
+**Pane A (Claude Code):**
+
+> Draft a plan to add OAuth login. When it's solid, pass the stick to Codex for critique. After Codex hands it back with revisions, finalize, then pass to Codex to implement — you'll test and review. `/talking-stick`
+
+**Pane B (Codex):**
+
+> Join the room and wait for the stick. When Claude passes you a plan, critique it sharply and pass it back with revisions. Later, when Claude hands you the implementation turn, build it and pass back for review. `$talking-stick`
+
+That's the whole workflow. They negotiate turns automatically, hand off structured context (status, next action, artifacts) at each transition, and never edit the repo at the same time.
 
 ### Install options
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.1.0`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.1.1`. Requires Node ≥ 22. |
 | **From GitHub** | `npm i -g github:mostlydev/talking-stick` | Tracks the `master` branch; builds on install via the `prepare` hook. |
 | **From source** | `git clone … && npm install && npm link` | For contributors. |
 
@@ -51,6 +71,16 @@ tt install-skill gemini
 
 During normal execution, install commands skip harnesses that are not present instead of failing or creating new harness config roots. For example, `tt install-skill codex` only creates `~/.codex/skills/` if `~/.codex/` already exists.
 
+### Update
+
+Uses the right npm/pnpm/yarn by default:
+
+```bash
+tt self-update
+```
+
+Skills are symlinked automatically, so they don't need an update.
+
 ### Remove
 
 ```bash

package/dist/mcp-server.js

@@ -27,7 +27,7 @@ export function createMcpServer(service = new TalkingStickService()) {
     const resolveConnectionIdentity = createConnectionIdentityResolver();
     const server = new McpServer({
         name: "talking-stick",
-        version: "0.1.0"
+        version: "0.1.1"
     });
     server.registerTool("list_rooms", {
         title: "List Rooms",

package/docs/releases/0.1.1.md

@@ -0,0 +1,30 @@
+# Talking Stick 0.1.1
+
+Date: 2026-04-27
+
+Patch release focused on onboarding clarity and tighter multi-agent wait
+cadence.
+
+## Changed
+
+### Clearer quickstart
+
+The README quickstart now presents the setup as three steps: install `tt`,
+register the MCP server and skill across harnesses, then try a concrete
+two-agent Claude Code / Codex workflow in one repo.
+
+### Wait cycles before scheduled wakeups
+
+The bundled skill now tells agents to prefer direct `wait_for_turn` wait cycles
+and background long-polls over scheduled wakeups. Scheduled wakeups are framed
+as fallback behavior, and active multi-agent wakeups are capped at 60-120
+seconds unless the operator explicitly pauses the room or the task is blocked
+outside the room.
+
+## Verification
+
+- `npm run typecheck`
+- `npm test` — 208 tests across 14 files
+- `npm run build`
+- `git diff --check`
+- `npm pack --dry-run --ignore-scripts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP coordination server for path-scoped agent handoffs.",
   "type": "module",
   "bin": {

package/skills/talking-stick/SKILL.md

@@ -70,15 +70,15 @@ Possible outcomes:
 
 **Prefer to run the wait in the background.** If your harness supports running a command or subtask in the background, launch the wait (`wait_for_turn` or `tt wait`) as a background process so your foreground stays free for other work — reading, planning, answering the operator — until your turn arrives. Blocking the whole harness on the wait defeats the point.
 
-**Even better: use a wakeup if your harness supports one.** Some harnesses (for example Claude Code with `ScheduleWakeup`, cron-backed agents, or runtime-resumed sleeps) can sleep without keeping conversation context loaded. Prefer that over repeated long-polls: a long-poll re-evaluates your full conversation each cycle, while a wakeup pays one re-entry per actual room event.
+**Prefer wait cycles over scheduled wakeups.** A direct `wait_for_turn` long-poll keeps your cadence aligned with other agents and usually notices a released stick within the same cycle. Use scheduling only when your harness cannot keep a wait running in the background, or when it must return control between checks.
 
 Wakeup pattern:
 
 1. Probe `wait_for_turn` with `max_wait_ms: 0`.
-2. If it returns `not_yet`, schedule a wakeup and return control to the harness. Use 60-240 s in active multi-agent sessions, or 1200-1800 s at idle/operator-blocked pause points. Avoid roughly 300 s; most prompt caches expire around 5 minutes, so stay under that window or choose a much longer interval.
+2. If it returns `not_yet`, schedule a wakeup and return control to the harness. Keep active multi-agent wakeups tight: use 60-120 s, and never more than 120 s unless the operator explicitly pauses the room or the task is blocked outside the room.
 3. On wakeup, repeat from step 1.
 
-This converts repeated re-prompts into roughly one re-entry per actual event. If your harness has neither background work nor wakeups, fall back to synchronous long-polls with the longest client-safe `max_wait_ms` from §3.
+Scheduled wakeups are a fallback, not a reason to check in more slowly than agents using `wait_for_turn` directly. If your harness has neither background work nor wakeups, fall back to synchronous long-polls with the longest client-safe `max_wait_ms` from §3.
 
 Whether the wait runs in the foreground or the background, call it **once** with the client-safe `max_wait_ms` budget from above and let the server long-poll. When it returns without `your_turn`, call it again. Do not busy-loop with short waits — that generates log noise and burns cache without buying anything.