@sztlink/pi-ensemble 0.1.0-alpha.12

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+## v0.1.0-alpha.12
+
+- Documented neutral-root runtime usage: keep Pi/Claude in their natural runtime root and point to the canonical ledger with `PI_ENSEMBLE_ROOT` or `--root`.
+- Updated tmux wake adapter prompt to use `PI_ENSEMBLE_ROOT=... ensemble ...` instead of requiring `cd` into the ledger root.
+- Refreshed GitHub install docs for the latest alpha.
+
+## v0.1.0-alpha.11
+
+- Added lightweight message lifecycle without adding orchestration:
+  - generated message ids on `ensemble send`;
+  - inbox headers include `{#msg_...}` anchors;
+  - new `ensemble ack MESSAGE_ID` audit event;
+  - new `ensemble done MESSAGE_ID` resolution audit event;
+  - new `ensemble messages [--open]` read-only lifecycle view;
+  - `overview` includes recent open messages.
+- Added matching Pi command/tool actions and tests.
+
+## v0.1.0-alpha.10
+
+- Added `ensemble doctor` read-only ledger health checks:
+  - required protocol files;
+  - config protocol version;
+  - audit JSONL parse issues;
+  - agent name validity;
+  - unread/retained inbox summaries;
+  - claim path/owner sanity;
+  - nested `.pi-ensemble` detection for root-confusion dogfood.
+- Added matching Pi command/tool action and tests.
+
+## v0.1.0-alpha.9
+
+- Added dogfood ergonomics for retained inboxes:
+  - per-agent `lastReadAt` state;
+  - `unread` and `stale` counts in status/overview JSON;
+  - `ensemble inbox --since-last-read` for focused new-message reads without clearing history.
+- Updated overview text to show `total` vs `unread` instead of treating all retained messages as urgent.
+- Updated tmux wake prompts to suggest `--since-last-read`, reducing duplicate/manual relay friction.
+
+## v0.1.0-alpha.8
+
+- Added canonical root overrides for nested workspaces:
+  - CLI `--root PATH`;
+  - `PI_ENSEMBLE_ROOT` environment variable;
+  - Pi tool `root` parameter;
+  - Pi slash command `--root PATH`.
+- Documented root resolution to avoid accidental use of nested `.pi-ensemble/` ledgers.
+
+## v0.1.0-alpha.7 — publish candidate
+
+- Documented GitHub Pi package install path.
+- Added changelog and release framing for first public alpha.
+- Confirmed project-local Pi install from `git:github.com/sztlink/pi-ensemble@v0.1.0-alpha.6` in a clean temp workspace.
+
+## v0.1.0-alpha.6
+
+- Added read-only observability:
+  - `ensemble overview`
+  - `ensemble timeline`
+- Added matching Pi tool/command actions.
+- Expanded tests for overview/timeline.
+
+## v0.1.0-alpha.5
+
+- Added ledger inspection commands:
+  - `ensemble claims`
+  - `ensemble audit`
+- Added protocol version to `status`.
+- Expanded tests for audit and claims.
+
+## v0.1.0-alpha.4
+
+- Documented Claude Code Agent Teams interop.
+- Added runtime recipes for Pi, Claude Code, Codex/generic terminal agents, shell scripts, CI/watchers, and tmux.
+- Added Claude lead-session prompt example.
+
+## v0.1.0-alpha.3
+
+- Formalized adapter contract.
+- Added public `examples/ensemble-tmux` adapter.
+- Made tmux wake prompts shell-safe with `#` prefix.
+
+## v0.1.0-alpha.2
+
+- Hardened core ledger:
+  - agent name validation;
+  - message type validation;
+  - JSON outputs for adapter-facing commands;
+  - claim conflict protection and force override;
+  - blackboard recovery.
+- Added Node test suite.
+- Added quickstart and expanded spec.
+
+## v0.1.0-alpha.1
+
+- Added hybrid runtime adapter documentation.
+- Bumped alpha after documenting tmux/Pi/Claude boundaries.
+
+## v0.1.0-alpha.0
+
+- Initial public alpha.
+- CLI, core file protocol, Pi extension, blackboard, inboxes, claims, audit log, docs, and security boundary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 szt.link
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# pi-ensemble
+
+[![CI](https://github.com/sztlink/pi-ensemble/actions/workflows/ci.yml/badge.svg)](https://github.com/sztlink/pi-ensemble/actions/workflows/ci.yml)
+
+Shared workspace coordination ledger for parallel coding agents.
+
+`pi-ensemble` is a small local coordination ledger: blackboard + mailbox + claims + audit for developers who run multiple coding agents side by side. It is designed for Pi, Claude Code, Codex, or any terminal agent that can read and write files.
+
+It is **not** a daemon, process supervisor, remote-control system, or agent auto-runner.
+
+## Why
+
+When multiple coding agents work in parallel, the human becomes the relay: copy message here, paste result there, remember who owns which worktree. `pi-ensemble` turns that relay into a transparent local file protocol:
+
+```txt
+.pi-ensemble/
+  config.yaml
+  blackboard.md
+  agents/<name>/inbox.md
+  agents/<name>/state.json
+  worktrees.json
+  audit.jsonl
+```
+
+Files are the protocol. If the tool disappears, the state is still readable.
+
+## Quickstart
+
+See [`docs/QUICKSTART.md`](docs/QUICKSTART.md) for the shortest path. See [`docs/CLAUDE_AGENT_TEAMS.md`](docs/CLAUDE_AGENT_TEAMS.md) and [`docs/RUNTIME_RECIPES.md`](docs/RUNTIME_RECIPES.md) for interop patterns.
+
+## Install
+
+### Pi package from GitHub
+
+```bash
+pi install git:github.com/sztlink/pi-ensemble@v0.1.0-alpha.12
+```
+
+Reload Pi or start a new session, then run:
+
+```txt
+/ensemble status
+```
+
+### Local development
+
+```bash
+cd /path/to/repo
+pi install /absolute/path/to/pi-ensemble
+```
+
+### CLI only
+
+```bash
+node /absolute/path/to/pi-ensemble/bin/ensemble.mjs init
+```
+
+### npm
+
+The npm package is not published yet. Once published:
+
+```bash
+pi install npm:@sztlink/pi-ensemble@alpha
+```
+
+## CLI
+
+Use `--root PATH` or `PI_ENSEMBLE_ROOT=/path/to/workspace` when running from nested repositories, subdirectories, or neutral runtime roots. This lets Pi/Claude stay in their natural session root while sharing one canonical ledger elsewhere.
+
+```bash
+ensemble --root /path/to/workspace init [--agent pi]
+ensemble --root /path/to/workspace status
+ensemble note "message" [--from pi]
+ensemble send claude "handoff" [--from pi] [--type handoff]
+ensemble ack msg_xxx [--from claude] [--body "received"]
+ensemble done msg_xxx [--from pi] [--body "resolved"]
+ensemble messages [--open] [--limit 50] [--json]
+ensemble inbox [--agent pi] [--no-clear] [--since-last-read] [--clear] [--json]
+ensemble board [--json]
+ensemble claims [--json]
+ensemble audit [--limit 50] [--json]
+ensemble timeline [--limit 50] [--json]
+ensemble overview [--limit 10] [--json]
+ensemble doctor [--json]
+ensemble claim ./worktree-or-path [--agent pi] [--force] [--json]
+ensemble release ./worktree-or-path [--agent pi] [--force] [--json]
+```
+
+Allowed message types: `note`, `handoff`, `question`, `result`, `ack`.
+
+Inbox reads update per-agent `lastReadAt`. Use `--since-last-read` for focused wakeups: it prints only new messages, marks them read, and keeps retained history in `inbox.md`. `overview` reports both total retained messages and unread counts.
+
+Use `ensemble doctor` when a workflow feels off: it checks required files, protocol version, audit log parse health, claims, agent names, inbox state, and nested `.pi-ensemble` folders that can cause root confusion.
+
+Every `send` returns a message id and writes an inbox anchor like `{#msg_...}`. Use `ack` and `done` for lightweight traceability of handoffs/questions. They append audit events only; they do not schedule, route, or supervise agents.
+
+Canonical/root override examples:
+
+```bash
+# Neutral-root runtime: stay wherever the agent naturally starts, point at the ledger.
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble overview
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble inbox --agent claude --since-last-read
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble send pi "Result: ..." --from claude --type result
+
+# Equivalent explicit flag:
+ensemble --root /home/aya/implante inbox --agent pi --since-last-read
+```
+
+## Pi commands
+
+When installed as a Pi package, the extension exposes:
+
+```txt
+/ensemble init
+/ensemble status
+/ensemble note <message>
+/ensemble send <agent> <message> [--type note|handoff|question|result|ack]
+/ensemble inbox
+/ensemble board
+/ensemble claim <path>
+/ensemble release <path>
+```
+
+It also exposes an `ensemble` tool for the parent agent to perform the same file-only operations.
+
+## v0.1 boundaries
+
+See [`SECURITY.md`](SECURITY.md). In short: no network, no spawning, no command execution, no credentials, no hidden persistence, no remote sessions, no automatic routing.
+
+## Hybrid runtimes
+
+Pi can use the package extension and tool directly. Claude Code can participate directly or through a lead session that also uses Agent Teams internally. Codex and other terminal agents can participate through the same CLI/files. Tmux wakeups should remain an adapter outside the core protocol. See [`docs/ADAPTERS.md`](docs/ADAPTERS.md) and [`examples/ensemble-tmux`](examples/ensemble-tmux).
+
+## Relationship to existing workflows
+
+`pi-ensemble` generalizes a simple bridge pattern: blackboard for durable shared facts, inboxes for handoffs, audit log for traceability. Integrations with tmux, watchers, or external dashboards should remain outside v0.1.
+
+See [`docs/LANDSCAPE.md`](docs/LANDSCAPE.md) for a benchmark of related Claude Code, Pi, tmux, and terminal-agent orchestrators and why `pi-ensemble` stays smaller: local file protocol, not mission control. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the repositioning from would-be orchestrator toward neutral ledger + adapter protocol.
+
+## Repository decision
+
+Recommended public home: `sztlink/pi-ensemble` as a standalone repository, not inside a benchmark or application repo. The protocol is generic and should not inherit TurboQuant-specific context.

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Principles — pi-ensemble
+
+pi-ensemble is a local coordination layer for coding agents. These principles are fixed for v0.1; any violation is a bug, not a feature.
+
+## What pi-ensemble does
+
+- Reads and writes local files inside `.pi-ensemble/`.
+- Provides structured handoff, mailbox, blackboard, and worktree-claim files.
+- Logs inter-agent events to `audit.jsonl` for human review.
+
+## What pi-ensemble never does in v0.1
+
+1. **No network** — no HTTP, sockets, cloud sync, or webhooks.
+2. **No process spawning** — never creates, wakes, kills, or supervises agents.
+3. **No code execution** — never runs commands on behalf of an agent.
+4. **No credentials** — never handles, stores, extracts, or proxies secrets.
+5. **No hidden persistence** — no daemons, cron jobs, launch agents, or systemd units.
+6. **No remote sessions** — designed for single-user local development only.
+7. **No automatic routing** — humans decide which agent receives which handoff.
+
+## Threat model
+
+An actor who can write to `.pi-ensemble/` can place messages in agent inboxes. Treat inboxes and the blackboard like source files: review them before acting, keep normal filesystem permissions, and do not store secrets there.
+
+## Reporting
+
+If you discover behavior that violates these principles, open an issue or remove the package. The safe failure mode is to delete `.pi-ensemble/` and recreate it.

package/bin/ensemble.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import {
+  ack,
+  claim,
+  claims,
+  defaultAgent,
+  doctor,
+  done,
+  init,
+  messages,
+  note,
+  overview,
+  readAudit,
+  readBoard,
+  readInbox,
+  release,
+  requireWorkspaceRoot,
+  send,
+  status,
+  timeline,
+} from '../lib/core.mjs';
+
+function usage() {
+  console.log(`pi-ensemble
+
+Usage:
+  ensemble [--root PATH] init [--agent NAME]
+  ensemble [--root PATH] status
+  ensemble note MESSAGE [--from NAME] [--json]
+  ensemble send AGENT MESSAGE [--from NAME] [--type note|handoff|question|result|ack] [--json]
+  ensemble ack MESSAGE_ID [--from NAME] [--body TEXT] [--json]
+  ensemble done MESSAGE_ID [--from NAME] [--body TEXT] [--json]
+  ensemble messages [--limit N] [--open] [--json]
+  ensemble inbox [--agent NAME] [--no-clear] [--since-last-read] [--clear] [--json]
+  ensemble board [--json]
+  ensemble claims [--json]
+  ensemble audit [--limit N] [--json]
+  ensemble timeline [--limit N] [--json]
+  ensemble overview [--limit N] [--json]
+  ensemble doctor [--json]
+  ensemble claim PATH [--agent NAME] [--force] [--json]
+  ensemble release PATH [--agent NAME] [--force] [--json]
+`);
+}
+
+function takeFlag(args, name, fallback = undefined) {
+  const i = args.indexOf(name);
+  if (i === -1) return fallback;
+  const value = args[i + 1];
+  args.splice(i, 2);
+  return value ?? fallback;
+}
+
+function hasFlag(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return false;
+  args.splice(i, 1);
+  return true;
+}
+
+let explicitRoot;
+
+function root() {
+  return requireWorkspaceRoot(explicitRoot || process.env.PI_ENSEMBLE_ROOT || process.cwd());
+}
+
+function initRoot() {
+  return explicitRoot || process.env.PI_ENSEMBLE_ROOT || process.cwd();
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function formatTimeline(rows) {
+  return rows.map(row => `${row.ts ?? '?'} ${row.action ?? '?'} — ${row.summary}`).join('\n') + (rows.length ? '\n' : '');
+}
+
+function formatOverview(value) {
+  const lines = [];
+  lines.push(`root: ${value.root}`);
+  lines.push(`version: ${value.version}`);
+  lines.push(`agents: ${value.agents.map(a => `${a.agent}(${a.pending} total, ${a.unread} unread)`).join(', ') || 'none'}`);
+  lines.push(`unread: ${value.unread.map(a => a.agent).join(', ') || 'none'}`);
+  lines.push(`retained: ${value.stale.map(a => a.agent).join(', ') || 'none'}`);
+  lines.push(`claims: ${value.claims.length}`);
+  for (const claim of value.claims) lines.push(`  - ${claim.agent}: ${claim.path}`);
+  lines.push(`open messages: ${value.openMessages.length}`);
+  for (const message of value.openMessages) lines.push(`  - ${message.messageId}: ${message.from} → ${message.to} [${message.type}] ${message.status}`);
+  lines.push('recent:');
+  for (const row of value.recent) lines.push(`  - ${row.ts ?? '?'} ${row.action ?? '?'} — ${row.summary}`);
+  return lines.join('\n') + '\n';
+}
+
+function formatMessages(rows) {
+  return rows.map(row => `${row.messageId} ${row.status} — ${row.from ?? '?'} → ${row.to ?? '?'} [${row.type ?? '?'}]${row.doneBy ? ` done by ${row.doneBy}` : ''}`).join('\n') + (rows.length ? '\n' : '');
+}
+
+function formatDoctor(value) {
+  const lines = [];
+  lines.push(`root: ${value.root}`);
+  lines.push(`ok: ${value.ok ? 'yes' : 'no'}`);
+  lines.push(`summary: ${value.summary.pass} pass, ${value.summary.info} info, ${value.summary.warn} warn, ${value.summary.fail} fail`);
+  for (const check of value.checks) {
+    const mark = check.status === 'pass' ? '✓' : check.status === 'fail' ? '✗' : check.status === 'warn' ? '!' : 'i';
+    lines.push(`${mark} ${check.name}: ${check.message}`);
+    if (check.details) lines.push(`  details: ${JSON.stringify(check.details)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+try {
+  const args = process.argv.slice(2);
+  explicitRoot = takeFlag(args, '--root', undefined);
+  const cmd = args.shift() || 'help';
+  if (!explicitRoot) explicitRoot = takeFlag(args, '--root', undefined);
+  if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    usage();
+  } else if (cmd === 'init') {
+    const agent = takeFlag(args, '--agent', defaultAgent());
+    const r = init(initRoot(), { agent });
+    console.log(`initialized ${r.dir} (agent: ${r.agent})`);
+  } else if (cmd === 'status') {
+    const s = status(root());
+    printJson(s);
+  } else if (cmd === 'note') {
+    const from = takeFlag(args, '--from', defaultAgent());
+    const json = hasFlag(args, '--json');
+    const body = args.join(' ');
+    const result = note(root(), { from, body });
+    json ? printJson(result) : console.log('noted');
+  } else if (cmd === 'send') {
+    const from = takeFlag(args, '--from', defaultAgent());
+    const type = takeFlag(args, '--type', 'handoff');
+    const json = hasFlag(args, '--json');
+    const to = args.shift();
+    const body = args.join(' ');
+    const result = send(root(), { from, to, type, body });
+    json ? printJson(result) : console.log(`sent to ${to}: ${result.messageId}`);
+  } else if (cmd === 'ack') {
+    const from = takeFlag(args, '--from', defaultAgent());
+    const body = takeFlag(args, '--body', '');
+    const json = hasFlag(args, '--json');
+    const messageId = args.shift();
+    const result = ack(root(), { from, messageId, body: body || args.join(' ') });
+    json ? printJson(result) : console.log(`acked ${messageId}`);
+  } else if (cmd === 'done') {
+    const from = takeFlag(args, '--from', defaultAgent());
+    const body = takeFlag(args, '--body', '');
+    const json = hasFlag(args, '--json');
+    const messageId = args.shift();
+    const result = done(root(), { from, messageId, body: body || args.join(' ') });
+    json ? printJson(result) : console.log(`resolved ${messageId}`);
+  } else if (cmd === 'messages') {
+    const json = hasFlag(args, '--json');
+    const open = hasFlag(args, '--open');
+    const limit = Number(takeFlag(args, '--limit', '50'));
+    const result = messages(root(), { limit: Number.isFinite(limit) ? limit : 50, open });
+    json ? printJson(result) : process.stdout.write(formatMessages(result));
+  } else if (cmd === 'inbox') {
+    const agent = takeFlag(args, '--agent', defaultAgent());
+    const sinceLastRead = hasFlag(args, '--since-last-read');
+    const clearFlag = hasFlag(args, '--clear');
+    const noClear = hasFlag(args, '--no-clear');
+    const json = hasFlag(args, '--json');
+    const clear = clearFlag ? true : sinceLastRead ? false : !noClear;
+    const content = readInbox(root(), { agent, clear, sinceLastRead });
+    json ? printJson({ agent, clear, sinceLastRead, content }) : process.stdout.write(content);
+  } else if (cmd === 'board') {
+    const json = hasFlag(args, '--json');
+    const content = readBoard(root());
+    json ? printJson({ content }) : process.stdout.write(content);
+  } else if (cmd === 'claims') {
+    const json = hasFlag(args, '--json');
+    const result = claims(root());
+    json ? printJson(result) : printJson(result);
+  } else if (cmd === 'audit') {
+    const json = hasFlag(args, '--json');
+    const limit = Number(takeFlag(args, '--limit', '50'));
+    const result = readAudit(root(), { limit: Number.isFinite(limit) ? limit : 50 });
+    json ? printJson(result) : process.stdout.write(result.map(r => JSON.stringify(r)).join('\n') + (result.length ? '\n' : ''));
+  } else if (cmd === 'timeline') {
+    const json = hasFlag(args, '--json');
+    const limit = Number(takeFlag(args, '--limit', '50'));
+    const result = timeline(root(), { limit: Number.isFinite(limit) ? limit : 50 });
+    json ? printJson(result) : process.stdout.write(formatTimeline(result));
+  } else if (cmd === 'overview') {
+    const json = hasFlag(args, '--json');
+    const limit = Number(takeFlag(args, '--limit', '10'));
+    const result = overview(root(), { limit: Number.isFinite(limit) ? limit : 10 });
+    json ? printJson(result) : process.stdout.write(formatOverview(result));
+  } else if (cmd === 'doctor') {
+    const json = hasFlag(args, '--json');
+    const result = doctor(root());
+    json ? printJson(result) : process.stdout.write(formatDoctor(result));
+  } else if (cmd === 'claim') {
+    const agent = takeFlag(args, '--agent', defaultAgent());
+    const force = hasFlag(args, '--force');
+    const json = hasFlag(args, '--json');
+    const targetPath = args.join(' ');
+    const result = claim(root(), { agent, targetPath, force });
+    json ? printJson(result) : console.log(`claimed ${targetPath}`);
+  } else if (cmd === 'release') {
+    const agent = takeFlag(args, '--agent', defaultAgent());
+    const force = hasFlag(args, '--force');
+    const json = hasFlag(args, '--json');
+    const targetPath = args.join(' ');
+    const result = release(root(), { agent, targetPath, force });
+    json ? printJson(result) : console.log(`released ${targetPath}`);
+  } else {
+    usage();
+    process.exitCode = 2;
+  }
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+}

package/docs/ADAPTERS.md

@@ -0,0 +1,159 @@
+# pi-ensemble adapters
+
+`pi-ensemble` core is intentionally file-only. It does not spawn agents, send tmux keys, open sockets, or supervise processes.
+
+Adapters sit beside the core ledger to connect specific runtimes to the same files.
+
+## Adapter contract
+
+Adapters MAY:
+
+- call the `ensemble` CLI or tool;
+- write normal protocol messages through `note`, `send`, `claim`, and `release`;
+- read `status`, `board`, `inbox`, `worktrees.json`, and `audit.jsonl`;
+- keep runtime-specific local config outside the core protocol;
+- wake panes, render dashboards, mirror events, or bridge other queues.
+
+Adapters MUST:
+
+- keep durable coordination state in `.pi-ensemble/`;
+- put long messages in inbox/files, not in transport-specific prompts;
+- preserve human readability;
+- leave an audit trail for state-changing protocol operations;
+- tolerate missing agents/inboxes by creating or reporting them explicitly;
+- fail closed when a target runtime/pane is missing.
+
+Adapters MUST NOT:
+
+- treat tmux panes, process ids, session ids, provider/model names, or launcher state as core protocol fields;
+- store secrets in `.pi-ensemble/`;
+- hide coordination state in adapter-only databases;
+- mutate core files in shapes that the CLI cannot understand;
+- make the core depend on any specific runtime.
+
+Heuristic:
+
+```txt
+Needed to reconstruct ownership, decision, or outcome later? -> core ledger.
+Only needed to operate one runtime right now? -> adapter config/state.
+```
+
+## Safe wake pattern
+
+Transport prompts are lossy and runtime-specific. The safe pattern is:
+
+```bash
+ensemble send claude-lead "full handoff body" --from pi --type handoff
+# out-of-band wake carries only a short pointer
+```
+
+For tmux, wake text should be shell-safe. Prefix with `#` so accidental paste into a shell pane is a harmless comment, while Pi/Claude still receive a readable markdown-style prompt:
+
+```txt
+# pi-ensemble: new inbox item. Run: PI_ENSEMBLE_ROOT=/repo ensemble inbox --agent claude-lead --since-last-read
+```
+
+Do not paste long instructions through tmux. Put them in the inbox.
+
+## Pi adapter
+
+Install as a Pi package:
+
+```bash
+pi install /path/to/pi-ensemble
+# or, after publication:
+pi install git:github.com/sztlink/pi-ensemble@v0.1.0-alpha.2
+```
+
+After `/reload` or a new Pi session, Pi exposes:
+
+```txt
+/ensemble status
+/ensemble inbox
+/ensemble note <message>
+/ensemble send <agent> <message> [--type ...]
+```
+
+The registered `ensemble` tool exposes the same operations to the parent agent.
+
+Pi-specific guidance:
+
+- Pi can act as maestro, but that is a usage pattern, not a core feature.
+- Pi should record only durable facts, claims, handoffs, and outcomes.
+- Pi should use external orchestrators such as Claude Agent Teams when they already solve runtime-level parallelism.
+
+## Claude Code / Agent Teams adapter
+
+Claude Code does not need a native plugin for v0.1. It participates through the CLI and files:
+
+```bash
+# From the project root:
+ensemble status
+ensemble inbox --agent claude-lead --since-last-read
+ensemble note "durable fact" --from claude-lead
+ensemble send pi "handoff" --from claude-lead --type handoff
+ensemble claim ./path --agent claude-lead
+ensemble release ./path --agent claude-lead
+
+# Or from a neutral runtime root while using a canonical ledger elsewhere:
+PI_ENSEMBLE_ROOT=~/implante ensemble overview
+PI_ENSEMBLE_ROOT=~/implante ensemble inbox --agent claude-lead --since-last-read
+PI_ENSEMBLE_ROOT=~/implante ensemble send pi "Result: ..." --from claude-lead --type result
+```
+
+Recommended Claude lead-session habit:
+
+1. On start, inspect `ensemble overview` from the project root, or `PI_ENSEMBLE_ROOT=/canonical/root ensemble overview` from a neutral runtime root.
+2. If the lead has unread inbox items, read with `--since-last-read` first.
+3. If useful, use Claude Code Agent Teams internally.
+4. Mirror only durable milestones to `pi-ensemble`:
+   - accepted task frame;
+   - claimed files/worktrees;
+   - result pointers;
+   - final handoff;
+   - blockers requiring another runtime.
+5. Keep ephemeral intra-team chatter inside Claude's team system.
+
+## tmux adapter
+
+Tmux is a transport/wake layer, not part of the core protocol.
+
+An example adapter lives at:
+
+```txt
+examples/ensemble-tmux
+```
+
+It does exactly two durable things:
+
+1. Writes the real message to `.pi-ensemble/` using the CLI.
+2. Pastes a short shell-safe wake prompt into the target pane.
+
+Example:
+
+```bash
+examples/ensemble-tmux send claude-lead \
+  "Please read your inbox and run the requested review." \
+  --from pi \
+  --type handoff
+```
+
+This preserves the invariant: deleting the adapter still leaves the collaboration legible in `.pi-ensemble/`.
+
+## Dashboard / observability adapters
+
+Dashboards should be read-only by default:
+
+- render `blackboard.md`, inbox total/unread/stale counts, claims, and audit timeline;
+- do not become the source of truth;
+- if they mutate state, they should do so by invoking the same CLI/tool operations as everyone else.
+
+## Queue / bridge adapters
+
+Adapters for other message queues may mirror into `pi-ensemble`, but should avoid duplicating whole private transcripts. Mirror only:
+
+- external event id / URL / file pointer;
+- sender and recipient;
+- type (`handoff`, `question`, `result`, `ack`, `note`);
+- durable summary;
+- result pointer.