mail

# mail - Agent Communication Skill

Inter-agent communication patterns for Gas Town.

## Overview

**What this skill does:** Enables structured communication between agents (Mayor, Witnesses, Refineries, Polecats, Crew).

| User Says | Claude Does |
|-----------|-------------|
| "check my mail" | `gt mail inbox` |
| "send mail to X" | `gt mail send <address> -s "..." -m "..."` |
| "broadcast to workers" | `gt broadcast "message"` |
| "nudge that polecat" | `gt nudge <target> "message"` |
| "escalate to human" | `gt mail send --human -s "..." -m "..."` |

---

## Quick Reference

```bash
# Check inbox
gt mail inbox                        # Your inbox (auto-detected)
gt mail inbox mayor/                 # Mayor's inbox
gt mail inbox gastown/Toast          # Polecat's inbox

# Send mail
gt mail send mayor/ -s "Subject" -m "Message"
gt mail send gastown/refinery -s "Task" -m "Details"
gt mail send --human -s "Escalation" -m "Need human help"

# Read specific message
gt mail read <message-id>

# Broadcast to all workers
gt broadcast "Check your mail"
gt broadcast --rig gastown "Rig-specific message"

# Nudge specific polecat/agent
gt nudge gastown/Toast "Continue with your task"
gt nudge witness "Check polecat health"
```

---

## Operations

### 1. Checking Inbox

```bash
# Your inbox (context auto-detected)
gt mail inbox

# Filter to unread only
gt mail inbox -u

# Specific agent's inbox
gt mail inbox mayor/
gt mail inbox gastown/witness
gt mail inbox gastown/Toast
```

**Output format:**
```
ID           FROM              SUBJECT                    DATE
msg-abc123   gastown/Toast     Work complete              2026-01-08 10:30
msg-def456   gastown/refinery  Merge ready                2026-01-08 10:15
```

### 2. Sending Mail

**Address formats:**
| Pattern | Example | Destination |
|---------|---------|-------------|
| `mayor/` | `gt mail send mayor/ ...` | Mayor inbox |
| `<rig>/witness` | `gt mail send gastown/witness ...` | Rig's Witness |
| `<rig>/refinery` | `gt