talking-stick 0.2.0 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # Talking Stick
 
-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.
+A CLI coordination tool 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.2.0. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv` and the matching MCP tools.
+**Version:** 0.4.0. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv`.
 
 ## Quickstart
 
@@ -14,13 +14,13 @@ Three steps, then you're coordinating two agents in the same repo.
 npm i -g talking-stick
 ```
 
-### 2. Register the MCP server and skill in every harness
+### 2. Install the skill in every harness
 
 ```bash
 tt install --all
 ```
 
-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.
+Restart any harness that was already running so it loads the updated skill. The skill teaches agents to coordinate by running `tt` CLI commands from the workspace. To tune the default collaboration prompt without editing installed package files, run `tt instructions edit`.
 
 ### 3. Try it: two agents, one repo
 
@@ -46,7 +46,7 @@ That's the whole workflow. They negotiate turns automatically, hand off structur
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.2.0`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.4.0`. 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. |
 
@@ -76,7 +76,7 @@ Uses the right npm/pnpm/yarn by default:
 tt self-update
 ```
 
-Skills are symlinked automatically, so they don't need an update.
+`tt self-update` also removes stale Talking Stick MCP registrations left by older installs. The first normal `tt` invocation after a package-version change runs the same cleanup if the package manager skipped lifecycle scripts.
 
 ### Remove
 
@@ -86,32 +86,41 @@ tt uninstall --all
 
 ## What it gives your agent
 
-Once installed, each agent harness sees these tools:
+Once installed, each agent harness has a skill that tells it to coordinate through the `tt` CLI:
 
 ```
-list_rooms         — which rooms exist under a path
-join_path          — join the room for this workspace
-leave_room         — explicitly leave a room; deletes it when no active members remain
-wait_for_turn      — block until the stick is available, with takeover signals
-heartbeat          — prove liveness while holding the stick
-release_stick      — normal handoff to the next fair waiter, with structured Handoff
-pass_stick         — explicit handoff to a named agent
-takeover_stick     — deliberate claim when the prior holder is gone/stuck
-kick_member        — evict an idle member whose process is gone
-get_room_state     — authoritative state projection
-get_room_events    — audit log of turn transitions
-add_note           — leave an async observation for the current owner
-list_notes         — read notes left for the room
-send_message       — out-of-band chat into the room event log (direct or broadcast)
-wait_for_events    — observer-safe long-poll over the event log with type/target/sender filters
+tt list            — which rooms exist under a path
+tt join            — join the room for this workspace
+tt leave           — explicitly leave a room; deletes it when no active members remain
+tt wait            — block until the stick is available, with takeover signals
+tt release         — normal handoff to the next fair waiter, with structured Handoff
+tt assign          — explicit handoff to a named agent
+tt take            — deliberate claim when the prior holder is gone/stuck
+tt kick            — evict an idle member whose process is gone
+tt state           — authoritative state projection
+tt events          — audit log and long-poll stream of turn transitions/messages
+tt notes add/list  — durable async observations for the room
+tt msg send/recv   — out-of-band chat into the room event log
+tt instructions    — editable collaboration prompt loaded by the skill
 ```
 
 A workspace maps to a room — usually the `git` root or nearest project marker — so two agents `cd`'d anywhere under the same repo join the same room automatically.
 
-The skill complements the MCP tools:
+The global skill tells the model when to join, wait, verify its guardian, take over, leave notes, send messages, and hand off.
 
-- MCP gives the harness the coordination surface
-- the global skill tells the model when to join, wait, heartbeat, take over, and hand off
+## Editable collaboration instructions
+
+The bundled skill is the safety floor. It is intentionally small and package-managed. Local collaboration preferences live in editable Markdown files that `tt instructions` shows to agents after they join.
+
+```bash
+tt instructions show                     # effective prompt for the detected harness
+tt instructions show --harness codex     # view one harness's effective prompt
+tt instructions edit                     # edit user defaults
+tt instructions edit --project           # edit this repo's overrides
+tt instructions reset --project          # remove this repo's override
+```
+
+Effective instructions are layered in this order: bundled defaults, user defaults at `${TALKING_STICK_DATA_DIR}/instructions.md` (normally `~/.local/share/talking-stick/instructions.md`), then project overrides at `.talking-stick/instructions.md` in the workspace root. User and project files are created lazily on first edit, so installing `tt` does not litter repositories or harness config directories.
 
 ## Non-owner notes
 
