From 2e461cb10f53fc676afe193d1250365f9939c2d2 Mon Sep 17 00:00:00 2001 From: gastown/polecats/dex Date: Wed, 31 Dec 2025 12:05:53 -0800 Subject: [PATCH] Document hookable mail in all role templates and priming (gt-frhcq.4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add "Hookable Mail" section to all role templates explaining how mail beads can be hooked for ad-hoc instruction handoff. Key documentation points: - GUPP applies to hooked mail: read and execute instructions - Two use cases: hook existing mail, create+hook via gt handoff - Role-specific examples for each agent type Templates updated: - boot.md.tmpl - crew.md.tmpl - deacon.md.tmpl - mayor.md.tmpl - polecat.md.tmpl - refinery.md.tmpl - witness.md.tmpl Also updated prime.go fallback output functions to include hookable mail reference for when templates fail to render. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- internal/cmd/prime.go | 20 ++++++++++++++++++++ internal/templates/roles/boot.md.tmpl | 14 ++++++++++++++ internal/templates/roles/crew.md.tmpl | 14 ++++++++++++++ internal/templates/roles/deacon.md.tmpl | 17 +++++++++++++++++ internal/templates/roles/mayor.md.tmpl | 15 +++++++++++++++ internal/templates/roles/polecat.md.tmpl | 15 +++++++++++++++ internal/templates/roles/refinery.md.tmpl | 15 +++++++++++++++ internal/templates/roles/witness.md.tmpl | 15 +++++++++++++++ 8 files changed, 125 insertions(+) diff --git a/internal/cmd/prime.go b/internal/cmd/prime.go index 62fe95d4..4a9f0d80 100644 --- a/internal/cmd/prime.go +++ b/internal/cmd/prime.go @@ -312,6 +312,10 @@ func outputMayorContext(ctx RoleContext) { fmt.Println("- `gt rigs` - List all rigs") fmt.Println("- `bd ready` - Issues ready to work") fmt.Println() + fmt.Println("## Hookable Mail") + fmt.Println("Mail can be hooked for ad-hoc instructions: `gt hook attach `") + fmt.Println("If mail is on your hook, read and execute its instructions (GUPP applies).") + fmt.Println() fmt.Println("## Startup") fmt.Println("Check for handoff messages with 🤝 HANDOFF in subject - continue predecessor's work.") fmt.Println() @@ -330,6 +334,10 @@ func outputWitnessContext(ctx RoleContext) { fmt.Println("- `gt witness status` - Show witness status") fmt.Println("- `gt polecats` - List polecats in this rig") fmt.Println() + fmt.Println("## Hookable Mail") + fmt.Println("Mail can be hooked for ad-hoc instructions: `gt hook attach `") + fmt.Println("If mail is on your hook, read and execute its instructions (GUPP applies).") + fmt.Println() fmt.Printf("Rig: %s\n", style.Dim.Render(ctx.Rig)) } @@ -346,6 +354,10 @@ func outputRefineryContext(ctx RoleContext) { fmt.Println("- `gt merge queue` - Show pending merges") fmt.Println("- `gt merge next` - Process next merge") fmt.Println() + fmt.Println("## Hookable Mail") + fmt.Println("Mail can be hooked for ad-hoc instructions: `gt hook attach `") + fmt.Println("If mail is on your hook, read and execute its instructions (GUPP applies).") + fmt.Println() fmt.Printf("Rig: %s\n", style.Dim.Render(ctx.Rig)) } @@ -365,6 +377,10 @@ func outputPolecatContext(ctx RoleContext) { fmt.Println("- `bd close ` - Mark issue complete") fmt.Println("- `gt done` - Signal work ready for merge") fmt.Println() + fmt.Println("## Hookable Mail") + fmt.Println("Mail can be hooked for ad-hoc instructions: `gt hook attach `") + fmt.Println("If mail is on your hook, read and execute its instructions (GUPP applies).") + fmt.Println() fmt.Printf("Polecat: %s | Rig: %s\n", style.Dim.Render(ctx.Polecat), style.Dim.Render(ctx.Rig)) } @@ -384,6 +400,10 @@ func outputCrewContext(ctx RoleContext) { fmt.Println("- `bd show ` - View issue details") fmt.Println("- `bd close ` - Mark issue complete") fmt.Println() + fmt.Println("## Hookable Mail") + fmt.Println("Mail can be hooked for ad-hoc instructions: `gt hook attach `") + fmt.Println("If mail is on your hook, read and execute its instructions (GUPP applies).") + fmt.Println() fmt.Printf("Crew: %s | Rig: %s\n", style.Dim.Render(ctx.Polecat), style.Dim.Render(ctx.Rig)) } diff --git a/internal/templates/roles/boot.md.tmpl b/internal/templates/roles/boot.md.tmpl index d6a8e1be..e45bc4bf 100644 --- a/internal/templates/roles/boot.md.tmpl +++ b/internal/templates/roles/boot.md.tmpl @@ -114,6 +114,20 @@ When tmux is unavailable: - Report anomalies but can't fix interactively - Run to completion and exit (no handoff) +## Hookable Mail + +Mail beads can be hooked for ad-hoc instruction handoff: +- `gt hook attach ` - Hook existing mail as your assignment +- `gt handoff -m "..."` - Create and hook new instructions for next session + +If you find mail on your hook (not a patrol wisp), GUPP applies: read the mail +content, interpret the prose instructions, and execute them. This enables ad-hoc +tasks without creating formal beads. + +**Boot-specific note**: Since Boot is spawned fresh each daemon tick, hookable +mail is less common. However, the mechanism exists if debugging or special +instructions need to be passed to a Boot instance. + ## Commands ```bash diff --git a/internal/templates/roles/crew.md.tmpl b/internal/templates/roles/crew.md.tmpl index 009dd700..f7b4a159 100644 --- a/internal/templates/roles/crew.md.tmpl +++ b/internal/templates/roles/crew.md.tmpl @@ -206,6 +206,20 @@ gt mol attach-from-mail Your hooked work persists across sessions. The handoff mail is just context notes. +## Hookable Mail + +Mail beads can be hooked for ad-hoc instruction handoff: +- `gt hook attach ` - Hook existing mail as your assignment +- `gt handoff -m "..."` - Create and hook new instructions for next session + +If you find mail on your hook (not a molecule), GUPP applies: read the mail +content, interpret the prose instructions, and execute them. This enables ad-hoc +tasks without creating formal beads. + +**Crew use case**: The overseer can send you mail with instructions, then you (or +they) hook it. Your next session sees the mail on the hook and executes those +instructions immediately. Useful for one-off tasks that don't warrant a full bead. + ## Git Workflow: Work Off Main **Crew workers push directly to main. No feature branches.** diff --git a/internal/templates/roles/deacon.md.tmpl b/internal/templates/roles/deacon.md.tmpl index e03eb311..5d736c16 100644 --- a/internal/templates/roles/deacon.md.tmpl +++ b/internal/templates/roles/deacon.md.tmpl @@ -142,6 +142,23 @@ bd update --status=hooked --assignee=deacon **Work hooked → Run it. Hook empty → Check mail. Nothing anywhere → Create patrol.** +## Hookable Mail + +Mail beads can be hooked for ad-hoc instruction handoff: +- `gt hook attach ` - Hook existing mail as your assignment +- `gt handoff -m "..."` - Create and hook new instructions for next session + +If you find mail on your hook (not a patrol wisp), GUPP applies: read the mail +content, interpret the prose instructions, and execute them. This enables ad-hoc +tasks without creating formal beads. + +**Deacon use case**: The Mayor or human can send you mail with special instructions +(e.g., "focus on debugging witness spawning this cycle"), then hook it. Your next +session sees the mail on the hook and prioritizes those instructions before creating +a normal patrol wisp. + +--- + Then print the startup banner and execute: ``` diff --git a/internal/templates/roles/mayor.md.tmpl b/internal/templates/roles/mayor.md.tmpl index 5498ca01..b6f49476 100644 --- a/internal/templates/roles/mayor.md.tmpl +++ b/internal/templates/roles/mayor.md.tmpl @@ -224,6 +224,21 @@ gt mol attach-from-mail Your hooked work persists across sessions. Handoff mail (🤝 HANDOFF subject) provides context notes. +## Hookable Mail + +Mail beads can be hooked for ad-hoc instruction handoff: +- `gt hook attach ` - Hook existing mail as your assignment +- `gt handoff -m "..."` - Create and hook new instructions for next session + +If you find mail on your hook (not a molecule), GUPP applies: read the mail +content, interpret the prose instructions, and execute them. This enables ad-hoc +tasks without creating formal beads. + +**Mayor use case**: The human can send you mail with high-level instructions +(e.g., "prioritize security fixes across all rigs today"), then hook it. Your next +session sees the mail on the hook and executes those instructions. Also useful for +cross-session continuity when work doesn't fit neatly into a bead. + ## Session End Checklist ``` diff --git a/internal/templates/roles/polecat.md.tmpl b/internal/templates/roles/polecat.md.tmpl index cdc0875a..93dd8936 100644 --- a/internal/templates/roles/polecat.md.tmpl +++ b/internal/templates/roles/polecat.md.tmpl @@ -192,6 +192,21 @@ all your steps. Resume from the next unclosed step and execute. **No thinking. No "should I?" questions. Hook → Execute.** +## Hookable Mail + +Mail beads can be hooked for ad-hoc instruction handoff: +- `gt hook attach ` - Hook existing mail as your assignment +- `gt handoff -m "..."` - Create and hook new instructions for next session + +If you find mail on your hook (not a molecule), GUPP applies: read the mail +content, interpret the prose instructions, and execute them. This enables ad-hoc +tasks without creating formal beads. + +**Polecat use case**: The Witness or Mayor may hook mail with special instructions +when spawning you (e.g., "handle this urgent fix, details in the mail body"). Your +session sees the mail on the hook and executes those instructions. Less common than +molecule-based work, but useful for quick ad-hoc tasks. + ## Work Protocol Your work follows the **mol-polecat-work** molecule. As you complete each step: diff --git a/internal/templates/roles/refinery.md.tmpl b/internal/templates/roles/refinery.md.tmpl index 48f951ef..35ad6f88 100644 --- a/internal/templates/roles/refinery.md.tmpl +++ b/internal/templates/roles/refinery.md.tmpl @@ -159,6 +159,21 @@ bd mol spawn mol-refinery-patrol --wisp --assignee=refinery **No thinking. No "should I?" questions. Hook → Execute.** +## Hookable Mail + +Mail beads can be hooked for ad-hoc instruction handoff: +- `gt hook attach ` - Hook existing mail as your assignment +- `gt handoff -m "..."` - Create and hook new instructions for next session + +If you find mail on your hook (not a patrol wisp), GUPP applies: read the mail +content, interpret the prose instructions, and execute them. This enables ad-hoc +tasks without creating formal beads. + +**Refinery use case**: The Mayor or human can send you mail with special instructions +(e.g., "prioritize branch X due to blocking dependency"), then hook it. Your next +session sees the mail on the hook and prioritizes those instructions before creating +a normal patrol wisp. + ## Patrol Execution Protocol (Wisp-Based) Each patrol cycle uses a wisp (ephemeral molecule): diff --git a/internal/templates/roles/witness.md.tmpl b/internal/templates/roles/witness.md.tmpl index 71b92917..9d446e2e 100644 --- a/internal/templates/roles/witness.md.tmpl +++ b/internal/templates/roles/witness.md.tmpl @@ -176,6 +176,21 @@ bd update --status=hooked --assignee={{ .RigName }}/witness **Work hooked → Execute. No exceptions.** +## Hookable Mail + +Mail beads can be hooked for ad-hoc instruction handoff: +- `gt hook attach ` - Hook existing mail as your assignment +- `gt handoff -m "..."` - Create and hook new instructions for next session + +If you find mail on your hook (not a patrol wisp), GUPP applies: read the mail +content, interpret the prose instructions, and execute them. This enables ad-hoc +tasks without creating formal beads. + +**Witness use case**: The Mayor or Deacon can send you mail with special instructions +(e.g., "investigate polecat X which may be stuck"), then hook it. Your next session +sees the mail on the hook and prioritizes those instructions before creating a normal +patrol wisp. + --- ## 📋 FOLLOWING YOUR MOL