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
+12 -6
View File
@@ -35,14 +35,20 @@ var deaconCmd = &cobra.Command{
Use: "deacon",
Aliases: []string{"dea"},
GroupID: GroupAgents,
Short: "Manage the Deacon session",
Short: "Manage the Deacon (town-level watchdog)",
RunE: requireSubcommand,
Long: `Manage the Deacon tmux session.
Long: `Manage the Deacon - the town-level watchdog for Gas Town.
The Deacon is the hierarchical health-check orchestrator for Gas Town.
It monitors the Mayor and Witnesses, handles lifecycle requests, and
keeps the town running. Use the subcommands to start, stop, attach,
and check status.`,
The Deacon ("daemon beacon") is the only agent that receives mechanical
heartbeats from the daemon. It monitors system health across all rigs:
- Watches all Witnesses (are they alive? stuck? responsive?)
- Manages Dogs for cross-rig infrastructure work
- Handles lifecycle requests (respawns, restarts)
- Receives heartbeat pokes and decides what needs attention
The Deacon patrols the town; Witnesses patrol their rigs; Polecats work.
Role shortcuts: "deacon" in mail/nudge addresses resolves to this agent.`,
}
var deaconStartCmd = &cobra.Command{