@@ -135,7 +144,9 @@ tt events --wait|--follow [--event TYPE[,TYPE]] [--target self|any|agent]
 - `--interrupt` marks the message time-sensitive; receivers decide whether to act on it now.
 - `tt msg recv --follow` is a long-running tail (one JSON line per event) suited to harnesses that can monitor child stdout (Claude Code Monitor, terminals).
 - `tt msg recv --wait` exits on the next matching batch — ideal for harnesses that can launch a background command and notice when it completes; restart with `--after <last_event_seq>` to resume.
+- `tt events --wait` and `tt events --follow` default to `--target self`; pass `--target any` only for audit/debug views.
 - `wait_for_events` is observer-safe: it never mutates room state, so non-holders can use it freely without disturbing turn-fairness bookkeeping.
+- Event receive does not grant the stick. Agents must still use `tt wait` for ownership and verify the returned guardian before editing shared files.
 
 **When to message vs note vs handoff.**
 
@@ -145,26 +156,11 @@ tt events --wait|--follow [--event TYPE[,TYPE]] [--target self|any|agent]
 
 **`to_agent_id` is routing, not ACL.** Any room member can read any message via `get_room_events` or `tt events --follow --target any`. Messages are not private. They also do not grant the stick — a non-holder paging the holder gets attention, not write authority.
 
-## How installation works per harness
-
-`tt install` installs both pieces a harness needs: the MCP server registration and the bundled `talking-stick` skill.
+For harnesses that only notice completed subprocesses, run `tt events --wait --after <cursor> --json` as a wake process alongside the normal `tt wait --json` loop. A message, pass, release, or assignment event should make the agent read/reply/retry `tt wait`; it is not permission to mutate the workspace.
 
-For MCP registration, it prefers each harness's own `mcp add` subcommand when available (so the server ends up in the right user-global config with the right schema), and falls back to direct JSON editing when it isn't.
-
-| Harness       | Scope        | Under the hood                                                              |
-|---------------|--------------|-----------------------------------------------------------------------------|
-| claude-code   | user         | `claude mcp add -s user talking-stick -- tt mcp`                            |
-| codex         | user         | `codex mcp add talking-stick -- tt mcp`                                     |
-| gemini        | user         | `gemini mcp add -s user -t stdio talking-stick tt mcp`                      |
-| opencode      | user         | Merge `mcp.talking-stick` into `$XDG_CONFIG_HOME/opencode/opencode.json`    |
-
-All four install into **user-global scope**, not project-local. A coordination server is only useful if every workspace your agent enters can see the same rooms — project-scoped MCP would defeat the point.
-
-If you'd rather apply setup by hand, run `tt install --print <harness>` to see the exact MCP and skill actions, then apply them yourself.
-
-## Skill paths per harness
+## How installation works per harness
 
-Talking Stick also ships with a portable `talking-stick` skill:
+`tt install` installs or refreshes the bundled `talking-stick` skill. It does not add MCP servers. During install, uninstall, package update, and first run after an installed package version changes, `tt` removes stale MCP registrations written by older Talking Stick releases.
 
 - Claude Code: copied or linked into `~/.claude/skills/talking-stick`
 - Codex: copied or linked into `~/.codex/skills/talking-stick`
@@ -173,6 +169,8 @@ Talking Stick also ships with a portable `talking-stick` skill:
 
 By default, `tt install` links the bundled skill into each harness so local updates are picked up immediately. Pass `--copy` if you want a standalone snapshot instead.
 
