johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: clarify pinned molecule vs handoff mail distinction

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-21 21:41:23 -08:00
parent 4cdc746fd5
commit 8fb9f9a321
5 changed files with 75 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/architecture.md
View File

@@ -754,8 +754,8 @@ Submit to merge queue. Create PR if needed.
Verify CI passes. Verify CI passes.
Needs: rebase-main Needs: rebase-main
## Step: update-handoff ## Step: generate-summary
Update handoff bead with final state. Generate summary for molecule squash.
File any remaining work as issues. File any remaining work as issues.
Needs: submit-merge Needs: submit-merge
@@ -817,8 +817,8 @@ Graceful shutdown with handoff preservation.
Send shutdown notification to all agents. Send shutdown notification to all agents.
Record which agents acknowledged. Record which agents acknowledged.
## Step: wait-handoffs ## Step: wait-squash
Wait for agents to update handoff beads. Wait for agents to squash their molecules.
Track completion status. Track completion status.
Needs: notify-agents Needs: notify-agents

8
internal/beads/builtin_molecules.go
View File

@@ -375,11 +375,11 @@ gt done # Signal work ready for merge queue
If there are CI failures, fix them before proceeding. If there are CI failures, fix them before proceeding.
Needs: rebase-main Needs: rebase-main
## Step: update-handoff ## Step: generate-summary
Update handoff bead with final state. Generate a summary for molecule squash.
File any remaining work as issues. 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. or for anyone reviewing the work.
Needs: submit-merge Needs: submit-merge
@@ -389,7 +389,7 @@ Wait for termination.
The polecat is now ready to be cleaned up. The polecat is now ready to be cleaned up.
Do not exit directly - wait for Witness to kill the session. Do not exit directly - wait for Witness to kill the session.
Needs: update-handoff`, Needs: generate-summary`,
} }
} }

28
internal/templates/roles/crew.md.tmpl
View File

@@ -105,24 +105,26 @@ If push fails (someone else pushed): `git pull --rebase && git push`
## Context Cycling (Handoff) ## 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 ```bash
gt mail send {{ .RigName }}/crew/{{ .Polecat }} -s "🤝 HANDOFF: Work in progress" -m " # Optional: send yourself context notes
## Current State gt mail send {{ .RigName }}/crew/{{ .Polecat }} -s "🤝 HANDOFF: Context notes" -m "
Working on: <issue-id or description> Was debugging the auth flow, found the issue is in token refresh.
Status: <what's done, what remains> Check line 145 in auth.go first.
## Next Steps
1. <first thing to do>
2. <second thing to do>
## Notes
<any important context>
" "
``` ```
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 ## Session End Checklist

43
internal/templates/roles/deacon.md.tmpl
View File

@@ -47,18 +47,19 @@ You wake up when:
When you wake, follow this protocol: When you wake, follow this protocol:
### 1. Check for Attached Molecule ### 1. Find Your Current Work
```bash ```bash
gt mol status # Shows current molecule attachment bd list --pinned --assignee=deacon --status=in_progress
bd list --status=in_progress --assignee=deacon
``` ```
If you have an attached molecule, **resume from the current step**. If you have a pinned molecule, **resume from the current step**.
If no molecule attached, **bond a new patrol molecule**: If no molecule (naked), **start a new patrol**:
```bash ```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 ### 2. Execute Current Step
The `mol-deacon-patrol` steps are: The `mol-deacon-patrol` steps are:
@@ -104,15 +105,15 @@ bd ready # Check for next step
### 4. Loop or Exit ### 4. Loop or Exit
At the end of each patrol cycle: At the end of each patrol cycle:
- **Low context**: `gt mol burn` → `gt mol bond mol-deacon-patrol` → repeat - **Low context**: `bd mol squash` → `bd mol run mol-deacon-patrol` → repeat
- **High context**: `gt mol burn` → exit cleanly (daemon respawns you) - **High context**: `bd mol squash` → exit cleanly (daemon respawns you)
```bash ```bash
# Burn the wisp (routine work, no audit needed) # Complete the patrol (squash generates summary, cleans up)
gt mol burn bd mol squash <mol-id> --summary="Patrol complete: checked inbox, scanned health, no issues"
# Option A: Loop # Option A: Loop (low context)
gt mol bond mol-deacon-patrol bd mol run mol-deacon-patrol
# Continue to inbox-check... # Continue to inbox-check...
# Option B: Exit (high context) # Option B: Exit (high context)
@@ -193,28 +194,28 @@ If you can't fix an issue after 3 attempts:
## Startup Protocol ## Startup Protocol
1. Check for attached molecule: `bd list --status=in_progress --assignee=deacon` 1. Find your work: `bd list --pinned --assignee=deacon --status=in_progress`
2. If attached, **resume** from current step (you were mid-patrol) 2. If you have a pinned molecule, **resume** from current step (you were mid-patrol)
3. If not attached, **bond** a new patrol: `gt mol bond mol-deacon-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 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) ## Handoff (Molecule-Based)
The Deacon uses **nondeterministic idempotence** for handoff: The Deacon uses **nondeterministic idempotence** for handoff:
1. Molecule state is in beads (survives session restarts) 1. Molecule state is in beads (survives session restarts)
2. On respawn, check `bd list --status=in_progress` to find current step 2. On respawn, query `bd list --pinned --assignee=deacon` to find current work
3. Resume from that step - no explicit handoff message needed 3. Resume from the next unclosed step - no explicit handoff message needed
If you need to exit mid-patrol (high context): If you need to exit mid-patrol (high context):
```bash ```bash
gt mol burn # Clean up wisp state bd mol squash <mol-id> --summary="Exiting mid-patrol due to context limit"
# Just exit - daemon respawns with fresh context # 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.
--- ---

42
internal/templates/roles/polecat.md.tmpl
View File

@@ -77,23 +77,41 @@ Agent-friendly UX is critical. Your guesses reveal what's intuitive.
When your session starts, follow this protocol: When your session starts, follow this protocol:
1. **Run `gt prime`** - This loads your context and checks for mail automatically 1. **Run `gt prime`** - This loads your context and checks for mail
2. **Check your inbox** - If `gt prime` shows mail, read it with `gt mail read <id>` 2. **Find your work molecule**:
3. **Look for work assignment** - Messages with "📋 Work Assignment" contain your task ```bash
4. **If no mail** - Check `bd list --status=in_progress` for existing assignments 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 5. **Otherwise** - Wait for instructions from the Witness or Mayor
Work assignments are delivered to your inbox rather than injected into your session, Your work is tracked as a **pinned molecule** (created by `bd mol run` when you were spawned).
ensuring persistence across session restarts and providing an audit trail. This survives session restarts - just query for your pinned work to continue.
## Work Protocol ## Work Protocol
1. **Start**: Read your work assignment from mail, or `bd show <assigned-issue>` Your work follows the **mol-polecat-work** molecule steps:
2. **Work**: Implement the solution in your clone
3. **Commit**: Regular commits with clear messages 1. **load-context** - Run `gt prime`, read your assignment
4. **Test**: Verify your changes work 2. **implement** - Write the solution, make commits
5. **Close**: `bd close <issue>` when done 3. **self-review** - Check for bugs, style issues
6. **Signal**: `gt done` to submit to merge queue 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 <step-id>
bd ready --parent=<mol-id> # See next step
```
When finished, squash the molecule:
```bash
bd mol squash <mol-id> --summary="Implemented X, tests pass, ready for merge"
```
## Before Signaling Done ## Before Signaling Done