talking-stick 0.3.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.3.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`.
+**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
 
@@ -20,7 +20,7 @@ npm i -g talking-stick
 tt install --all
 ```
 
-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.
+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.3.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. |
 
@@ -101,12 +101,27 @@ 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 global skill tells the model when to join, wait, verify its guardian, take over, leave notes, send messages, 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
 
 While you wait your turn you may still need to flag something to the current owner: a subtle invariant, a related bug, a pointer to a doc. Non-owner notes give you a durable channel without interrupting the turn.
@@ -173,6 +188,9 @@ 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

package/dist/cli/install-commands.js

@@ -29,6 +29,7 @@ export async function runInstallCommand(parsed) {
     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");
@@ -222,6 +223,12 @@ 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) {

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

@@ -129,6 +129,9 @@ Commands:
   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)

package/dist/cli/registry.js

@@ -1,5 +1,6 @@
 import { runGuardCommand } from "./guardian.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";
@@ -50,6 +51,15 @@ export const COMMAND_REGISTRY = [
         description: "Remove stale Talking Stick MCP registrations.",
         handler: ({ parsed }) => runMcpMigrationCommand(parsed)
     },
+    {
+        name: "instructions",
+        needsRuntime: false,
+        startupMaintenance: true,
+        internal: false,
+        usage: "tt instructions [show|edit|reset] [--harness NAME] [--scope SCOPE]",
+        description: "Show, edit, or reset editable collaboration instructions.",
+        handler: ({ parsed }) => handleInstructionsCommand(parsed)
+    },
     {
         name: "whoami",
         needsRuntime: false,

package/dist/index.js

@@ -4,6 +4,7 @@ export { applyPragmas, assertLocalFilesystem, detectFilesystemType, migrate, ope
 export { ProtocolError, isProtocolError } from "./errors.js";
 export { deriveHarnessCliIdentity, deriveHumanCliIdentity, deriveMcpHarnessIdentity } from "./identity.js";
 export { ancestorPaths, canonicalizeContextPath, resolveContextPath, resolveWorkspaceRoot } from "./path-resolution.js";
+export { DEFAULT_MAX_INSTRUCTION_FILE_BYTES, DEFAULT_INSTRUCTIONS_MARKDOWN, editInstructions, extractHarnessInstructions, normalizeInstructionHarness, parseInstructionScope, resetInstructions, resolveInstructionHarness, resolveInstructionPaths, showInstructions } from "./instructions.js";
 export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
 export { DEFAULT_SKILL_NAME, planSkillInstall, planSkillUninstall, resolveBundledSkillPath, resolveSkillTargetPath, syncInstalledSkills } from "./skill-install.js";
 export { readPackageVersion, readUpdateMigrationState, resolveUpdateMigrationStatePath, runFirstRunMcpMigration, runStaleMcpCleanup, writeUpdateMigrationState } from "./update-migration.js";

package/dist/instructions.js

@@ -0,0 +1,256 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveDataDir } from "./config.js";
+import { resolveContextPath } from "./path-resolution.js";
+export const DEFAULT_MAX_INSTRUCTION_FILE_BYTES = 256 * 1024;
+export const DEFAULT_INSTRUCTIONS_MARKDOWN = `# Talking Stick collaboration instructions
+
+Keep using Talking Stick until the shared task is done. After releasing or handing off, re-enter the wait loop by default. Prefer continued action unless the task is complete or the operator explicitly redirects or stops the room.
+
+Use phase names in handoffs when they clarify the work: draft, adversarial review, convergence, implementation, implementation review, test review, and release. These phases are vocabulary, not protocol state.
+
+Typical fits are advisory. Claude is usually strong at prose, first-pass synthesis, tool-running, implementation review, and test review. Codex is usually strong at adversarial review, convergence, implementation, edge cases, and release mechanics after operator approval. Gemini and OpenCode start with conservative local guidance until project dogfood says otherwise.
+
+For multi-agent design work, prefer independent read-only drafts first, then adversarial review and convergence. Do not impose a draft file structure on the workspace by default. If scratch draft files are useful, delete superseded pre-convergence drafts after the converged plan exists unless the operator asks to keep them.
+
+Default to normal release handoffs. Use named assignment only when a specific member must go next because of unique context, credentials, capability, or direct operator routing.
+
+## Claude
+
+Lean into drafting, synthesis, tool-running, implementation review, and test review. Watch for scope creep and messy first-pass artifacts. When implementation belongs elsewhere, make the next phase explicit in the handoff.
+
+## Codex
+
+Lean into adversarial review, convergence, precise implementation, edge-case sweeps, and release mechanics after operator approval. Watch for over-indexing on mechanics when the operator still needs to decide direction.
+
+## Gemini
+
+Use broad context review and exploration conservatively until the project has stronger Gemini-specific dogfood. Keep handoffs concrete and do not assume responsibility that the operator assigned to another harness.
+
+## OpenCode
+
+Use terminal-native local exploration and implementation conservatively until the project has stronger OpenCode-specific dogfood. Keep coordination safety ahead of speed.
+`;
+const HARNESS_ALIASES = {
+    all: "all",
+    base: "all",
+    claude: "claude",
+    "claude-code": "claude",
+    codex: "codex",
+    gemini: "gemini",
+    opencode: "opencode"
+};
+export function resolveInstructionPaths(options = {}) {
+    const contextPath = options.contextPath ?? process.cwd();
+    const workspaceRoot = resolveContextPath(contextPath).workspace_root;
+    return {
+        user: path.join(resolveDataDir(options), "instructions.md"),
+        project: path.join(workspaceRoot, ".talking-stick", "instructions.md")
+    };
+}
+export function showInstructions(input = {}) {
+    const options = input.options ?? {};
+    const harness = resolveInstructionHarness(input.harness, options.identity);
+    const scope = input.scope ?? "effective";
+    const paths = resolveInstructionPaths(options);
+    const layers = readInstructionLayers(paths, options.maxInstructionFileBytes ?? DEFAULT_MAX_INSTRUCTION_FILE_BYTES);
+    const selectedLayers = selectLayers(scope, layers);
+    const text = joinInstructionTexts(selectedLayers.map((layer) => extractHarnessInstructions(layer.text, harness)));
+    return {
+        harness,
+        scope,
+        text,
+        sources: selectedLayers.map((layer) => ({
+            scope: layer.scope,
+            path: layer.path
+        })),
+        paths
+    };
+}
+export async function editInstructions(input = {}) {
+    const scope = input.scope ?? "user";
+    const options = input.options ?? {};
+    const paths = resolveInstructionPaths(options);
+    const filePath = paths[scope];
+    const created = ensureInstructionFile(filePath);
+    const editor = chooseEditor(options);
+    if (!editor) {
+        return { scope, path: filePath, created, opened: false, editor: null };
+    }
+    await runEditor(editor, filePath);
+    return { scope, path: filePath, created, opened: true, editor };
+}
+export function resetInstructions(input) {
+    const paths = resolveInstructionPaths(input.options ?? {});
+    const filePath = paths[input.scope];
+    const removed = fs.existsSync(filePath);
+    if (removed) {
+        fs.rmSync(filePath, { force: true });
+    }
+    return { scope: input.scope, path: filePath, removed };
+}
+export function resolveInstructionHarness(explicitHarness, identity) {
+    if (explicitHarness) {
+        return normalizeInstructionHarness(explicitHarness);
+    }
+    const displayName = identity?.process_metadata.display_name ?? undefined;
+    const fromDisplay = displayName ? HARNESS_ALIASES[normalizeKey(displayName)] : undefined;
+    if (fromDisplay) {
+        return fromDisplay;
+    }
+    const prefix = identity?.agent_id.split(":")[0];
+    const fromPrefix = prefix ? HARNESS_ALIASES[normalizeKey(prefix)] : undefined;
+    return fromPrefix ?? "all";
+}
+export function normalizeInstructionHarness(value) {
+    const normalized = HARNESS_ALIASES[normalizeKey(value)];
+    if (!normalized) {
+        throw new Error(`--harness must be one of claude, codex, gemini, opencode, all (got ${value}).`);
+    }
+    return normalized;
+}
+export function parseInstructionScope(value) {
+    if (!value) {
+        return "effective";
+    }
+    if (value === "effective" ||
+        value === "bundled" ||
+        value === "user" ||
+        value === "project") {
+        return value;
+    }
+    throw new Error(`--scope must be one of effective, bundled, user, project (got ${value}).`);
+}
+export function extractHarnessInstructions(markdown, harness) {
+    const trimmed = markdown.trim();
+    if (!trimmed || harness === "all") {
+        return trimmed;
+    }
+    const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+    const shared = [];
+    const sections = new Map();
+    let current = null;
+    let sawSection = false;
+    for (const line of lines) {
+        const header = parseHarnessHeader(line);
+        if (header) {
+            sawSection = true;
+            current = header;
+            if (!sections.has(current)) {
+                sections.set(current, []);
+            }
+            sections.get(current)?.push(line);
+            continue;
+        }
+        if (!sawSection) {
+            shared.push(line);
+            continue;
+        }
+        if (current) {
+            sections.get(current)?.push(line);
+        }
+    }
+    return joinInstructionTexts([
+        shared.join("\n").trim(),
+        sections.get(harness)?.join("\n").trim() ?? ""
+    ]);
+}
+function readInstructionLayers(paths, maxInstructionFileBytes) {
+    const layers = [
+        { scope: "bundled", path: null, text: DEFAULT_INSTRUCTIONS_MARKDOWN }
+    ];
+    for (const scope of ["user", "project"]) {
+        const filePath = paths[scope];
+        if (!fs.existsSync(filePath)) {
+            continue;
+        }
+        const stat = fs.statSync(filePath);
+        if (stat.size > maxInstructionFileBytes) {
+            throw new Error(`${scope} instructions file is too large (${stat.size} bytes, max ${maxInstructionFileBytes}): ${filePath}`);
+        }
+        const text = fs.readFileSync(filePath, "utf8");
+        layers.push({ scope, path: filePath, text });
+    }
+    return layers;
+}
+function selectLayers(scope, layers) {
+    if (scope === "effective") {
+        return layers;
+    }
+    return layers.filter((layer) => layer.scope === scope);
+}
+function joinInstructionTexts(parts) {
+    return parts
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .join("\n\n");
+}
+function ensureInstructionFile(filePath) {
+    if (fs.existsSync(filePath)) {
+        return false;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, DEFAULT_INSTRUCTIONS_MARKDOWN);
+    return true;
+}
+function parseHarnessHeader(line) {
+    const match = line.match(/^##\s+(.+?)\s*$/);
+    if (!match) {
+        return null;
+    }
+    const key = normalizeKey(match[1]);
+    if (key.startsWith("claude"))
+        return "claude";
+    if (key.startsWith("codex"))
+        return "codex";
+    if (key.startsWith("gemini"))
+        return "gemini";
+    if (key.startsWith("opencode"))
+        return "opencode";
+    return null;
+}
+function chooseEditor(options) {
+    const env = options.env ?? process.env;
+    const explicit = env.VISUAL?.trim() || env.EDITOR?.trim();
+    if (explicit) {
+        return explicit;
+    }
+    switch (options.platform ?? process.platform) {
+        case "darwin":
+            return "open -t";
+        case "win32":
+            return "notepad.exe";
+        default:
+            if (env.DISPLAY || env.WAYLAND_DISPLAY) {
+                return "xdg-open";
+            }
+            return null;
+    }
+}
+function runEditor(editor, filePath) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(`${editor} ${shellQuote(filePath)}`, {
+            stdio: "inherit",
+            shell: true
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`${editor} exited with code ${code}.`));
+        });
+    });
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function normalizeKey(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}

