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
+16 -3
View File
@@ -32,12 +32,25 @@ var polecatCmd = &cobra.Command{
Use: "polecat",
Aliases: []string{"polecats"},
GroupID: GroupAgents,
Short: "Manage polecats in rigs",
Short: "Manage polecats (ephemeral workers, one task then nuked)",
RunE: requireSubcommand,
Long: `Manage polecat lifecycle in rigs.
Polecats are worker agents that operate in their own git worktrees.
Use the subcommands to add, remove, list, wake, and sleep polecats.`,
Polecats are EPHEMERAL workers: spawned for one task, nuked when done.
There is NO idle state. A polecat is either:
- Working: Actively doing assigned work
- Stalled: Session crashed mid-work (needs Witness intervention)
- Zombie: Finished but gt done failed (needs cleanup)
Self-cleaning model: When work completes, the polecat runs 'gt done',
which pushes the branch, submits to the merge queue, and exits. The
Witness then nukes the sandbox. Polecats don't wait for more work.
Session vs sandbox: The Claude session cycles frequently (handoffs,
compaction). The git worktree (sandbox) persists until nuke. Work
survives session restarts.
Cats build features. Dogs clean up messes.`,
}
var polecatListCmd = &cobra.Command{