+Stale MCP cleanup is strict for OpenCode JSON entries: it removes only the canonical `mcp.talking-stick` value with `["tt", "mcp"]` and leaves hand-edited entries alone. Claude Code, Codex, and Gemini cleanup uses their own `mcp remove` commands when the old server name exists. Every cleanup run appends JSONL audit entries to `${TALKING_STICK_DATA_DIR}/update-migrations.log`.
+
 Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install gemini` after updating when needed.
 
 ## Human CLI
@@ -184,12 +182,15 @@ tt whoami [--explain]                                      # show the resolved C
 tt list [path]                                            # list rooms
 tt join [path] [--force-new]                              # join the room for path
 tt leave [path]                                           # leave the room for path
-tt wait [path] [--timeout 30s]                            # block until your turn
+tt wait [path] [--timeout 110s]                           # block until your turn
 tt try [path]                                             # non-blocking claim attempt
 tt state [path]                                           # full room state
 tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]  # room event log; --wait/--follow long-polls
 tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]  # send an OOB message
 tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent] [--path DIR]  # receive OOB messages
+tt instructions show [path] [--harness claude|codex|gemini|opencode|all] [--scope effective|bundled|user|project]  # show collaboration prompt
+tt instructions edit [path] [--user|--project]             # edit user or project prompt
+tt instructions reset [path] (--user|--project)            # delete a user or project prompt
 tt release [path] --status TEXT --next-action TEXT        # normal handoff
 tt pass [path] --status TEXT --next-action TEXT           # pass/end your turn
 tt assign <target|next> [path] --status TEXT --next-action TEXT  # explicit handoff
@@ -197,13 +198,14 @@ tt take [path] [--reason TEXT]                            # human-friendly take/
 tt takeover [path] [--reason TEXT]                        # alias for take
 tt notes add <body> [--turn N] [--path DIR] [--stdin]     # leave an async note
 tt notes list [--all] [--after ID] [--limit N] [--path DIR] # read notes
-tt mcp                                                    # run the MCP stdio server
-tt install <harness...> | --all [--print] [--copy] [--link]  # install MCP server and skill
-tt uninstall <harness...> | --all [--print]               # remove MCP server and skill
+tt install <harness...> | --all [--print] [--copy] [--link]  # install skill and clean stale MCP entries
+tt uninstall <harness...> | --all [--print]               # remove skill and stale MCP entries
 tt self-update [--print] [--manager npm|pnpm|yarn|bun]    # update to the latest published tt
 ```
 
-`tt self-update` detects how `tt` was installed (npm / pnpm / yarn / bun, including npm-via-Homebrew/mise/asdf/nvm) and runs the right global-update command. Pass `--print` to see the inferred command without running it; pass `--manager` to override detection. Running `tt self-update` from a development checkout (where `tt` resolves outside `node_modules/talking-stick`) refuses and tells you to `git pull && npm install && npm run build` instead.
+`[path]` defaults to the current working directory. Omit it for normal in-repo coordination; pass it only when you intentionally want a different or nested room.
+
+`tt self-update` detects how `tt` was installed (npm / pnpm / yarn / bun, including npm-via-Homebrew/mise/asdf/nvm), runs the right global-update command, then removes stale MCP registrations from older Talking Stick installs. Pass `--print` to see the inferred command without running it; pass `--manager` to override detection. Running `tt self-update` from a development checkout (where `tt` resolves outside `node_modules/talking-stick`) refuses and tells you to `git pull && npm install && npm run build` instead.
 
 Human CLI commands use a stable identity like `human:<username>`. When `tt wait`, `tt take`, or `tt takeover` wins the turn, a small background guardian keeps the lease alive on your behalf until you release, pass, or assign it. Human CLI `take` intentionally works without a required reason so an operator can step into a stuck room quickly; harness-aware CLI takeovers still require `--reason` unless the command includes `--operator-requested`.
 
