walkie-talkie

# Walkie-Talkie ## Overview An append-only file mailbox, committed to the repo, that lets agent sessions communicate across platforms, machines, and time. Any agent that can read and write files can participate — no shared harness, API, or memory required. Git is the transport; the human audits both channels. **Core invariant: one writer per file, append-only.** Each agent owns exactly one outbox file. Nobody ever edits another agent's outbox, and nobody ever rewrites a past entry. This designs merge conflicts and clobbering out of existence. **Why a fixed protocol matters:** unaided agents invent *good but incompatible* mailbox formats. The value of this skill is convergence — every session that loads it speaks the same format, so channels compose across sessions that have never met. ## When to Use - Heterogeneous agents (Claude + Codex + Gemini…) sharing one repo - Handoff of in-flight work to a session that starts later - Parallel sessions on the same repo needing to coordinate shared surfaces - Cross-machine coordination (git push/pull moves the mailbox) **When NOT to use:** Claude Code sessions in the same harness on the same machine — use Agent Teams / SendMessage instead (push notifications beat polling). One-shot handoff with no return channel and nothing contested — a plain HANDOFF.md is enough, though the Grill (below) still applies on receipt. ## Setup (first agent creates the channel) 1. Create `comms/` next to the work it coordinates (repo-wide: `.agents/comms/`; sprint-scoped: `docs/<area>/comms/`). 2. Copy [PROTOCOL_TEMPLATE.md](PROTOCOL_TEMPLATE.md) into it as `README.md`, filling in the agent handles. 3. Create one outbox per agent, named `<HANDLE>.md` (e.g. `FABLE.md`, `CODEX.md`). Initialize peers' outboxes with a one-line pointer to the README so their first read routes them in. 4. Add a discovery shim to every bootstrap file the participating platforms auto-read — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`: *"In-repo agent mailbox at `<path>/comms/` — read its README.md and your inbox before changing anything. MANDATORY."* 5. Write your first entry: repo state, in-flight work with exact `file:line` for load-bearing state, known unknowns, and any `ACTION-REQUESTED`. 6. Commit the mailbox together with (or immediately after) the code it describes. ## Message Format Append to YOUR OWN outbox only: ```markdown ## [2026-07-03 14:05] STATUS: eval-surface rotation half-applied Re: — The 7-match gate is now the ONLY confirmation surface (src/ranker.py:4). build_cache() sort order is stale vs the bounce rule — main outstanding fix. ``` Header: `## [YYYY-MM-DD HH:MM] TYPE: subject`. `Re:` names the entry being answered (by timestamp+subject), or `—`. | Type | Meaning | |---|---| | `STATUS` | What I did / left half-done / decided. The workhorse. | | `ACTION-REQUESTED` | Peer must act or explicitly decline. Highest priority. | | `QUESTION` / `ANSWER` | Async request/response. ANSWER always sets `Re:`. | | `GRILL` | Handoff interrogation — evidence required (see below). | | `EVIDENCE` | Reply to a GRILL. Command output, SHAs, file:line — not assurances. | | `CLAIM` / `RELEASE` | Advisory lock on a named surface (exact paths). | | `ACK` | Received and understood; nothing further. | ## Checkpoint Discipline Read every peer outbox at: **session start**, **before starting a new slice of work**, **after completing one**. Answer open `ACTION-REQUESTED` and `GRILL` items addressed to you before starting new work. Write whenever you have verdicts, needs, or plans affecting shared surfaces, caches, or artifacts — not just at session end. ## The Grill On receiving a handoff, do not ACK politely — interrogate. Post a `GRILL` entry with pointed questions; the handing-off agent (this session or its next incarnation) must answer each with `EVIDENCE`, not assurances. Minimum grill set: 1. What did you **verify by running something** vs. merely believe? Show the command and output. 2. What is **half-applied** right now? Exact file:line of every load-bearing edit. 3. What breaks if I touch X? Which surfaces are **claimed**? 4. What do you know that is **written down nowhere** but this mailbox? 5. What would you check first if this were broken tomorrow? Any grill question that cannot be answered with evidence is recorded as a **RISK** in the answering entry — never silently dropped. Unanswered grills block `RELEASE` of the affected surface. ## Rules - Append-only. Never edit or delete a past entry (corrections are new entries with `Re:`). - Never write to another agent's outbox. - Concise and factual — exact paths, function names, constants. Write for an agent with zero shared context. - The human audits both channels; write nothing you wouldn't want audited. - Git history is the tiebreaker for what *happened*; the mailbox for what was *intended*. ## Common Mistakes | Mistake | Fix | |---|---| | Single shared LOG.md both agents write | One outbox per agent — sole-writer files can't conflict | | Editing an old entry to "update" it | New entry with `Re:` — audit trail must be immutable | | Polite ACK of a handoff | GRILL it — untested handoff claims are where bugs hide | | Mailbox only written at session end | Checkpoint cadence: start, before each slice, after each slice | | Protocol described only in chat | README.md in the comms dir + shims in CLAUDE.md/AGENTS.md/GEMINI.md | | Committing code without its mailbox entry | Commit them together — a pull must never show unexplained code | ## Prerequisites - A shared git repo both sessions can pull/push - Write access to create `comms/` (or an agreed path) and one outbox file per agent handle - Participating platforms that auto-read at least one bootstrap file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, …) ## Instructions Follow the Setup / Message Format / Grill sections above. Non-negotiables: 1. One writer per outbox file; append-only. 2. Never edit another agent's outbox. 3. Commit mailbox updates with the code they describe. 4. On handoff receipt, run the Grill before trusting claims. ## Output - A `comms/` (or agreed) mailbox directory with `README.md` (protocol) and `<HANDLE>.md` outboxes - Appended status / handoff / ACTION-REQUESTED entries with timestamps - Optional Grill notes on the receiving agent's outbox after interrogation ## Examples ### Two Claude sessions hand off mid-feature ``` Session A: /walkie-talkie set up comms at .agents/comms/ Session A: writes STATUS + handoff with file:line load-bearing state Session B: reads mailbox, grills ambiguous claims, continues work ``` ### Claude → Codex handoff ``` Session A (Claude): creates comms/, appends handoff entry Human: git push; opens Codex on same branch Session B (Codex): reads AGENTS.md → mailbox path → grills → continues ``` ## Edge Cases - **Same-harness Claude-only teams:** prefer Agent Teams / SendMessage; this skill is for heterogeneous or cross-machine sessions. - **Empty peer outbox:** initialize with a one-line pointer to README so first read routes correctly. - **Merge conflicts on outboxes:** design forbids multi-writer files; if it happens, treat as process break and re-split by handle. - **Stale handoff:** Grill for freshness (commit SHA, branch tip, uncommitted work) before applying. ## Resources - Protocol template: [PROTOCOL_TEMPLATE.md](PROTOCOL_TEMPLATE.md) - Package metadata: [package.json](package.json)