| name | agent-mail |
| user-invocable | false |
| skill_api_version | 1 |
| hexagonal_role | supporting |
| consumes | ["coordination-request"] |
| produces | ["agent-identity","file-reservation","acknowledged-handoff"] |
| context_rel | [{"kind":"supplier-to","with":"agent-native"}] |
| metadata | {"capabilities":["agent_mail"],"effects":["write_agent_mail_records","install_precommit_guard","authorized_destructive_reset"],"canonical_status":"canonical","disposition":"keep_optional_adapter","tier":"execution","dependencies":[]} |
| description | Use Agent Mail as an optional messaging and file-reservation adapter for explicitly coordinated writers. Triggers: "coordinate writers", "reserve files". |
| practices | ["pragmatic-programmer"] |
| output_contract | factual messaging and reservation adapter results |
Agent Mail — optional coordination adapter
Agent Mail carries messages, acknowledgements, identities, and temporary file
reservations. It is not a task tracker, queue, proof ledger, or lifecycle
controller.
Reservations are advisory: they prevent collisions only because every
cooperating writer checks them against the same absolute project path, and one
writer registered against a different path resolution makes the whole ledger
advisory fiction. Agent Mail enforces nothing on a writer that does not check.
Named failure mode — silence-as-status: reading an unanswered thread as
"work stalled" or "work done"; mail silence proves only that no mail arrived.
Anti-pattern: widening or renewing a reservation unprompted when a conflict
appears. Corrective: report the conflict to the caller as-is; scope and TTL
changes are the caller's call.
Boundary
- Skip Agent Mail for a single writer.
- The caller supplies the absolute project path, agent identities, thread id,
participants, paths, exclusivity, reason, and TTL.
- Reservations prevent accidental overlap among cooperating writers. They do not
create work ownership or affect Plan, Candidate, or verdict semantics.
- Mail silence proves nothing about work status.
- A message or acknowledgement is evidence that communication occurred, not
evidence that a change is correct or complete. The adapter cannot select AgentOps semantics, issue a binding verdict, or turn factory completion into delivery or validation proof.
- Release a reservation, including any
force_release, only on the caller's
explicit request for that exact reservation. Force-release has no autonomous
trigger; a conflict is reported, not force-cleared.
- Agent Mail never selects work, changes tracker state, commits code, validates,
integrates, closes, releases, or delivers work.
Modes and authority
Two disjoint surfaces; do not reach the second from the first:
- Coordination mode (default). Register identity, reserve/release the
caller's paths, send/read/acknowledge the caller's threads. This is the whole
of routine use, and all of it writes durable Agent Mail records.
- Admin / disaster-recovery mode (explicitly caller-authorized only).
Installing the git pre-commit guard,
doctor repair, backup/restore, and the
irreversible clear-and-reset-everything are a separate mode. Each requires
the caller's explicit authorization for that specific operation; none is ever
performed as a side effect of coordination. clear-and-reset-everything
deletes the database and all storage and cannot be undone — never run it, even
with --force, without an explicit destructive-reset authorization from the
caller.