@@ -231,7 +233,7 @@ Use `tt whoami --explain` to see which identity path the CLI chose.
 - **Fencing tokens.** `lease_id` + `turn_id` make stale writes impossible — an agent who lost their turn cannot commit anything under the room's name.
 - **Liveness-aware recovery.** Dead or crashed holders are detected with OS-level process checks; claim-timeout takeover skips the prior owner when another active member is waiting.
 - **Multi-process safe.** Shared SQLite with WAL mode, `BEGIN IMMEDIATE` writes, 250 ms polling for `wait_for_turn`. No daemon required.
-- **Per-call identity derivation.** MCP callers don't supply `agent_id`; the adapter derives identity from the spawning harness process. Human CLI callers get a stable `human:<username>` identity.
+- **Per-call identity derivation.** Harness-launched CLI calls derive identity from harness environment or ancestry. Human CLI callers get a stable `human:<username>` identity.
 
 ## Storage
 

package/dist/cli/install-commands.js

@@ -1,7 +1,11 @@
 import { spawn } from "node:child_process";
-import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planInstall, planUninstall, runAction } from "../install.js";
+import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planUninstall, runAction } from "../install.js";
 import { planSkillInstall, planSkillUninstall } from "../skill-install.js";
+import { resolveDataDir } from "../config.js";
+import { FileAuditLog, defaultAuditLogPath } from "../install-audit.js";
+import { removeStaleMcpRegistrations } from "../install-migration.js";
 import { detectInstallSource, isPackageManager, planSelfUpdate, resolveCurrentBinaryPath } from "../self-update.js";