package/docs/plans/2026-05-06-harness-instructions-v6-converged.md

@@ -0,0 +1,220 @@
+# v6 converged design — harness instructions
+
+> **Status:** converged claude + codex design.
+>
+> **Convergence path:** independent drafts written in parallel, then debated
+> by cross-reference. Outcomes: claude conceded load-mechanism (separate
+> `tt instructions show` call, not piggyback on `tt join`); codex conceded
+> file-structure (single file per layer, not per-harness) and materialization
+> (lazy on edit, never on install). Naming, CLI surface, project-file scope,
+> and bundled-skill scope were already aligned.
+>
+> The pre-debate drafts (`v6-claude.md`, `v6-codex.md`) were deleted after
+> convergence per Wojtek: "if they write something they need to delete the
+> pre-debate versions after convergence."
+
+## Problem
+
+v5 collapsed the phase guidance into bundled `SKILL.md`. Wojtek's pushback:
+*"The skill ships with the binary, which means people won't be able to edit. I
+want them to be able to edit, but I still want it to be simple."* `tt install`
+links the bundled skill by default and startup sync can refresh copied
+installs — there is no durable user-edit affordance.
+
+v6 fixes this with editable Markdown instructions, seeded lazily, opened with
+`$EDITOR`. Not JSON profiles. Not a config subsystem.
+
+## Shape
+
+Two layers of concern, kept separate by design:
+
+### 1. Bundled skill floor (`skills/talking-stick/SKILL.md`)
+
+Immutable, package-owned. Covers join, wait, guardian checks, release/handoff,
+event-wake safety, takeover, notes, messages, and the "keep using the stick
+until done" rule. Tells agents how to load the editable collaboration
+instructions. **Does not include phase vocabulary or typical fits** — those
+live in the editable layer with bundled defaults as fallback inside the
+instructions code path, not duplicated into the safety contract.
+
+### 2. Editable collaboration instructions
+
+Single Markdown file per layer, with optional per-harness sections inside:
+
+```
+~/.local/share/talking-stick/instructions.md      # user override (optional, XDG-aware)
+<repo>/.talking-stick/instructions.md             # project override (optional)
+```
+
+Bundled defaults live as text constants in `src/instructions.ts` — they are
+the seed text and the always-available fallback if no editable file exists.
+
+The file uses `## <Harness>` section headers. The effective text for a given
+harness is: shared preamble (everything before the first `##`) + the matching
+harness section.
+
+## Effective-text resolution
+
+Additive concatenation in layer order: bundled → user → project. Later layers
+add or override by plain language; the model weighs the concatenated text. No
+merge semantics, no structured fields, no precedence rules beyond "later text
+typically wins by recency." Bundled safety floor (the SKILL.md content)
+remains higher than editable content always — operators cannot use
+instructions to override the coordination safety contract.
+
+## Loading
+
+Agents call `tt instructions show --json` once after `tt join` on the first
+substantial task in a room. The command infers the caller's harness from
+identity detection (no `--harness` flag needed). The JSON result includes the
+effective Markdown text and the file paths that contributed to it.
+
+If the command fails, agents continue with the bundled `SKILL.md` guidance
+alone. Coordination must never depend on instructions loading successfully.
+
+`tt join` returns membership/coordination state only; instructions are
+deliberately separate.
+
+## CLI surface
+
+```
+tt instructions show   [--harness <name>] [--scope effective|user|project|bundled] [--json]
+tt instructions edit   [--user|--project]
+tt instructions reset  [--user|--project]
+```
+
+- `show` defaults to `--scope effective` and the detected current harness.
+- `edit` opens `$VISUAL`, then `$EDITOR`, then a platform default if available;
+  prints the file path if no editor is found. Defaults to `--user`.
+- `edit` materializes the seed text on first use, then opens the editor.
+  Subsequent edits open the existing file in place.
+- `reset` requires explicit scope (no implicit `--user`); deletes the file at
+  the chosen scope so the layer below wins again.
+
+**Cut from both drafts:** `set`/`append`/`init`/`diff`. Editor-only for v1.
+Agents holding the stick can write to `<repo>/.talking-stick/instructions.md`
+directly via filesystem.
+
+## Materialization
+
+Lazy on first `tt instructions edit`, never on `tt install`. Reasoning:
+- Operators who never customize stay on shipped defaults forever — package
+  updates flow through automatically with no stale local copies.
+- Operators who customize get a one-time materialization at the moment they
+  show intent (running `edit`).
+- `tt install` stays fast and scriptable; no extra files written.
+
+`tt install` final output gains one hint:
+
+```
+Customize collaboration instructions with: tt instructions edit
+```
+
+No interactive prompt.
+
+## Bundled defaults (content)
+
+Text constants in `src/instructions.ts`. Short. Cover:
+
+- the "keep using Talking Stick until the shared task is done" rule,
+  including "prefer continued action unless the task is complete or the
+  operator explicitly redirects/stops",
+- the phase vocabulary: draft, adversarial review, convergence,
+  implementation, implementation review, test review, release,
+- typical fits (advisory, not enforced):
+  - Claude: prose, first-pass synthesis, tool-running, implementation review,
+    test review.
+  - Codex: adversarial review, convergence, implementation, edge cases,
+    release mechanics after operator approval.
+  - Gemini/OpenCode: conservative starter guidance until dogfood gives
+    evidence.
+
+These are defaults, not a scheduler. Talking Stick does not auto-route turns
+based on them.
+
+## Parallel drafting without workspace clutter
+
+Wojtek's target default is independent read-only planning first, then debate
+until convergence. His concern was not the independent thinking; it was
+workspace clutter and imposed file structure: *"I'm not sure I want to default
+to the models writing drafts or imposing a file structure on the workspace. I
+guess maybe if they write something they need to delete the pre-debate versions
+after convergence."*
+
+So the default is **read-only independent drafts**, not repo draft files.
+Rules when this happens:
+
+- **Drafts go in handoff `status` text or room notes by default**, not in
+  workspace files. Coordination channels are the natural place for read-only
+  position exchange.
+- **If files are unavoidable** (drafts too long for handoffs/notes), use
+  files in `docs/plans/` with clear `*-<harness>-draft.md` naming, and
+  **delete them after convergence**. Only the converged artifact remains.
+- Single-agent rooms and tiny tasks can skip parallel drafting.
+- The default for larger multi-agent planning is: draft independently, debate,
+  converge, then write only the converged artifact if a workspace file is
+  useful.
+
+This is still prompt guidance, not protocol. Talking Stick does not create
+draft files, track phases, or auto-route turns based on this pattern.
+
+## What we explicitly do not build
+
+- No JSON config, no schema, no validator beyond a soft size cap on read.
+- No structured merge semantics. Plain Markdown concatenation.
+- No `set`/`append`/`init`/`diff` commands.
+- No materialization on install.
+- No phase tracking in the protocol. No `tt phase set`. No `phase` field in
+  handoff types.
+- No `tt state` rendering changes.
+- No model overlays.
+- No auto-routing by harness.
+- No instruction-text override of the bundled safety floor.
+
+## Implementation order
+
+1. `src/instructions.ts` — bundled default text constants, layer resolver
+   (bundled → user → project, additive concatenation), XDG-aware path
+   resolution, `## <Harness>` section parser, soft size cap.
+2. Add `tt instructions show` (CLI + service plumbing).
+3. Add `tt instructions edit` with `$VISUAL` / `$EDITOR` / platform fallback.
+   Materializes seed on first use.
+4. Add `tt instructions reset`.
+5. Edit bundled `SKILL.md`: keep current safety contract, add one short line
+   pointing agents at `tt instructions show --json` after first `tt join`.
+6. Update `tt install` final output with the customize hint.
+7. Tests: `tests/instructions.test.ts` for layer resolution, missing files,
+   materialization-only-on-edit, section parsing, additive concatenation,
+   bundled-fallback when commands fail. Extend `tests/cli.test.ts` for the
+   new commands.
+8. README: replace `tt install-skill` references with `tt install`; add a
+   short paragraph on `tt instructions edit` for customization.
+9. Release notes entry.
+
+## Acceptance criteria
+
+- A fresh user can install with `npm i -g talking-stick && tt install --all`
+  and get useful defaults without answering prompts.
+- The same user can run `tt instructions edit` and customize collaboration
+  behavior in `$EDITOR`.
+- A package update never overwrites the user's instruction file.
+- An agent runs one command after join (`tt instructions show --json`) and
+  receives effective instruction text + source paths.
+- If instruction loading fails, the bundled `SKILL.md` still gives enough
+  guidance to coordinate safely (agents will lack phase vocabulary but
+  coordination/safety remains intact).
+- No new protocol state, no role enforcement, and no auto-routing are added.
+
+## Process notes (meta)
+
+This convergence used parallel-drafting one-off. Each harness wrote an
+independent v6 draft without reading the other's first. Both landed near
+the same shape but differed on three points (file structure, load
+mechanism, materialization). Reading both drafts side by side made the
+real trade-offs visible quickly; concessions went both ways within one
+round.
+
+The pre-debate draft files were deleted after convergence per Wojtek. The
+parallel-drafting workflow is captured above as an *optional* operator-
+driven pattern, not a shipped default — to avoid imposing file structure
+on workspaces by default.

