From a5c2589c7d464acd856f0176cf2034d75194993f Mon Sep 17 00:00:00 2001 From: teernisse Date: Wed, 18 Feb 2026 21:52:10 -0500 Subject: [PATCH] docs: migrate agent coordination from MCP Agent Mail to Liquid Mail Replace all MCP Agent Mail references with Liquid Mail in AGENTS.md and CLAUDE.md. The old system used file reservations and MCP-based messaging with inbox/outbox/thread semantics. Liquid Mail provides a simpler post-based shared log with topic-scoped messages, decision conflict detection, and polling via the liquid-mail CLI. Key changes: - Remove entire MCP Agent Mail section (identity registration, file reservations, macros vs granular tools, common pitfalls) - Update Beads integration workflow to reference Liquid Mail: replace reservation + announce patterns with post-based progress logging and decision-first workflows - Update bv scope boundary note to reference Liquid Mail - Append full Liquid Mail integration block to CLAUDE.md: conventions, typical flow, decision conflicts, posting format, topic rules, context refresh, live updates, mapping cheat-sheet, quick reference - Add .liquid-mail.toml project configuration (Honcho backend) --- AGENTS.md | 96 +++++---------------- CLAUDE.md | 248 ++++++++++++++++++++++++++++++++++++++---------------- 2 files changed, 200 insertions(+), 144 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 139acfc..b42a6e5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -127,66 +127,17 @@ Prefer deterministic lab-runtime tests for concurrency-sensitive behavior. --- -## MCP Agent Mail — Multi-Agent Coordination - -A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources. Provides identities, inbox/outbox, searchable threads, and advisory file reservations with human-auditable artifacts in Git. - -### Why It's Useful - -- **Prevents conflicts:** Explicit file reservations (leases) for files/globs -- **Token-efficient:** Messages stored in per-project archive, not in context -- **Quick reads:** `resource://inbox/...`, `resource://thread/...` - -### Same Repository Workflow - -1. **Register identity:** - ``` - ensure_project(project_key=) - register_agent(project_key, program, model) - ``` - -2. **Reserve files before editing:** - ``` - file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true) - ``` - -3. **Communicate with threads:** - ``` - send_message(..., thread_id="FEAT-123") - fetch_inbox(project_key, agent_name) - acknowledge_message(project_key, agent_name, message_id) - ``` - -4. **Quick reads:** - ``` - resource://inbox/{Agent}?project=&limit=20 - resource://thread/{id}?project=&include_bodies=true - ``` - -### Macros vs Granular Tools - -- **Prefer macros for speed:** `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake` -- **Use granular tools for control:** `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message` - -### Common Pitfalls - -- `"from_agent not registered"`: Always `register_agent` in the correct `project_key` first -- `"FILE_RESERVATION_CONFLICT"`: Adjust patterns, wait for expiry, or use non-exclusive reservation -- **Auth errors:** If JWT+JWKS enabled, include bearer token with matching `kid` - ---- - ## Beads (br) — Dependency-Aware Issue Tracking -Beads provides a lightweight, dependency-aware issue database and CLI (`br` / beads_rust) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging and file reservations. +Beads provides a lightweight, dependency-aware issue database and CLI (`br` / beads_rust) for selecting "ready work," setting priorities, and tracking status. It complements Liquid Mail's shared log for progress, decisions, and cross-session context. **Note:** `br` is non-invasive—it never executes git commands directly. You must run git commands manually after `br sync --flush-only`. ### Conventions -- **Single source of truth:** Beads for task status/priority/dependencies; Agent Mail for conversation and audit -- **Shared identifiers:** Use Beads issue ID (e.g., `br-123`) as Mail `thread_id` and prefix subjects with `[br-123]` -- **Reservations:** When starting a task, call `file_reservation_paths()` with the issue ID in `reason` +- **Single source of truth:** Beads for task status/priority/dependencies; Liquid Mail for conversation/decisions +- **Shared identifiers:** Include the Beads issue ID in posts (e.g., `[br-123] Topic validation rules`) +- **Decisions before action:** Post `DECISION:` messages before risky changes, not after ### Typical Agent Flow @@ -195,35 +146,34 @@ Beads provides a lightweight, dependency-aware issue database and CLI (`br` / be br ready --json # Choose highest priority, no blockers ``` -2. **Reserve edit surface (Mail):** - ``` - file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="br-123") +2. **Check context (Liquid Mail):** + ```bash + liquid-mail notify # See what changed since last session + liquid-mail query "br-123" # Find prior discussion on this issue ``` -3. **Announce start (Mail):** - ``` - send_message(..., thread_id="br-123", subject="[br-123] Start: ", ack_required=true) +3. **Work and log progress:** + ```bash + liquid-mail post --topic <workstream> "[br-123] START: <description>" + liquid-mail post "[br-123] FINDING: <what you discovered>" + liquid-mail post --decision "[br-123] DECISION: <what you decided and why>" ``` -4. **Work and update:** Reply in-thread with progress - -5. **Complete and release:** +4. **Complete (Beads is authority):** ```bash br close br-123 --reason "Completed" + liquid-mail post "[br-123] Completed: <summary with commit ref>" ``` - ``` - release_file_reservations(project_key, agent_name, paths=["src/**"]) - ``` - Final Mail reply: `[br-123] Completed` with summary ### Mapping Cheat Sheet -| Concept | Value | -|---------|-------| -| Mail `thread_id` | `br-###` | -| Mail subject | `[br-###] ...` | -| File reservation `reason` | `br-###` | -| Commit messages | Include `br-###` for traceability | +| Concept | In Beads | In Liquid Mail | +|---------|----------|----------------| +| Work item | `br-###` (issue ID) | Include `[br-###]` in posts | +| Workstream | — | `--topic auth-system` | +| Subject prefix | — | `[br-###] ...` | +| Commit message | Include `br-###` | — | +| Status | `br update --status` | Post progress messages | --- @@ -231,7 +181,7 @@ Beads provides a lightweight, dependency-aware issue database and CLI (`br` / be bv is a graph-aware triage engine for Beads projects (`.beads/beads.jsonl`). It computes PageRank, betweenness, critical path, cycles, HITS, eigenvector, and k-core metrics deterministically. -**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (messaging, work claiming, file reservations), use MCP Agent Mail. +**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (progress logging, decisions, cross-session context), use Liquid Mail. **CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.** diff --git a/CLAUDE.md b/CLAUDE.md index ee27019..712c6cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -127,66 +127,19 @@ Prefer deterministic lab-runtime tests for concurrency-sensitive behavior. --- -## MCP Agent Mail — Multi-Agent Coordination - -A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources. Provides identities, inbox/outbox, searchable threads, and advisory file reservations with human-auditable artifacts in Git. - -### Why It's Useful - -- **Prevents conflicts:** Explicit file reservations (leases) for files/globs -- **Token-efficient:** Messages stored in per-project archive, not in context -- **Quick reads:** `resource://inbox/...`, `resource://thread/...` - -### Same Repository Workflow - -1. **Register identity:** - ``` - ensure_project(project_key=<abs-path>) - register_agent(project_key, program, model) - ``` - -2. **Reserve files before editing:** - ``` - file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true) - ``` - -3. **Communicate with threads:** - ``` - send_message(..., thread_id="FEAT-123") - fetch_inbox(project_key, agent_name) - acknowledge_message(project_key, agent_name, message_id) - ``` - -4. **Quick reads:** - ``` - resource://inbox/{Agent}?project=<abs-path>&limit=20 - resource://thread/{id}?project=<abs-path>&include_bodies=true - ``` - -### Macros vs Granular Tools - -- **Prefer macros for speed:** `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake` -- **Use granular tools for control:** `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message` - -### Common Pitfalls - -- `"from_agent not registered"`: Always `register_agent` in the correct `project_key` first -- `"FILE_RESERVATION_CONFLICT"`: Adjust patterns, wait for expiry, or use non-exclusive reservation -- **Auth errors:** If JWT+JWKS enabled, include bearer token with matching `kid` - --- ## Beads (br) — Dependency-Aware Issue Tracking -Beads provides a lightweight, dependency-aware issue database and CLI (`br` / beads_rust) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging and file reservations. +Beads provides a lightweight, dependency-aware issue database and CLI (`br` / beads_rust) for selecting "ready work," setting priorities, and tracking status. It complements Liquid Mail's shared log for progress, decisions, and cross-session context. **Note:** `br` is non-invasive—it never executes git commands directly. You must run git commands manually after `br sync --flush-only`. ### Conventions -- **Single source of truth:** Beads for task status/priority/dependencies; Agent Mail for conversation and audit -- **Shared identifiers:** Use Beads issue ID (e.g., `br-123`) as Mail `thread_id` and prefix subjects with `[br-123]` -- **Reservations:** When starting a task, call `file_reservation_paths()` with the issue ID in `reason` +- **Single source of truth:** Beads for task status/priority/dependencies; Liquid Mail for conversation/decisions +- **Shared identifiers:** Include the Beads issue ID in posts (e.g., `[br-123] Topic validation rules`) +- **Decisions before action:** Post `DECISION:` messages before risky changes, not after ### Typical Agent Flow @@ -195,35 +148,34 @@ Beads provides a lightweight, dependency-aware issue database and CLI (`br` / be br ready --json # Choose highest priority, no blockers ``` -2. **Reserve edit surface (Mail):** - ``` - file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="br-123") +2. **Check context (Liquid Mail):** + ```bash + liquid-mail notify # See what changed since last session + liquid-mail query "br-123" # Find prior discussion on this issue ``` -3. **Announce start (Mail):** - ``` - send_message(..., thread_id="br-123", subject="[br-123] Start: <title>", ack_required=true) +3. **Work and log progress:** + ```bash + liquid-mail post --topic <workstream> "[br-123] START: <description>" + liquid-mail post "[br-123] FINDING: <what you discovered>" + liquid-mail post --decision "[br-123] DECISION: <what you decided and why>" ``` -4. **Work and update:** Reply in-thread with progress - -5. **Complete and release:** +4. **Complete (Beads is authority):** ```bash br close br-123 --reason "Completed" + liquid-mail post "[br-123] Completed: <summary with commit ref>" ``` - ``` - release_file_reservations(project_key, agent_name, paths=["src/**"]) - ``` - Final Mail reply: `[br-123] Completed` with summary ### Mapping Cheat Sheet -| Concept | Value | -|---------|-------| -| Mail `thread_id` | `br-###` | -| Mail subject | `[br-###] ...` | -| File reservation `reason` | `br-###` | -| Commit messages | Include `br-###` for traceability | +| Concept | In Beads | In Liquid Mail | +|---------|----------|----------------| +| Work item | `br-###` (issue ID) | Include `[br-###]` in posts | +| Workstream | — | `--topic auth-system` | +| Subject prefix | — | `[br-###] ...` | +| Commit message | Include `br-###` | — | +| Status | `br update --status` | Post progress messages | --- @@ -231,7 +183,7 @@ Beads provides a lightweight, dependency-aware issue database and CLI (`br` / be bv is a graph-aware triage engine for Beads projects (`.beads/beads.jsonl`). It computes PageRank, betweenness, critical path, cycles, HITS, eigenvector, and k-core metrics deterministically. -**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (messaging, work claiming, file reservations), use MCP Agent Mail. +**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (progress logging, decisions, cross-session context), use Liquid Mail. **CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.** @@ -835,3 +787,157 @@ Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fa - ❌ Full scan per edit → ✅ Scope to file - ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`) ```` + +<!-- BEGIN LIQUID MAIL (v:48d7b3fc) --> +## Integrating Liquid Mail with Beads + +**Beads** manages task status, priority, and dependencies (`br` CLI). +**Liquid Mail** provides the shared log—progress, decisions, and context that survives sessions. + +### Conventions + +- **Single source of truth**: Beads owns task state; Liquid Mail owns conversation/decisions +- **Shared identifiers**: Include the Beads issue ID in posts (e.g., `[lm-jht] Topic validation rules`) +- **Decisions before action**: Post `DECISION:` messages before risky changes, not after +- **Identity in user updates**: In every user-facing reply, include your window-name (derived from `LIQUID_MAIL_WINDOW_ID`) so humans can distinguish concurrent agents. + +### Typical Flow + +**1. Pick ready work (Beads)** +```bash +br ready # Find available work (no blockers) +br show lm-jht # Review details +br update lm-jht --status in_progress +``` + +**2. Check context (Liquid Mail)** +```bash +liquid-mail notify # See what changed since last session +liquid-mail query "lm-jht" # Find prior discussion on this issue +``` + +**3. Work and log progress (topic required)** + +The `--topic` flag is required for your first post. After that, the topic is pinned to your window. +```bash +liquid-mail post --topic auth-system "[lm-jht] START: Reviewing current topic id patterns" +liquid-mail post "[lm-jht] FINDING: IDs like lm3189... are being used as topic names" +liquid-mail post "[lm-jht] NEXT: Add validation + rename guidance" +``` + +**4. Decisions before risky changes** +```bash +liquid-mail post --decision "[lm-jht] DECISION: Reject UUID-like topic names; require slugs" +# Then implement +``` + +### Decision Conflicts (Preflight) + +When you post a decision (via `--decision` or a `DECISION:` line), Liquid Mail can preflight-check for conflicts with prior decisions **in the same topic**. + +- If a conflict is detected, `liquid-mail post` fails with `DECISION_CONFLICT`. +- Review prior decisions: `liquid-mail decisions --topic <topic>`. +- If you intend to supersede the old decision, re-run with `--yes` and include what changed and why. + +**5. Complete (Beads is authority)** +```bash +br close lm-jht # Mark complete in Beads +liquid-mail post "[lm-jht] Completed: Topic validation shipped in 177267d" +``` + +### Posting Format + +- **Short** (5-15 lines, not walls of text) +- **Prefixed** with ALL-CAPS tags: `FINDING:`, `DECISION:`, `QUESTION:`, `NEXT:` +- **Include file paths** so others can jump in: `src/services/auth.ts:42` +- **Include issue IDs** in brackets: `[lm-jht]` +- **User-facing replies**: include `AGENT: <window-name>` near the top. Get it with `liquid-mail window name`. + +### Topics (Required) + +Liquid Mail organizes messages into **topics** (Honcho sessions). Topics are **soft boundaries**—search spans all topics by default. + +**Rule:** `liquid-mail post` requires a topic: +- Provide `--topic <name>`, OR +- Post inside a window that already has a pinned topic. + +Topic names must be: +- 4–50 characters +- lowercase letters/numbers with hyphens +- start with a letter, end with a letter/number +- no consecutive hyphens +- not reserved (`all`, `new`, `help`, `merge`, `rename`, `list`) +- not UUID-like (`lm<32-hex>` or standard UUIDs) + +Good examples: `auth-system`, `db-system`, `dashboards` + +Commands: + +- **List topics (newest first)**: `liquid-mail topics` +- **Find context across topics**: `liquid-mail query "auth"`, then pick a topic name +- **Rename a topic (alias)**: `liquid-mail topic rename <old> <new>` +- **Merge two topics into a new one**: `liquid-mail topic merge <A> <B> --into <C>` + +Examples (component topic + Beads id in the subject): +```bash +liquid-mail post --topic auth-system "[lm-jht] START: Investigating token refresh failures" +liquid-mail post --topic auth-system "[lm-jht] FINDING: refresh happens in middleware, not service layer" +liquid-mail post --topic auth-system --decision "[lm-jht] DECISION: Move refresh logic into AuthService" + +liquid-mail post --topic dashboards "[lm-1p5] START: Adding latency panel" +``` + +### Context Refresh (Before New Work / After Redirects) + +If you see redirect/merge messages, refresh context before acting: +```bash +liquid-mail notify +liquid-mail window status --json +liquid-mail summarize --topic <topic> +liquid-mail decisions --topic <topic> +``` + +If you discover a newer "canonical" topic (for example after a topic merge), switch to it explicitly: +```bash +liquid-mail post --topic <new-topic> "[lm-xxxx] CONTEXT: Switching topics (rename/merge)" +``` + +### Live Updates (Polling) + +Liquid Mail is pull-based by default (you run `notify`). For near-real-time updates: +```bash +liquid-mail watch --topic <topic> # watch a topic +liquid-mail watch # or watch your pinned topic +``` + +### Mapping Cheat-Sheet + +| Concept | In Beads | In Liquid Mail | +|---------|----------|----------------| +| Work item | `lm-jht` (issue ID) | Include `[lm-jht]` in posts | +| Workstream | — | `--topic auth-system` | +| Subject prefix | — | `[lm-jht] ...` | +| Commit message | Include `lm-jht` | — | +| Status | `br update --status` | Post progress messages | + +### Pitfalls + +- **Don't manage tasks in Liquid Mail**—Beads is the single task queue +- **Always include `lm-xxx`** in posts to avoid ID drift across tools +- **Don't dump logs**—keep posts short and structured + +### Quick Reference + +| Need | Command | +|------|---------| +| What changed? | `liquid-mail notify` | +| Log progress | `liquid-mail post "[lm-xxx] ..."` | +| Before risky change | `liquid-mail post --decision "[lm-xxx] DECISION: ..."` | +| Find history | `liquid-mail query "search term"` | +| Prior decisions | `liquid-mail decisions --topic <topic>` | +| Show config | `liquid-mail config` | +| List topics | `liquid-mail topics` | +| Rename topic | `liquid-mail topic rename <old> <new>` | +| Merge topics | `liquid-mail topic merge <A> <B> --into <C>` | +| Polling watch | `liquid-mail watch [--topic <topic>]` | +<!-- END LIQUID MAIL -->