docs: improve help text and add nudge documentation

Polish help text across all agent commands to clarify roles:
- crew: persistent workspaces vs ephemeral polecats
- deacon: town-level watchdog receiving heartbeats
- dog: cross-rig infrastructure workers (cats vs dogs)
- mayor: Chief of Staff for cross-rig coordination
- nudge: universal synchronous messaging API
- polecat: ephemeral one-task workers, self-cleaning
- refinery: merge queue serializer per rig
- witness: per-rig polecat health monitor

Add comprehensive gt nudge documentation to crew template explaining
when to use nudge vs mail, common patterns, and target shortcuts.

Add orphan-process-cleanup step to deacon patrol formula to clean up
claude subagent processes that fail to exit (TTY = "?").

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
dennis
2026-01-17 02:55:24 -08:00
committed by Steve Yegge
parent bd655f58f9
commit 7ff87ff012
11 changed files with 191 additions and 52 deletions

View File

@@ -308,9 +308,49 @@ ONE exception where branches are created. But the rule still applies:
- `bd sync` - Sync beads changes
### Communication
- `gt mail send <addr> -s "Subject" -m "Message"` - Send mail
- `gt mail send <addr> -s "Subject" -m "Message"` - Send mail (async, queued)
- `gt mail send mayor/ -s "Subject" -m "Message"` - To Mayor
- `gt mail send --human -s "Subject" -m "Message"` - To overseer
- `gt nudge <target> "message"` - Wake an agent and send immediate message
### gt nudge: Waking Agents
`gt nudge` is the **core mechanism for inter-agent communication**. It sends a message
directly to another agent's Claude Code session via tmux.
**When to use nudge vs mail:**
| Use Case | Tool | Why |
|----------|------|-----|
| Wake a sleeping agent | `gt nudge` | Immediate delivery to their session |
| Send task for later | `gt mail send` | Queued, they'll see it on next check |
| Both: assign + wake | `gt mail send` then `gt nudge` | Mail carries payload, nudge wakes them |
**Common patterns:**
```bash
# Wake another crew member (full path: rig/crew/name)
gt nudge {{ .RigName }}/crew/peer "Check your mail - PR review waiting"
# Wake a polecat (full path: rig/polecats/name)
gt nudge {{ .RigName }}/polecats/alpha "Work available on hook"
# Nudge with notification flag (also sends tmux bell)
gt mail send {{ .RigName }}/peer -s "Urgent" -m "..." --notify
# Nudge patrol agents
gt nudge witness "Check polecat health"
gt nudge deacon "Session started"
gt nudge mayor "Status update needed"
```
**Target shortcuts:**
- `mayor` → gt-mayor session
- `deacon` → gt-deacon session
- `witness` → gt-{{ .RigName }}-witness session
- `refinery` → gt-{{ .RigName }}-refinery session
- `channel:<name>` → All members of a named channel
**Important:** `gt nudge` is the ONLY reliable way to send text to Claude sessions.
Raw `tmux send-keys` is unreliable. Always use `gt nudge` for agent-to-agent communication.
## No Witness Monitoring