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

@@ -26,12 +26,23 @@ var refineryCmd = &cobra.Command{
Use: "refinery",
Aliases: []string{"ref"},
GroupID: GroupAgents,
Short: "Manage the merge queue processor",
Short: "Manage the Refinery (merge queue processor)",
RunE: requireSubcommand,
Long: `Manage the Refinery merge queue processor for a rig.
Long: `Manage the Refinery - the per-rig merge queue processor.
The Refinery processes merge requests from polecats, merging their work
into integration branches and ultimately to main.`,
The Refinery serializes all merges to main for a rig:
- Receives MRs submitted by polecats (via gt done)
- Rebases work branches onto latest main
- Runs validation (tests, builds, checks)
- Merges to main when clear
- If conflict: spawns FRESH polecat to re-implement (original is gone)
Work flows: Polecat completes → gt done → MR in queue → Refinery merges.
The polecat is already nuked by the time the Refinery processes.
One Refinery per rig. Persistent agent that processes work as it arrives.
Role shortcuts: "refinery" in mail/nudge addresses resolves to this rig's Refinery.`,
}
var refineryStartCmd = &cobra.Command{