+import { readPackageVersion, runStaleMcpCleanup } from "../update-migration.js";
 import { getStringOption, hasOption, normalizeBooleanFlag } from "./parser.js";
 export async function runInstallCommand(parsed) {
     normalizeBooleanFlag(parsed, "print");
@@ -14,28 +18,34 @@ export async function runInstallCommand(parsed) {
         skipMissing: true
     };
     if (dryRun) {
-        for (const action of planCombinedInstallActions(harnesses, installOptions)) {
+        for (const action of planInstallActions(harnesses, installOptions)) {
+            printActionPlan(action);
+        }
+        for (const action of planCleanupActions(harnesses, installOptions)) {
             printActionPlan(action);
         }
         return;
     }
-    const results = (await Promise.all(harnesses.map((harness) => runCombinedInstall(harness, installOptions)))).flat();
+    const results = (await Promise.all(harnesses.map((harness) => runSkillInstall(harness, installOptions)))).flat();
     reportInstallResults(results, "install");
+    reportCleanupResults(await runCleanup(harnesses, "manual", installOptions), "install");
+    printInstructionHint(results);
 }
 export async function runUninstallCommand(parsed) {
     normalizeBooleanFlag(parsed, "print");
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
     const installOptions = { skipMissing: true };
-    const actions = planCombinedUninstallActions(harnesses, installOptions);
+    const actions = planUninstallActions(harnesses, installOptions);
     if (dryRun) {
         for (const action of actions) {
             printActionPlan(action);
         }
         return;
     }
-    const results = (await Promise.all(harnesses.map((harness) => runCombinedUninstall(harness, installOptions)))).flat();
+    const results = (await Promise.all(harnesses.map((harness) => runSkillUninstall(harness, installOptions)))).flat();
     reportInstallResults(results, "uninstall");
+    reportCleanupResults(await runCleanup(harnesses, "uninstall", installOptions), "uninstall");
 }
 export async function runInstallSkillCommand(parsed) {
     normalizeBooleanFlag(parsed, "print");
@@ -85,6 +95,7 @@ export async function runSelfUpdateCommand(parsed, cliEntryUrl) {
         const binaryPath = resolveCurrentBinaryPath(cliEntryUrl);
         source = detectInstallSource({ binaryPath });
     }
+    const packageVersionFrom = readPackageVersion(cliEntryUrl);
     const plan = planSelfUpdate(source);
     if (!plan) {
         if (source === "dev") {
@@ -98,7 +109,29 @@ export async function runSelfUpdateCommand(parsed, cliEntryUrl) {
     }
     process.stdout.write(`Updating via: ${plan.description}\n`);
     await runInheritIo(plan.command, plan.args);
-    process.stdout.write("Done. Restart your harness MCP subprocess to pick up the new dist.\n");
+    const packageVersionTo = readPackageVersion(cliEntryUrl);
+    const cleanup = await runStaleMcpCleanup({
+        harnesses: "all",
+        reason: "update",
+        packageVersionFrom,
+        packageVersionTo,
+        installOptions: { skipMissing: true }
+    });
+    reportCleanupResults(cleanup.results, "self-update");
+    process.stdout.write("Done. Restart any long-running harness sessions to pick up the new tt.\n");
+}
+export async function runMcpMigrationCommand(parsed) {
+    normalizeBooleanFlag(parsed, "quiet");
+    const reason = parseAuditReason(getStringOption(parsed, "reason") ?? "manual");
+    const quiet = hasOption(parsed, "quiet");
+    const cleanup = await runStaleMcpCleanup({
+        harnesses: "all",
+        reason,
+        installOptions: { skipMissing: true }
+    });
+    if (!quiet) {
+        reportCleanupResults(cleanup.results, "self-update");
+    }
 }
 function resolveSkillInstallLinkMode(parsed) {
     const wantsCopy = hasOption(parsed, "copy");
@@ -111,48 +144,39 @@ function resolveSkillInstallLinkMode(parsed) {
     }
     return true;
 }
-function planCombinedInstallActions(harnesses, installOptions) {
-    return harnesses.flatMap((harness) => {
-        const mcpAction = planInstall(harness, installOptions);
-        if (mcpAction.kind === "skip") {
-            return [mcpAction];
-        }
-        return [
-            mcpAction,
-            planSkillInstall(harness, {
-                ...installOptions,
-                // In dry-run mode, show the skill action that will follow MCP setup
-                // even when the MCP installer is what creates the harness config root.
-                skipMissing: false
-            })
-        ];
-    });
+function planInstallActions(harnesses, installOptions) {
+    return harnesses.map((harness) => planSkillInstall(harness, installOptions));
 }
-function planCombinedUninstallActions(harnesses, installOptions) {
+function planUninstallActions(harnesses, installOptions) {
     return harnesses.flatMap((harness) => [
-        planUninstall(harness, installOptions),
         planSkillUninstall(harness, {
             ...installOptions,
             skipMissing: false
-        })
+        }),
+        planUninstall(harness, installOptions)
     ]);
 }
-async function runCombinedInstall(harness, installOptions) {
-    const mcpAction = planInstall(harness, installOptions);
-    const mcpResult = await runAction(mcpAction, installOptions);
-    if (!mcpResult.ok || mcpResult.skipped) {
-        return [mcpResult];
-    }
+function planCleanupActions(harnesses, installOptions) {
+    return harnesses.map((harness) => planUninstall(harness, installOptions));
+}
+async function runSkillInstall(harness, installOptions) {
     const skillAction = planSkillInstall(harness, installOptions);
     const skillResult = await runAction(skillAction, installOptions);
-    return [mcpResult, skillResult];
+    return [skillResult];
 }
-async function runCombinedUninstall(harness, installOptions) {
-    const mcpAction = planUninstall(harness, installOptions);
-    const mcpResult = await runAction(mcpAction, installOptions);
+async function runSkillUninstall(harness, installOptions) {
     const skillAction = planSkillUninstall(harness, installOptions);
     const skillResult = await runAction(skillAction, installOptions);
-    return [mcpResult, skillResult];
+    return [skillResult];
+}
+async function runCleanup(harnesses, reason, installOptions) {
+    const dataDir = resolveDataDir();
+    return removeStaleMcpRegistrations({
+        harnesses,
+        reason,
+        audit: new FileAuditLog(defaultAuditLogPath(dataDir)),
+        installOptions
+    });
 }
 function selectHarnesses(parsed) {
     if (hasOption(parsed, "all")) {
@@ -199,6 +223,29 @@ function reportInstallResults(results, mode) {
         throw new Error(`${mode} completed with failures.`);
     }
 }
+function printInstructionHint(results) {
+    if (!results.some((result) => result.ok && !result.skipped)) {
+        return;
+    }
+    process.stdout.write("Customize collaboration instructions with: tt instructions edit\n");
+}
+function reportCleanupResults(results, mode) {
+    let anyFailed = false;
+    for (const result of results) {
+        process.stdout.write(`[${result.harness}] mcp-cleanup ${result.action}: ${result.message}\n`);
+        if (result.action === "failed")
+            anyFailed = true;
+    }
+    if (anyFailed) {
+        throw new Error(`${mode} completed with MCP cleanup failures.`);
+    }
+}
 function formatInstallStatus(status) {
     return status.replaceAll("_", "-");
 }
+function parseAuditReason(value) {
+    if (value === "update" || value === "first-run" || value === "uninstall" || value === "manual") {
+        return value;
+    }
+    throw new Error(`--reason must be one of update | first-run | uninstall | manual (got ${value}).`);
+}

package/dist/cli/instructions-commands.js

@@ -0,0 +1,113 @@
+import { editInstructions, parseInstructionScope, resetInstructions, showInstructions } from "../instructions.js";
+import { deriveCliIdentity } from "./identity.js";
+import { getStringOption, hasOption } from "./parser.js";
+import { printResult } from "./output.js";
+export async function handleInstructionsCommand(parsed) {
+    const [subcommand = "show", ...rest] = parsed.positionals;
+    const subParsed = {
+        name: `instructions ${subcommand}`,
+        positionals: rest,
+        options: parsed.options
+    };
+    switch (subcommand) {
+        case "show":
+            handleInstructionsShowCommand(subParsed);
+            return;
+        case "edit":
+            await handleInstructionsEditCommand(subParsed);
+            return;
+        case "reset":
+            handleInstructionsResetCommand(subParsed);
+            return;
+        default:
+            throw new Error(`Unknown instructions subcommand: ${subcommand}`);
+    }
+}
+function handleInstructionsShowCommand(parsed) {
+    repairBooleanFlag(parsed, "json", 0);
+    repairBooleanFlag(parsed, "text", 0);
+    const contextPath = resolveContextPathArg(parsed);
+    const scope = parseInstructionScope(getStringOption(parsed, "scope"));
+    const identity = deriveCliIdentity(parsed);
+    const result = showInstructions({
+        harness: getStringOption(parsed, "harness"),
+        scope,
+        options: {
+            contextPath,
+            identity
+        }
+    });
+    printResult(parsed, result, () => {
+        if (result.text.trim().length > 0) {
+            return result.text;
+        }
+        return `No ${result.scope} instructions found for ${result.harness}.`;
+    });
+}
+async function handleInstructionsEditCommand(parsed) {
+    repairBooleanFlag(parsed, "json", 0);
+    repairBooleanFlag(parsed, "text", 0);
+    repairBooleanFlag(parsed, "user", 0);
+    repairBooleanFlag(parsed, "project", 0);
+    const contextPath = resolveContextPathArg(parsed);
+    const scope = resolveEditableScope(parsed, false);
+    const result = await editInstructions({
+        scope,
+        options: { contextPath }
+    });
+    printResult(parsed, result, () => {
+        if (result.opened) {
+            return `Opened ${result.scope} instructions: ${result.path}`;
+        }
+        return [
+            `Instructions file ready: ${result.path}`,
+            "Set $VISUAL or $EDITOR to edit it from this command."
+        ].join("\n");
+    });
+}
+function handleInstructionsResetCommand(parsed) {
+    repairBooleanFlag(parsed, "json", 0);
+    repairBooleanFlag(parsed, "text", 0);
+    repairBooleanFlag(parsed, "user", 0);
+    repairBooleanFlag(parsed, "project", 0);
+    const contextPath = resolveContextPathArg(parsed);
+    const scope = resolveEditableScope(parsed, true);
+    const result = resetInstructions({
+        scope,
+        options: { contextPath }
+    });
+    printResult(parsed, result, () => {
+        if (result.removed) {
+            return `Removed ${result.scope} instructions: ${result.path}`;
+        }
+        return `No ${result.scope} instructions file at ${result.path}`;
+    });
+}
+function resolveEditableScope(parsed, requireExplicit) {
+    const wantsUser = hasOption(parsed, "user");
+    const wantsProject = hasOption(parsed, "project");
+    if (wantsUser && wantsProject) {
+        throw new Error("Pass only one of --user or --project.");
+    }
+    if (wantsProject) {
+        return "project";
+    }
+    if (wantsUser || !requireExplicit) {
+        return "user";
+    }
+    throw new Error("Pass --user or --project to choose which instructions to reset.");
+}
+function resolveContextPathArg(parsed) {
+    const pathOption = parsed.options.get("path");
+    if (pathOption === true) {
+        throw new Error("--path requires a value.");
+    }
+    return pathOption ?? parsed.positionals[0] ?? process.cwd();
+}
+function repairBooleanFlag(parsed, key, insertAt) {
+    const value = parsed.options.get(key);
+    if (typeof value === "string") {
+        parsed.positionals.splice(insertAt, 0, value);
+        parsed.options.set(key, true);
+    }
+}

package/dist/cli/output.js

@@ -123,12 +123,15 @@ Commands:
   tt join [path] [--force-new]
   tt leave [path]
   tt kick <agent_id> [path] [--reason TEXT] [--force]
-  tt wait [path] [--timeout 30s]
+  tt wait [path] [--timeout 110s]
   tt try [path]
   tt state [path]
   tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]
   tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]
   tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent] [--path DIR]
+  tt instructions show [path] [--harness claude|codex|gemini|opencode|all] [--scope effective|bundled|user|project]
+  tt instructions edit [path] [--user|--project]
+  tt instructions reset [path] (--user|--project)
   tt release [path] (--status TEXT --next-action TEXT | --stdin)
   tt pass [path] (--status TEXT --next-action TEXT | --stdin)
   tt assign <target|next> [path] (--status TEXT --next-action TEXT | --stdin)
@@ -136,7 +139,6 @@ Commands:
   tt takeover [path] [--reason TEXT] [--operator-requested]
   tt notes add <body> [--turn N] [--path DIR] [--stdin]
   tt notes list [--all] [--after NOTE_ID] [--limit N] [--path DIR]
-  tt mcp
   tt install <harness...> | --all [--print] [--copy] [--link]
   tt uninstall <harness...> | --all [--print]
   tt self-update [--print] [--manager npm|pnpm|yarn|bun]
@@ -144,6 +146,7 @@ Commands:
 Harnesses: ${SUPPORTED_HARNESSES.join(", ")}
 
 Common options:
+  [path]     Defaults to the current working directory when omitted
   --agent ID   Override the default human identity
   --json       Force JSON output (also default when invoked from a harness)
   --text       Force human-readable text even when invoked from a harness

package/dist/cli/registry.js

@@ -1,20 +1,11 @@
-import { runStdioServer } from "../index.js";
 import { runGuardCommand } from "./guardian.js";
-import { runInstallCommand, runInstallSkillCommand, runSelfUpdateCommand, runUninstallCommand, runUninstallSkillCommand } from "./install-commands.js";
+import { runInstallCommand, runMcpMigrationCommand, runSelfUpdateCommand, runUninstallCommand } from "./install-commands.js";
+import { handleInstructionsCommand } from "./instructions-commands.js";
 import { handleMsgCommand } from "./msg-commands.js";
 import { handleNotesCommand } from "./notes-commands.js";
 import { handleEventsCommand, handleJoinCommand, handleKickCommand, handleLeaveCommand, handleListCommand, handleStateCommand, handleWhoAmICommand } from "./room-commands.js";
 import { handleAssignCommand, handlePassCommand, handleReleaseCommand, handleTakeCommand, handleWaitCommand } from "./turn-commands.js";
 export const COMMAND_REGISTRY = [
-    {
-        name: "mcp",
-        needsRuntime: false,
-        startupMaintenance: false,
-        internal: true,
-        usage: "tt mcp",
-        description: "Run the MCP server over stdio.",
-        handler: () => runStdioServer()
-    },
     {
         name: "guard",
         needsRuntime: false,
@@ -30,7 +21,7 @@ export const COMMAND_REGISTRY = [
         startupMaintenance: false,
         internal: false,
         usage: "tt install <harness...> | --all [--print] [--copy] [--link]",
-        description: "Install Talking Stick into harness MCP configs and skills.",
+        description: "Install the Talking Stick skill and remove stale MCP registrations.",
         handler: ({ parsed }) => runInstallCommand(parsed)
     },
     {
@@ -39,35 +30,35 @@ export const COMMAND_REGISTRY = [
         startupMaintenance: false,
         internal: false,
         usage: "tt uninstall <harness...> | --all [--print]",
-        description: "Remove Talking Stick from harness MCP configs and skills.",
+        description: "Remove the Talking Stick skill and stale MCP registrations.",
         handler: ({ parsed }) => runUninstallCommand(parsed)
     },
     {
-        name: "install-skill",
+        name: "self-update",
         needsRuntime: false,
         startupMaintenance: false,
         internal: false,
-        usage: "tt install-skill <harness...> | --all [--print] [--copy] [--link]",
-        description: "Install the bundled Talking Stick skill.",
-        handler: ({ parsed }) => runInstallSkillCommand(parsed)
+        usage: "tt self-update [--print] [--manager npm|pnpm|yarn|bun]",
+        description: "Update the globally installed tt package.",
+        handler: ({ parsed, cliEntryUrl }) => runSelfUpdateCommand(parsed, cliEntryUrl)
     },
     {
-        name: "uninstall-skill",
+        name: "migrate-mcp",
         needsRuntime: false,
         startupMaintenance: false,
-        internal: false,
-        usage: "tt uninstall-skill <harness...> | --all [--print]",
-        description: "Remove the bundled Talking Stick skill.",
-        handler: ({ parsed }) => runUninstallSkillCommand(parsed)
+        internal: true,
+        usage: "tt migrate-mcp [--reason update|first-run|uninstall|manual] [--quiet]",
+        description: "Remove stale Talking Stick MCP registrations.",
+        handler: ({ parsed }) => runMcpMigrationCommand(parsed)
     },
     {
-        name: "self-update",
+        name: "instructions",
         needsRuntime: false,
         startupMaintenance: true,
         internal: false,
-        usage: "tt self-update [--print] [--manager npm|pnpm|yarn|bun]",
-        description: "Update the globally installed tt package.",
-        handler: ({ parsed, cliEntryUrl }) => runSelfUpdateCommand(parsed, cliEntryUrl)
+        usage: "tt instructions [show|edit|reset] [--harness NAME] [--scope SCOPE]",
+        description: "Show, edit, or reset editable collaboration instructions.",
+        handler: ({ parsed }) => handleInstructionsCommand(parsed)
     },
     {
         name: "whoami",
@@ -146,7 +137,7 @@ export const COMMAND_REGISTRY = [
         needsRuntime: true,
         startupMaintenance: true,
         internal: false,
-        usage: "tt wait [path] [--timeout 30s]",
+        usage: "tt wait [path] [--timeout 110s]",
         description: "Wait until this agent can claim the stick.",
         handler: ({ runtime, parsed, cliEntryUrl }) => handleWaitCommand(requireRuntime(runtime), parsed, false, cliEntryUrl)
     },

package/dist/cli/room-commands.js

@@ -135,7 +135,7 @@ export async function handleEventsCommand(runtime, parsed) {
     if (hasOption(parsed, "wait") || hasOption(parsed, "follow")) {
         await runEventStream(runtime, parsed, identity, session.room_id, {
             event_type: parseEventTypeFilter(getStringOption(parsed, "event")),
-            default_target: "any",
+            default_target: "self",
             force_tail_cursor: false
         });
         return;