@sztlink/pi-ensemble 0.1.0-alpha.12

package/docs/QUICKSTART.md

@@ -0,0 +1,149 @@
+# pi-ensemble quickstart
+
+`pi-ensemble` is a local coordination ledger for coding agents. It does not start agents or move work between machines. It only writes readable files under `.pi-ensemble/`.
+
+## 1. Initialize a workspace
+
+```bash
+cd /path/to/project
+ensemble init --agent pi
+ensemble status
+```
+
+If you often work from nested repositories, subdirectories, or a neutral runtime root, pin the canonical ledger root:
+
+```bash
+export PI_ENSEMBLE_ROOT=/path/to/project
+ensemble overview
+# or per command:
+ensemble --root /path/to/project overview
+
+# Example: agent stays in /home/aya while ledger lives in /home/aya/implante
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble inbox --agent claude --since-last-read
+```
+
+This creates:
+
+```txt
+.pi-ensemble/
+  config.yaml
+  blackboard.md
+  agents/pi/inbox.md
+  agents/pi/state.json
+  worktrees.json
+  audit.jsonl
+```
+
+## 2. Record a durable fact
+
+```bash
+ensemble note "Decision: Pi is coordinating; Claude lead will run Agent Teams internally." --from pi
+ensemble board
+```
+
+Use the blackboard for facts that should outlive terminal scrollback.
+
+## 3. Send a handoff
+
+```bash
+ensemble send claude-lead \
+  "Please run a three-teammate Agent Teams review. Mirror only final findings back here." \
+  --from pi \
+  --type handoff
+```
+
+The receiver reads only new messages since its last read:
+
+```bash
+ensemble inbox --agent claude-lead --since-last-read
+```
+
+When the receiver is done:
+
+```bash
+ensemble send pi "Result: findings saved at docs/review.md" --from claude-lead --type result
+# Optional lifecycle trace:
+ensemble ack msg_xxx --from claude-lead --body "received"
+ensemble done msg_xxx --from pi --body "resolved"
+```
+
+## 4. Claim paths before concurrent work
+
+```bash
+ensemble claim lib/core.mjs --agent claude-lead
+```
+
+If another agent tries to claim the same path, `pi-ensemble` fails unless `--force` is used:
+
+```bash
+ensemble claim lib/core.mjs --agent pi
+# Path already claimed by claude-lead...
+```
+
+Release when done:
+
+```bash
+ensemble release lib/core.mjs --agent claude-lead
+```
+
+## 5. JSON mode for adapters
+
+Adapters can use JSON output:
+
+```bash
+ensemble inbox --agent pi --since-last-read --json
+ensemble claim docs/ROADMAP.md --agent pi --json
+ensemble claims --json
+ensemble audit --limit 20 --json
+ensemble timeline --limit 20
+ensemble messages --open
+ensemble overview
+ensemble doctor
+```
+
+## Pi usage
+
+After installing as a Pi package and reloading Pi:
+
+```txt
+/ensemble status
+/ensemble note durable fact
+/ensemble send claude-lead handoff text --type handoff
+/ensemble inbox
+```
+
+Pi also gets an `ensemble` tool with the same core actions.
+
+## Claude Code / Agent Teams usage
+
+Claude Code can participate through the CLI. See [`CLAUDE_AGENT_TEAMS.md`](CLAUDE_AGENT_TEAMS.md) for the full lead-session pattern.
+
+Recommended lead-session commands:
+
+```bash
+# from the project root, or prefix with PI_ENSEMBLE_ROOT=/canonical/root from a neutral runtime root
+ensemble overview
+ensemble inbox --agent claude-lead --since-last-read
+ensemble claim <path> --agent claude-lead
+ensemble note "Claude lead spawned Agent Teams internally; durable milestone only." --from claude-lead
+ensemble send pi "Result pointer: <path/url>" --from claude-lead --type result
+```
+
+Keep internal Agent Teams chatter inside Claude. Mirror only durable milestones, ownership, and outcomes into `pi-ensemble`.
+
+## tmux wake adapter
+
+If `ensemble-tmux` is available, use it only to wake panes. If you already wrote the long inbox message with `ensemble send`, use `wake` rather than `send` to avoid duplicate inbox entries:
+
+```bash
+ensemble-tmux wake claude-lead --message "New handoff in inbox"
+# or write + wake in one step:
+ensemble-tmux send claude-lead "New handoff in inbox" --from pi --type handoff
+```
+
+Rule:
+
+```txt
+long message -> .pi-ensemble inbox
+short wake ping -> tmux
+```