package/docs/releases/0.4.0.md

@@ -0,0 +1,71 @@
+# Talking Stick 0.4.0
+
+Date: 2026-05-10
+
+This release adds editable collaboration instructions for harness roles and
+phase preferences while keeping the bundled Talking Stick skill as the
+coordination safety floor.
+
+## Added
+
+### Editable collaboration instructions
+
+New CLI surface:
+
+```bash
+tt instructions show
+tt instructions edit
+tt instructions reset
+```
+
+`show` returns the effective Markdown prompt for the detected harness. Effective
+instructions are layered as bundled defaults, user defaults, and project
+overrides. User instructions live under the Talking Stick data directory
+(`instructions.md`); project instructions live at
+`.talking-stick/instructions.md` in the workspace root.
+
+`edit` lazily materializes the default Markdown on first use and opens
+`$VISUAL`, `$EDITOR`, or a platform editor fallback. `reset` deletes the chosen
+user or project file so lower layers apply again.
+
+### Bundled defaults
+
+The shipped defaults describe the shared phase vocabulary:
+
+- draft
+- adversarial review
+- convergence
+- implementation
+- implementation review
+- test review
+- release
+
+They also include advisory harness fits for Claude, Codex, Gemini, and
+OpenCode. These defaults are prompt guidance only; Talking Stick does not track
+phase state or auto-route turns.
+
+### Skill loading
+
+The bundled `talking-stick` skill now tells agents to run
+`tt instructions show --json` after joining a room. If the command fails, agents
+continue with the bundled skill. Editable instructions can add local
+preferences, but they cannot override the core safety rules around joining,
+waiting, guardian checks, handoffs, event wakes, or takeover.
+
+## Changed
+
+- `tt install` prints a short customization hint after a successful skill
+  install: `Customize collaboration instructions with: tt instructions edit`.
+- The skill's re-entry guidance now says to prefer continued action until the
+  task is complete or the operator explicitly redirects or stops the room.
+
+## Verification
+
+```bash
+npm run typecheck
+npm run build
+npm test
+git diff --check
+node dist/cli.js instructions show --harness codex --scope bundled --json
+npm pack --dry-run
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI coordination tool for path-scoped agent handoffs.",
   "type": "module",
   "bin": {

package/skills/talking-stick/SKILL.md

@@ -60,6 +60,14 @@ tt join --json
 
 Keep the returned room id and canonical path in mind. The current working directory is the implicit path for normal commands; pass an explicit path only when coordinating a different directory or intentionally selecting a nested room.
 
+After joining, load editable collaboration instructions once:
+
+```sh
+tt instructions show --json
+```
+
+If that command fails, continue with this bundled skill. Editable instructions can add local preferences, but they do not override the safety rules in this skill.
+
 Right after joining, start a background ambient receiver so direct messages and turn passes/reservations surface as soon as they happen instead of waiting for the next time you poll:
 
 ```sh
@@ -214,10 +222,9 @@ The default after `tt release` or `tt assign` is to re-enter the wait loop and k
 Exit the wait loop only when one of these is true:
 
 - the shared task is explicitly finished
-- you are the only active member and there is no one to hand off to
 - the operator gives a direct redirect or stop
 
-In every other case, after `tt release` or `tt assign`, go straight back into `tt wait --json`.
+In every other case, after `tt release` or `tt assign`, go straight back into `tt wait --json`. Other-harness inactivity is not an exit signal; keep waiting or take the next useful action until the task is done.
 
 If the operator tells you to drop out of coordination, run `tt leave --json`. Rooms with no active members are deleted instead of kept as history, and long-idle rooms may be purged on later invocations.