From 8fb9f9a321e182ea1b501c1c6f8a2b3e19c4b83d Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sun, 21 Dec 2025 21:41:23 -0800 Subject: [PATCH] docs: clarify pinned molecule vs handoff mail distinction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two mechanisms, different purposes: - Pinned molecule (bd mol run) = What you are working on, tracked by beads - Handoff mail = Optional context notes for session restarts Updated templates, architecture.md, and builtin_molecules.go 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/architecture.md | 8 ++--- internal/beads/builtin_molecules.go | 8 ++--- internal/templates/roles/crew.md.tmpl | 28 ++++++++------- internal/templates/roles/deacon.md.tmpl | 43 ++++++++++++------------ internal/templates/roles/polecat.md.tmpl | 42 ++++++++++++++++------- 5 files changed, 75 insertions(+), 54 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 34eead97..ec58c0ca 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -754,8 +754,8 @@ Submit to merge queue. Create PR if needed. Verify CI passes. Needs: rebase-main -## Step: update-handoff -Update handoff bead with final state. +## Step: generate-summary +Generate summary for molecule squash. File any remaining work as issues. Needs: submit-merge @@ -817,8 +817,8 @@ Graceful shutdown with handoff preservation. Send shutdown notification to all agents. Record which agents acknowledged. -## Step: wait-handoffs -Wait for agents to update handoff beads. +## Step: wait-squash +Wait for agents to squash their molecules. Track completion status. Needs: notify-agents diff --git a/internal/beads/builtin_molecules.go b/internal/beads/builtin_molecules.go index f0f981fb..1e54dddf 100644 --- a/internal/beads/builtin_molecules.go +++ b/internal/beads/builtin_molecules.go @@ -375,11 +375,11 @@ gt done # Signal work ready for merge queue If there are CI failures, fix them before proceeding. Needs: rebase-main -## Step: update-handoff -Update handoff bead with final state. +## Step: generate-summary +Generate a summary for molecule squash. File any remaining work as issues. -Document any important context for the next session +Document any important context for the squash digest or for anyone reviewing the work. Needs: submit-merge @@ -389,7 +389,7 @@ Wait for termination. The polecat is now ready to be cleaned up. Do not exit directly - wait for Witness to kill the session. -Needs: update-handoff`, +Needs: generate-summary`, } } diff --git a/internal/templates/roles/crew.md.tmpl b/internal/templates/roles/crew.md.tmpl index 87888f01..1063ced5 100644 --- a/internal/templates/roles/crew.md.tmpl +++ b/internal/templates/roles/crew.md.tmpl @@ -105,24 +105,26 @@ If push fails (someone else pushed): `git pull --rebase && git push` ## Context Cycling (Handoff) -When your context fills up, cycle to a fresh session: +When your context fills up, cycle to a fresh session. + +**Two mechanisms, different purposes:** +- **Pinned molecule** = What you're working on (tracked by beads, survives restarts) +- **Handoff mail** = Context notes for yourself (optional, for nuances the molecule doesn't capture) + +Your work state is in beads. Handoff mail is just for extra context: ```bash -gt mail send {{ .RigName }}/crew/{{ .Polecat }} -s "🤝 HANDOFF: Work in progress" -m " -## Current State -Working on: -Status: - -## Next Steps -1. -2. - -## Notes - +# Optional: send yourself context notes +gt mail send {{ .RigName }}/crew/{{ .Polecat }} -s "🤝 HANDOFF: Context notes" -m " +Was debugging the auth flow, found the issue is in token refresh. +Check line 145 in auth.go first. " ``` -Then end your session. The next session will see this message in its inbox. +When you restart, find your work: +```bash +bd list --pinned --assignee={{ .RigName }}/crew/{{ .Polecat }} --status=in_progress +``` ## Session End Checklist diff --git a/internal/templates/roles/deacon.md.tmpl b/internal/templates/roles/deacon.md.tmpl index d2ed3f63..7d0d7068 100644 --- a/internal/templates/roles/deacon.md.tmpl +++ b/internal/templates/roles/deacon.md.tmpl @@ -47,18 +47,19 @@ You wake up when: When you wake, follow this protocol: -### 1. Check for Attached Molecule +### 1. Find Your Current Work ```bash -gt mol status # Shows current molecule attachment -bd list --status=in_progress --assignee=deacon +bd list --pinned --assignee=deacon --status=in_progress ``` -If you have an attached molecule, **resume from the current step**. -If no molecule attached, **bond a new patrol molecule**: +If you have a pinned molecule, **resume from the current step**. +If no molecule (naked), **start a new patrol**: ```bash -gt mol bond mol-deacon-patrol +bd mol run mol-deacon-patrol ``` +This spawns the patrol molecule, assigns it to you, pins it, and sets status to in_progress. + ### 2. Execute Current Step The `mol-deacon-patrol` steps are: @@ -104,15 +105,15 @@ bd ready # Check for next step ### 4. Loop or Exit At the end of each patrol cycle: -- **Low context**: `gt mol burn` → `gt mol bond mol-deacon-patrol` → repeat -- **High context**: `gt mol burn` → exit cleanly (daemon respawns you) +- **Low context**: `bd mol squash` → `bd mol run mol-deacon-patrol` → repeat +- **High context**: `bd mol squash` → exit cleanly (daemon respawns you) ```bash -# Burn the wisp (routine work, no audit needed) -gt mol burn +# Complete the patrol (squash generates summary, cleans up) +bd mol squash --summary="Patrol complete: checked inbox, scanned health, no issues" -# Option A: Loop -gt mol bond mol-deacon-patrol +# Option A: Loop (low context) +bd mol run mol-deacon-patrol # Continue to inbox-check... # Option B: Exit (high context) @@ -193,28 +194,28 @@ If you can't fix an issue after 3 attempts: ## Startup Protocol -1. Check for attached molecule: `bd list --status=in_progress --assignee=deacon` -2. If attached, **resume** from current step (you were mid-patrol) -3. If not attached, **bond** a new patrol: `gt mol bond mol-deacon-patrol` +1. Find your work: `bd list --pinned --assignee=deacon --status=in_progress` +2. If you have a pinned molecule, **resume** from current step (you were mid-patrol) +3. If naked (no pinned molecule), **start** a new patrol: `bd mol run mol-deacon-patrol` 4. Execute patrol steps until loop-or-exit -5. At loop-or-exit: burn molecule, then loop or exit based on context +5. At loop-or-exit: squash molecule, then loop or exit based on context ## Handoff (Molecule-Based) The Deacon uses **nondeterministic idempotence** for handoff: 1. Molecule state is in beads (survives session restarts) -2. On respawn, check `bd list --status=in_progress` to find current step -3. Resume from that step - no explicit handoff message needed +2. On respawn, query `bd list --pinned --assignee=deacon` to find current work +3. Resume from the next unclosed step - no explicit handoff message needed If you need to exit mid-patrol (high context): ```bash -gt mol burn # Clean up wisp state +bd mol squash --summary="Exiting mid-patrol due to context limit" # Just exit - daemon respawns with fresh context -# New session will bond a fresh patrol molecule +# New session will run a fresh patrol molecule ``` -The patrol molecule ensures continuity without handoff messages. +The pinned molecule ensures continuity. Handoff mail is only for optional context notes. --- diff --git a/internal/templates/roles/polecat.md.tmpl b/internal/templates/roles/polecat.md.tmpl index ad95a196..bb63951f 100644 --- a/internal/templates/roles/polecat.md.tmpl +++ b/internal/templates/roles/polecat.md.tmpl @@ -77,23 +77,41 @@ Agent-friendly UX is critical. Your guesses reveal what's intuitive. When your session starts, follow this protocol: -1. **Run `gt prime`** - This loads your context and checks for mail automatically -2. **Check your inbox** - If `gt prime` shows mail, read it with `gt mail read ` -3. **Look for work assignment** - Messages with "📋 Work Assignment" contain your task -4. **If no mail** - Check `bd list --status=in_progress` for existing assignments +1. **Run `gt prime`** - This loads your context and checks for mail +2. **Find your work molecule**: + ```bash + bd list --pinned --assignee={{ .RigName }}/{{ .Polecat }} --status=in_progress + ``` +3. **If you have a pinned molecule** - Resume from the next unclosed step +4. **If no molecule** - Check inbox for work assignment (`gt mail inbox`) 5. **Otherwise** - Wait for instructions from the Witness or Mayor -Work assignments are delivered to your inbox rather than injected into your session, -ensuring persistence across session restarts and providing an audit trail. +Your work is tracked as a **pinned molecule** (created by `bd mol run` when you were spawned). +This survives session restarts - just query for your pinned work to continue. ## Work Protocol -1. **Start**: Read your work assignment from mail, or `bd show ` -2. **Work**: Implement the solution in your clone -3. **Commit**: Regular commits with clear messages -4. **Test**: Verify your changes work -5. **Close**: `bd close ` when done -6. **Signal**: `gt done` to submit to merge queue +Your work follows the **mol-polecat-work** molecule steps: + +1. **load-context** - Run `gt prime`, read your assignment +2. **implement** - Write the solution, make commits +3. **self-review** - Check for bugs, style issues +4. **verify-tests** - Run tests, fix any failures +5. **rebase-main** - Rebase on origin/main +6. **submit-merge** - Run `gt done` to submit to merge queue +7. **generate-summary** - Write a summary of what you did +8. **request-shutdown** - Signal done, Witness cleans you up + +As you complete each step, close it: +```bash +bd close +bd ready --parent= # See next step +``` + +When finished, squash the molecule: +```bash +bd mol squash --summary="Implemented X, tests pass, ready for merge" +``` ## Before Signaling Done