package/docs/ROADMAP.md

@@ -0,0 +1,313 @@
+# pi-ensemble roadmap
+
+The discovery that Claude Code Agent Teams already covers much of the “many Claude workers” vision clarifies the project rather than weakening it:
+
+> The stronger orchestrators become, the smaller `pi-ensemble` should remain.
+>
+> `pi-ensemble` is not the team manager. It is the local ledger/protocol that keeps cross-agent work legible, portable, and auditable.
+
+Core invariant:
+
+> If Pi, Claude Code, tmux, or any adapter disappears, the coordination history must still be readable from files.
+
+## Thesis — form should follow coordination behavior
+
+The durable behavior in hybrid coding workspaces is not “spawn N workers”. It is:
+
+- hand off intent;
+- record durable facts;
+- mark ownership;
+- point to results;
+- leave an audit trail;
+- wake another runtime when needed.
+
+That behavior suggests a smaller form:
+
+```txt
+blackboard + inbox + claims + audit
+```
+
+Not this:
+
+```txt
+scheduler + team manager + lifecycle controller
+```
+
+`pi-ensemble` should express the trace of collaboration, not control the collaboration itself.
+
+## Positioning
+
+`pi-ensemble` sits between runtimes and orchestrators, not above them.
+
+```txt
+Felipe
+  ↓
+Pi maestro / Claude lead / Claude Agent Teams / Codex / other agents
+  ↕
+pi-ensemble core ledger
+  ↕
+tmux wake adapter / dashboards / launchers / watchers / bridges
+```
+
+What stays inside other systems:
+
+- Agent Teams task decomposition;
+- worker topology and specialist roles;
+- session lifecycle, resume, shutdown;
+- provider/model-specific routing;
+- launcher and pane management.
+
+What belongs in `pi-ensemble`:
+
+- durable handoffs across runtimes;
+- shared facts worth keeping;
+- path/worktree ownership;
+- result pointers;
+- audit trail;
+- minimal coordination state a human can inspect.
+
+## Design principles
+
+1. **Core stays file-only** — no daemon, no spawn, no network, no tmux dependency.
+2. **Core is a ledger, not a runtime** — record coordination state; do not supervise sessions.
+3. **No team model in core** — no fixed maestro/worker abstraction, even if some users adopt that pattern.
+4. **Humans can inspect everything** — deleting the adapters must leave the work legible.
+5. **Claims before concurrency** — path/worktree ownership must be explicit when work overlaps.
+6. **Adapters translate, core does not command** — wakeups, dashboards, launchers, mirrors live outside core.
+7. **Protocol neutrality wins** — Pi, Claude Code, Codex, and future agents should all fit without special privilege.
+
+## Current state — v0.1 alpha
+
+Implemented:
+
+- CLI: `init`, `status`, `note`, `send`, `inbox`, `board`, `claim`, `release`.
+- Core file layout under `.pi-ensemble/`.
+- Markdown blackboard and inboxes.
+- JSON audit log and worktree/path claims.
+- Pi package extension with slash command and tool.
+- Local `ensemble-tmux` adapter.
+- Docs: `SPEC`, `SECURITY`, `AUDIT`, `ADAPTERS`, `LANDSCAPE`.
+
+Known limitations:
+
+- No formal adapter contract yet.
+- No JSON-first output mode for easy machine bridging.
+- Claim conflict policy is still minimal.
+- Inbox read/ack semantics are intentionally simple.
+- No versioned migration policy yet.
+- Slash command parsing is intentionally minimal.
+
+## Cuts / reframes from the previous roadmap
+
+These items should be removed from the core product direction or demoted to adapters/docs:
+
+- **No evolution toward a built-in maestro/workers system.** That is a usage pattern, not the product.
+- **No `dispatch` / `collect` core CLI.** If they exist later, they should be thin wrappers or external helpers.
+- **No core task engine as scheduler.** At most, future task files should be receipts/mirrors, not runtime control.
+- **No agent registry or session discovery in core.** Runtime presence belongs to adapters.
+- **No pane/window orchestration in core.** tmux stays a wake transport only.
+- **No Claude-only UX clone of Agent Teams.** Competing at that layer is a category error.
+
+## Priority reset
+
+### Phase 1 — Harden the ledger
+
+Goal: make the current substrate boring, inspectable, and stable.
+
+Deliverables:
+
+- Add minimal tests for core operations using the Node test runner.
+- Add validation for agent names, message types, and claim targets.
+- Add `--json` output for `status`, `inbox`, `board`, and claim state where useful.
+- Improve claim behavior:
+  - warn or fail on already-claimed paths;
+  - record previous owner in audit;
+  - document shared/read-only claim conventions.
+- Add explicit protocol version metadata.
+- Add `docs/QUICKSTART.md` with Pi, Claude Code, Agent Teams lead-session, and generic terminal examples.
+
+Acceptance:
+
+```txt
+A new user can install pi-ensemble, initialize a repo, run a cross-runtime handoff, inspect the files, and understand what happened without reading source code.
+```
+
+### Phase 2 — Define the adapter contract
+
+Goal: make adapters first-class without polluting core.
+
+Deliverables:
+
+- Document a minimal adapter contract in `docs/ADAPTERS.md`:
+  - what adapters may write;
+  - what must remain durable;
+  - what belongs only in local adapter config;
+  - safe wake pattern: long body in inbox, short ping out-of-band.
+- Clarify which fields are protocol and which are adapter metadata.
+- Document how adapters should preserve auditability when mirroring external events.
+- Keep `ensemble-tmux` explicitly separate from core package concerns.
+
+Acceptance:
+
+```txt
+A tmux bridge, a dashboard, and a Claude-side helper can all interoperate with the same .pi-ensemble folder without introducing hidden state into core.
+```
+
+### Phase 3 — Claude Agent Teams interop
+
+Goal: make `pi-ensemble` useful beside Agent Teams instead of against it.
+
+Status: first docs/examples landed in `docs/CLAUDE_AGENT_TEAMS.md` and `examples/claude-agent-teams-lead.md`.
+
+Deliverables:
+
+- Document the recommended pattern:
+  - Pi or a human talks to a Claude lead session;
+  - the lead may use Agent Teams internally;
+  - only durable cross-runtime milestones get mirrored into `pi-ensemble`.
+- Provide examples for when to mirror:
+  - claim ownership before major edits;
+  - record durable facts to blackboard;
+  - send result/handoff back to Pi or another runtime;
+  - keep ephemeral intra-team chatter out of core.
+- If tooling is added, keep it as an optional bridge that writes normal `pi-ensemble` files.
+
+Acceptance:
+
+```txt
+A Claude lead session can use Agent Teams internally while Pi still sees durable handoffs, ownership, and outcomes through pi-ensemble.
+```
+
+### Phase 4 — Neutral multi-runtime interop
+
+Goal: make the protocol feel native to more than Pi and Claude.
+
+Deliverables:
+
+- Harden the Pi package surface.
+- Add Codex/OpenCode/generic CLI recipes.
+- Document claim conventions for worktrees vs paths.
+- Consider tiny helper scripts/examples for other runtimes to append notes, results, and claims without needing a full plugin.
+
+Acceptance:
+
+```txt
+Pi, Claude Code, Codex, and a plain shell script can all participate in the same coordination ledger with no runtime having special authority.
+```
+
+### Phase 5 — Read-only observability
+
+Goal: add visibility without turning the project into mission control.
+
+Status: first CLI/tool inspection landed with `ensemble overview`, `ensemble timeline`, and `ensemble doctor`.
+
+Possible deliverables:
+
+- Read-only dashboard rendering `.pi-ensemble/`.
+- Timeline/audit viewer.
+- Claim inspector.
+- Activity summarizer.
+
+Rule:
+
+```txt
+Observe from the files first. Do not move control back into the dashboard.
+```
+
+### Phase 6 — v1.0 stability
+
+Goal: freeze the file protocol.
+
+Required:
+
+- Versioned spec for `.pi-ensemble/` layout.
+- Migration policy.
+- Compatibility tests for old state folders.
+- Security review.
+- Public examples.
+- npm publication decision.
+
+Non-goals for v1.0:
+
+- no daemon;
+- no remote sync;
+- no auto-spawn;
+- no background autonomous workers;
+- no credential handling;
+- no mandatory tmux;
+- no built-in team manager.
+
+## Core vs adapter boundary
+
+Visible in core ledger:
+
+- blackboard notes that matter later;
+- inbox handoffs, questions, results, acknowledgements;
+- path/worktree claims;
+- audit events;
+- minimal agent names and timestamps;
+- pointers to external artifacts when needed.
+
+Keep outside core / adapter zone:
+
+- pane IDs and tmux window mapping;
+- spawn/stop/shutdown/resume semantics;
+- Agent Teams topology and worker count;
+- provider/model details;
+- prompt assembly and ephemeral chatter;
+- heartbeats, retries, polling loops;
+- launcher state and session discovery.
+
+Heuristic:
+
+> If the information is needed to reconstruct ownership, decisions, or outcomes, it belongs in core.
+>
+> If the information is only needed to operate a specific runtime, keep it in the adapter.
+
+## Immediate dogfood test
+
+Run the next test on the project itself with the new positioning:
+
+```txt
+Pi:
+  frames the task, consolidates, and keeps the shared question alive.
+
+Claude lead:
+  may use Agent Teams internally for execution/review if useful,
+  but mirrors only durable milestones into pi-ensemble.
+
+Codex or another agent:
+  contributes a bounded audit/review through the same inbox/claim protocol.
+
+Tmux:
+  only wakes sessions.
+```
+
+Success criteria:
+
+- Felipe can still talk to one lead surface at a time.
+- `pi-ensemble` stores cross-runtime coordination, not every internal team interaction.
+- Claims prevent overlapping edits across runtimes.
+- Pi can reconstruct the story from `.pi-ensemble/` alone.
+- Replacing Agent Teams with another orchestrator would not break the protocol.
+
+## Public framing
+
+Use:
+
+```txt
+shared workspace coordination ledger for coding agents
+blackboard + mailbox + claims protocol for local coding agents
+structured handoff layer for hybrid coding workflows
+```
+
+Avoid:
+
+```txt
+swarm
+hivemind
+control plane
+agent command bus
+autonomous workforce
+Agent Teams replacement
+```

