{"slug":"agent-mail-2","title":"agent-mail","summary":"Use Agent Mail as an optional messaging and file-reservation adapter for explicitly coordinated writers. Triggers: \"coordinate writers\", \"reserve files\".","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-08T21:44:45.146884Z","repo":{"url":"https://github.com/boshu2/agentops","stars":445,"forks":41,"license":"Apache-2.0","updatedAt":"2026-09-24T01:09:16Z"},"bodyHtml":"<hr>\n<p>name: agent-mail\nuser-invocable: false\nskill_api_version: 1\nhexagonal_role: supporting\nconsumes:</p>\n<ul>\n<li>coordination-request\nproduces:</li>\n<li>agent-identity</li>\n<li>file-reservation</li>\n<li>acknowledged-handoff\ncontext_rel:</li>\n<li>kind: supplier-to\nwith: agent-native\nmetadata:\ncapabilities: [agent_mail]\neffects: [write_agent_mail_records, install_precommit_guard, authorized_destructive_reset]\ncanonical_status: canonical\ndisposition: keep_optional_adapter\ntier: execution\ndependencies: []\ndescription: 'Use Agent Mail as an optional messaging and file-reservation adapter for explicitly coordinated writers. Triggers: \"coordinate writers\", \"reserve files\".'\npractices:</li>\n<li>pragmatic-programmer\noutput_contract: factual messaging and reservation adapter results</li>\n</ul>\n<hr>\n<h1>Agent Mail — optional coordination adapter</h1>\n<p>Agent Mail carries messages, acknowledgements, identities, and temporary file\nreservations. It is not a task tracker, queue, proof ledger, or lifecycle\ncontroller.</p>\n<p>Reservations are <strong>advisory</strong>: they prevent collisions only because every\ncooperating writer checks them against the same absolute project path, and one\nwriter registered against a different path resolution makes the whole ledger\nadvisory fiction. Agent Mail enforces nothing on a writer that does not check.</p>\n<p>Named failure mode — <strong>silence-as-status</strong>: reading an unanswered thread as\n\"work stalled\" or \"work done\"; mail silence proves only that no mail arrived.</p>\n<p>Anti-pattern: widening or renewing a reservation unprompted when a conflict\nappears. Corrective: report the conflict to the caller as-is; scope and TTL\nchanges are the caller's call.</p>\n<h2>Boundary</h2>\n<ul>\n<li>Skip Agent Mail for a single writer.</li>\n<li>The caller supplies the absolute project path, agent identities, thread id,\nparticipants, paths, exclusivity, reason, and TTL.</li>\n<li>Reservations prevent accidental overlap among cooperating writers. They do not\ncreate work ownership or affect Plan, Candidate, or verdict semantics.</li>\n<li>Mail silence proves nothing about work status.</li>\n<li>A message or acknowledgement is evidence that communication occurred, not\nevidence that a change is correct or complete. The adapter cannot select\nAgentOps semantics, issue a binding verdict, or turn factory completion into\ndelivery or validation proof.</li>\n<li>Release a reservation, including any <code>force_release</code>, only on the caller's\nexplicit request for that exact reservation. Force-release has no autonomous\ntrigger; a conflict is reported, not force-cleared.</li>\n<li>Agent Mail never selects work, changes tracker state, commits code, validates,\nintegrates, closes, releases, or delivers work.</li>\n</ul>\n<h2>Modes and authority</h2>\n<p>Two disjoint surfaces; do not reach the second from the first:</p>\n<ul>\n<li><strong>Coordination mode (default).</strong> Register identity, reserve/release the\ncaller's paths, send/read/acknowledge the caller's threads. This is the whole\nof routine use, and all of it writes durable Agent Mail records.</li>\n<li><strong>Admin / disaster-recovery mode (explicitly caller-authorized only).</strong>\nInstalling the git pre-commit guard, <code>doctor repair</code>, backup/restore, and the\nirreversible <code>clear-and-reset-everything</code> are a separate mode. Each requires\nthe caller's explicit authorization for that specific operation; none is ever\nperformed as a side effect of coordination. <code>clear-and-reset-everything</code>\ndeletes the database and all storage and cannot be undone — never run it, even\nwith <code>--force</code>, without an explicit destructive-reset authorization from the\ncaller.</li>\n</ul>\n<h2>Surfaces</h2>\n<p>Choose exactly one mailbox owner and access mode for each storage root. When an\nHTTP/MCP daemon owns the root, use its MCP tools; do not point the direct <code>am</code>\nCLI at the same database. Use the CLI fallback only with a root not owned by a\nrunning Agent Mail runtime. A busy mailbox activity lock or a bounded read\ntimeout is a degraded adapter result, not permission to restart the service,\nrepair the database, or silently switch roots.</p>\n<p>Use the MCP tools when they are present. Otherwise use the self-describing <code>am</code>\nCLI. Pin the intended storage root explicitly, and discover current syntax with\n<code>am mail --help</code>, <code>am file_reservations --help</code>, and related group help; do not\ninfer commands from remembered aliases. If a direct macOS read rejects a\nsymlinked snapshot directory such as <code>/var</code>, use a caller-scoped, non-symlinked\ntemporary directory for that isolated invocation or report the adapter\ndegraded; never weaken the traversal check.</p>\n<h2>One-shot use</h2>\n<ol>\n<li>Confirm that multiple explicitly coordinated writers share the repository.</li>\n<li>Freeze one storage root and either MCP/server mode or direct-CLI mode; never\nmix both against the same live database.</li>\n<li>Register the caller-supplied identity against the same absolute project path.</li>\n<li>Reserve only the supplied paths, with a bounded TTL.</li>\n<li>Report conflicts without waiting, narrowing scope, or changing the plan.</li>\n<li>Send the supplied message once and record its id.</li>\n<li>Read or acknowledge only the requested thread.</li>\n<li>Before the caller advances a declared transition, verify every\nacknowledgement-required message in that transition has the intended\nrecipient acknowledgement. Later traffic is not an implicit acknowledgement.</li>\n<li>Release only reservations the caller explicitly asks to release.</li>\n</ol>\n<h2>Output</h2>\n<p>Return the project, identity, thread/message ids, reservation ids and paths\n(with their TTLs), conflicts, and timestamps. The caller owns all subsequent\ndecisions.</p>\n<p>Terminal outcomes are explicit, never silent:</p>\n<ul>\n<li><strong>Adapter unavailable</strong> — neither the MCP tools nor the <code>am</code> CLI is present:\nreport that Agent Mail is unavailable and stop. Do not fall back to\nhand-written coordination or treat the absence as \"no conflicts\".</li>\n<li><strong>Reservation conflict</strong> — report the conflicting reservation as-is; do not\nnarrow, widen, renew, or force-release it.</li>\n<li><strong>Mailbox ownership conflict</strong> — a daemon and direct CLI contend for one\nstorage root: report the lock owner/mode and stop; do not restart, repair, or\nbypass the lock as a coordination side effect.</li>\n<li><strong>Required acknowledgement pending</strong> — report the exact message and intended\nrecipient and stop the dependent transition. Do not infer acknowledgement\nfrom a later reply or repair it after validation.</li>\n<li><strong>Timeout / degraded surface</strong> — report the operation as timed out or degraded\nwith what was and was not observed; a timeout is evidence, not \"done\".</li>\n<li><strong>Cleanup</strong> — reservations released this session are listed by id; any left\nin place (still holding a TTL) are named so the caller can see what remains.</li>\n</ul>\n<h2>References</h2>\n<ul>\n<li><a href=\"references/TOOLS.md\">CLI and MCP surface notes</a></li>\n<li><a href=\"references/WORKFLOWS.md\">Coordination patterns</a></li>\n<li><a href=\"references/RECOVERY.md\">Troubleshooting</a></li>\n</ul>\n","files":[{"path":"references/RECOVERY.md","sizeBytes":5298,"isText":true},{"path":"references/TOOLS.md","sizeBytes":6720,"isText":true},{"path":"references/WORKFLOWS.md","sizeBytes":3272,"isText":true},{"path":"SKILL.md","sizeBytes":6723,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-16T15:55:41.678951Z","sha256":"AB88EC758345AF78E125FDB978DF39F94B87A5D2798557DC811319A76597C76C","sizeBytes":9101},"review":null,"source":{"repositoryUrl":"https://github.com/boshu2/agentops","path":"skills/agent-mail","license":"Apache-2.0","commit":"c3fe161dce0b85d1e0490df757bbb841d22e4ea1","subtreeSha":"EE9512E784EF80E170183B090149E803A524EA9F4E00F03C71916A82781496EE","lastSyncedAt":"2026-09-24T06:48:55.360254Z"},"reviewedAt":"2026-09-16T15:57:10.634437Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/boshu2/agentops/tree/main/skills/agent-mail"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install boshu2-agentops@llmmart"},{"target":"git","command":"git clone https://github.com/boshu2/agentops.git"}]}