diff --git a/.liquid-mail.toml b/.liquid-mail.toml new file mode 100644 index 0000000..e0ea2b4 --- /dev/null +++ b/.liquid-mail.toml @@ -0,0 +1,13 @@ +# Liquid Mail config (TOML) +# +# Prefer env vars for secrets: +# LIQUID_MAIL_HONCHO_API_KEY +# LIQUID_MAIL_HONCHO_WORKSPACE_ID +# +[honcho] +api_key = "hch-v3-pmx23gk9k60xlqffpxpyjj8pywnxkpjkic9bdygx21iydvyxbeialioz5ehhcp1r" +# workspace_id is optional. +# If omitted, Liquid Mail defaults it to the repo name (git root folder name). +# Honcho uses get-or-create semantics for workspaces, so it will be created on first use. +# workspace_id = "my-repo" +base_url = "https://api.honcho.dev" 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 -->