package/docs/RUNTIME_RECIPES.md

@@ -0,0 +1,111 @@
+# Runtime recipes
+
+These recipes show how different coding-agent runtimes can participate in the same `.pi-ensemble/` ledger without needing native plugins.
+
+## Common rules
+
+All runtimes should:
+
+1. Start from the project root, or stay in a neutral runtime root and set `PI_ENSEMBLE_ROOT=/path/to/project`.
+2. Read `ensemble overview`.
+3. Read their new inbox items with `--since-last-read` before broad/clearing reads.
+4. Claim paths before edits.
+5. Record durable facts with `ensemble note`.
+6. Return exact result pointers with `ensemble send <target> ... --type result`.
+7. Release claims when done.
+
+## Pi
+
+Pi has a native package extension and tool. Use Pi for field framing, synthesis, and cross-runtime decisions.
+
+```txt
+/ensemble status
+/ensemble inbox
+/ensemble note <durable fact>
+/ensemble send claude-lead <handoff> --type handoff
+```
+
+Recommended Pi role:
+
+- keep the question alive;
+- decide what should be mirrored;
+- avoid becoming a relay by hand;
+- use Claude Agent Teams when Claude-only parallelism is enough.
+
+## Claude Code lead
+
+Claude can use the CLI directly. If Claude starts in a neutral runtime root, prefix commands with `PI_ENSEMBLE_ROOT=/canonical/ledger/root`:
+
+```bash
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble inbox --agent claude-lead --since-last-read
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble ack msg_xxx --from claude-lead --body "received"
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble claim src/foo.ts --agent claude-lead
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble note "Started Agent Teams review for src/foo.ts" --from claude-lead
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble send pi "Result: findings at docs/foo-review.md" --from claude-lead --type result
+PI_ENSEMBLE_ROOT=/home/aya/implante ensemble release src/foo.ts --agent claude-lead
+```
+
+If using native Agent Teams, mirror only durable milestones. See `CLAUDE_AGENT_TEAMS.md`.
+
+## Codex / generic terminal agent
+
+Any terminal agent can use the CLI:
+
+```bash
+cd /path/to/project
+ensemble inbox --agent codex --since-last-read
+ensemble claim tests/foo.test.ts --agent codex
+# do work
+ensemble send pi "Result: tests added at tests/foo.test.ts" --from codex --type result
+ensemble release tests/foo.test.ts --agent codex
+```
+
+If the runtime prefers JSON:
+
+```bash
+ensemble status
+ensemble inbox --agent codex --since-last-read --json
+ensemble claim tests/foo.test.ts --agent codex --json
+```
+
+## Plain shell script
+
+A script can mirror external events without being an agent runtime:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+cd /path/to/project
+ensemble note "CI finished: $GITHUB_RUN_URL" --from ci-bot
+ensemble send pi "CI result: $GITHUB_RUN_URL" --from ci-bot --type result
+```
+
+Use stable agent names such as `ci-bot`, `watcher`, `bench-runner`, or `github-mirror`.
+
+## tmux wake adapter
+
+Use tmux only to wake a pane after writing the real message. If the message already exists in the inbox, use `wake`; if not, `send` can write + wake in one step:
+
+```bash
+ensemble-tmux wake claude-lead --message "Read your pi-ensemble inbox"
+ensemble-tmux send claude-lead "Read your pi-ensemble inbox" --from pi --type handoff
+```
+
+The wake prompt should be shell-safe and short. Long message bodies belong in inbox files.
+
+## Worktree convention
+
+If each runtime works in a separate git worktree, claim the worktree root:
+
+```bash
+ensemble claim ../worktrees/feature-a --agent claude-lead
+```
+
+If multiple runtimes share a worktree, claim specific paths:
+
+```bash
+ensemble claim src/auth --agent claude-lead
+ensemble claim tests/auth.test.ts --agent codex
+```
+
+Do not use `--force` unless a human/Pi intentionally resolves ownership.

package/docs/SPEC.md

@@ -0,0 +1,132 @@
+# pi-ensemble v0.1-alpha spec
+
+## Purpose
+
+A local, file-based coordination protocol for parallel coding agents operated by one developer.
+
+## Non-goals
+
+- Agent spawning or supervision
+- Network sync or remote execution
+- Automatic LLM routing
+- Git hooks or background daemons
+- Secrets management
+- Multi-user collaboration
+
+## Protocol version
+
+`config.yaml` stores `version: 1`. v0.1 treats this as the file-protocol version.
+
+## Directory layout
+
+```txt
+.pi-ensemble/
+  config.yaml
+  blackboard.md
+  agents/
+    <name>/
+      inbox.md
+      inbox.read.md  # created lazily on first cleared inbox read
+      state.json
+  worktrees.json
+  audit.jsonl
+```
+
+## Agent names
+
+Agent names must match:
+
+```txt
+^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
+```
+
+Examples: `pi`, `claude`, `claude-lead`, `codex.1`.
+
+## Message types
+
+- `note`: durable shared observation
+- `handoff`: actionable transfer of responsibility
+- `question`: explicit question needing answer
+- `result`: completed output or artifact pointer
+- `ack`: acknowledgement / receipt
+
+## Message ids and lifecycle
+
+`ensemble send` creates a message id (`msg_...`) and writes it into the inbox heading as an anchor:
+
+```md
+## 2026-05-06T... — pi → claude [question] {#msg_abc123...}
+```
+
+Message lifecycle is audit-only:
+
+- `ack MESSAGE_ID`: recipient or observer records receipt/acceptance;
+- `done MESSAGE_ID`: actor records that the handoff/question is resolved;
+- `messages [--open]`: reconstructs lifecycle state from `audit.jsonl`.
+
+No scheduler, router, retry loop, or process state is implied by these events.
+
+## Inbox read state
+
+Each agent has `state.json`. `lastReadAt` is updated whenever that agent reads its inbox, including non-clearing reads. Status/overview expose:
+
+- `pending`: total retained message blocks in `inbox.md`;
+- `unread`: retained messages newer than `lastReadAt`;
+- `stale`: retained messages already read but not cleared.
+
+`ensemble inbox --since-last-read` returns only unread messages, marks them read, and does not clear retained history unless `--clear` is also passed.
+
+## Claims
+
+`worktrees.json` maps resolved paths to current owner metadata:
+
+```json
+{
+  "/repo/src/foo.ts": { "agent": "claude", "since": "..." }
+}
+```
+
+A path claimed by another agent cannot be overwritten or released unless the caller uses a force override. Overrides are audited and keep the previous owner in the audit record.
+
+## Root resolution
+
+By default, commands search upward from the current directory until they find `.pi-ensemble/`.
+
+For nested repositories or canonical shared ledgers, callers can override root resolution with:
+
+```bash
+PI_ENSEMBLE_ROOT=/path/to/workspace ensemble overview
+ensemble --root /path/to/workspace overview
+```
+
+The Pi extension/tool accepts the same concept via `--root` in slash commands or a `root` parameter in the tool.
+
+## Machine-readable output
+
+The CLI supports `--json` for operations that adapters commonly consume: `note`, `send`, `ack`, `done`, `messages`, `inbox`, `board`, `claims`, `audit`, `timeline`, `overview`, `doctor`, `claim`, and `release`. `status` is JSON by default.
+
+## Health checks
+
+`ensemble doctor` is read-only observability for ledger hygiene. It checks required protocol files, config version, audit JSONL parse issues, agent names, unread/retained inbox summaries, claim path/owner sanity, and nested `.pi-ensemble` folders under the selected root.
+
+## Invariants
+
+1. All state is human-readable.
+2. All state-changing operations append an event to `audit.jsonl`.
+3. The package never starts processes or runs shell commands.
+4. The package never opens network connections.
+5. Deleting `.pi-ensemble/` fully resets the protocol.
+6. Adapters may wake or visualize runtimes, but the durable source of truth remains `.pi-ensemble/`.
+
+## Pi package surface
+
+- Slash command: `/ensemble ...`
+- Tool: `ensemble({ action, agent, to, type, body, path, clear, sinceLastRead })`
+- CLI: `ensemble ...`
+
+## v0.1 done when
+
+- `ensemble init/status/note/send/inbox/board/claim/release` work locally.
+- Pi extension exposes the same operations.
+- SECURITY.md clearly states no network/spawn/exec/credentials/persistence.
+- README frames this as shared workspace coordination, not command/control.