Skip to content

Commit 470b653

Browse files
steveyeggeclaude
andcommitted
docs: update all agent templates and concepts for root-only wisps
Update P0 role templates (polecat, deacon, witness, refinery) to remove bd mol current / bd close references and replace with inline formula checklist + gt patrol report pattern. Update P1 docs (molecules.md, propulsion-principle.md, reference.md, polecat-CLAUDE.md) to reflect the new architecture where formula steps are read from the embedded binary, not materialized as database rows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b8f79dc commit 470b653

8 files changed

Lines changed: 133 additions & 270 deletions

File tree

docs/concepts/molecules.md

Lines changed: 54 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -10,113 +10,42 @@ Formula (source TOML) ─── "Ice-9"
1010
▼ bd cook
1111
Protomolecule (frozen template) ─── Solid
1212
13-
├─▶ bd mol pour ──▶ Mol (persistent) ─── Liquid ──▶ bd squash ──▶ Digest
13+
├─▶ bd mol pour ──▶ Mol (persistent) ─── Liquid
1414
15-
└─▶ bd mol wisp ──▶ Wisp (ephemeral) ─── Vapor ──┬▶ bd squash ──▶ Digest
16-
└▶ bd burn ──▶ (gone)
15+
└─▶ bd mol wisp --root-only ──▶ Root Wisp (ephemeral) ─── Vapor
1716
```
1817

18+
**Root-only wisps**: Formula steps are NOT materialized as database rows. Only a
19+
single root wisp is created. Agents read steps inline from the embedded formula
20+
at prime time. This prevents wisp accumulation (~6,000+ rows/day → ~400/day).
21+
1922
## Core Concepts
2023

2124
| Term | Description |
2225
|------|-------------|
2326
| **Formula** | Source TOML template defining workflow steps |
2427
| **Protomolecule** | Frozen template ready for instantiation |
25-
| **Molecule** | Active workflow instance with trackable steps |
26-
| **Wisp** | Ephemeral molecule for patrol cycles (never synced) |
27-
| **Digest** | Squashed summary of completed molecule |
28-
| **Shiny Workflow** | Canonical polecat formula: design → implement → review → test → submit |
29-
30-
## Common Mistake: Reading Formulas Directly
31-
32-
**WRONG:**
33-
```bash
34-
# Reading a formula file and manually creating beads for each step
35-
cat .beads/formulas/mol-polecat-work.formula.toml
36-
bd create --title "Step 1: Load context" --type task
37-
bd create --title "Step 2: Branch setup" --type task
38-
# ... creating beads from formula prose
39-
```
40-
41-
**RIGHT:**
42-
```bash
43-
# Cook the formula into a proto, pour into a molecule
44-
bd cook mol-polecat-work
45-
bd mol pour mol-polecat-work --var issue=gt-xyz
46-
# Now work through the step beads that were created
47-
bd mol current # Find next step
48-
bd close <step-id> # Complete it
49-
```
50-
51-
**Key insight:** Formulas are source templates (like source code). You never read
52-
them directly during work. The `cook``pour` pipeline creates step beads for you.
53-
Your molecule already has steps - use `bd mol current` to find them.
54-
55-
## Navigating Molecules
56-
57-
Molecules help you track where you are in multi-step workflows.
58-
59-
### Finding Your Place
60-
61-
```bash
62-
bd mol current # Where am I?
63-
bd mol current gt-abc # Status of specific molecule
64-
```
65-
66-
Output:
67-
```
68-
You're working on molecule gt-abc (Feature X)
69-
70-
✓ gt-abc.1: Design
71-
✓ gt-abc.2: Scaffold
72-
✓ gt-abc.3: Implement
73-
→ gt-abc.4: Write tests [in_progress] <- YOU ARE HERE
74-
○ gt-abc.5: Documentation
75-
○ gt-abc.6: Exit decision
76-
77-
Progress: 3/6 steps complete
78-
```
79-
80-
### Seamless Transitions
81-
82-
Close a step and advance in one command:
83-
84-
```bash
85-
bd close gt-abc.3 --continue # Close and advance to next step
86-
bd close gt-abc.3 --no-auto # Close but don't auto-claim next
87-
```
88-
89-
**The old way (3 commands):**
90-
```bash
91-
bd close gt-abc.3
92-
bd mol current
93-
bd update gt-abc.4 --status=in_progress
94-
```
95-
96-
**The new way (1 command):**
97-
```bash
98-
bd close gt-abc.3 --continue
99-
```
100-
101-
### Transition Output
28+
| **Molecule** | Active workflow instance (root wisp only) |
29+
| **Wisp** | Ephemeral molecule for patrols and polecat work (never synced) |
30+
| **Root-only** | Only root wisp created; steps read from embedded formula |
10231

103-
```
104-
✓ Closed gt-abc.3: Implement feature
32+
## How Agents See Steps
10533

106-
Next ready in molecule:
107-
gt-abc.4: Write tests
34+
Agents do NOT use `bd mol current` or `bd close <step-id>` for formula workflows.
35+
Instead, formula steps are rendered inline when the agent runs `gt prime`:
10836

109-
→ Marked in_progress (use --no-auto to skip)
11037
```
38+
**Formula Checklist** (10 steps from mol-polecat-work):
11139
112-
### When Molecule Completes
40+
### Step 1: Load context and verify assignment
41+
Initialize your session and understand your assignment...
11342
43+
### Step 2: Set up working branch
44+
Ensure you're on a clean feature branch...
11445
```
115-
✓ Closed gt-abc.6: Exit decision
11646

117-
Molecule gt-abc complete! All steps closed.
118-
Consider: gt mol squash --summary '...'
119-
```
47+
The agent works through the checklist and runs `gt done` (polecats) or
48+
`gt patrol report` (patrol agents) when complete.
12049

12150
## Molecule Commands
12251

@@ -131,78 +60,66 @@ bd cook <formula> # Formula → Proto
13160
# Molecules (data operations)
13261
bd mol list # Available protos
13362
bd mol show <id> # Proto details
134-
bd mol pour <proto> # Create mol
135-
bd mol wisp <proto> # Create wisp
63+
bd mol wisp <proto> # Create wisp (root-only by default)
13664
bd mol bond <proto> <parent> # Attach to existing mol
137-
bd mol squash <id> # Condense to digest
138-
bd mol burn <id> # Discard wisp
139-
bd mol current # Where am I in the current molecule?
14065
```
14166

14267
### Agent Operations (gt)
14368

14469
```bash
14570
# Hook management
146-
gt hook # What's on MY hook
147-
gt mol current # What should I work on next
148-
gt mol progress <id> # Execution progress of molecule
71+
gt hook # What's on MY hook?
72+
gt prime # Shows inline formula checklist
14973
gt mol attach <bead> <mol> # Pin molecule to bead
15074
gt mol detach <bead> # Unpin molecule from bead
15175

152-
# Agent lifecycle
153-
gt mol burn # Burn attached molecule
154-
gt mol squash # Squash attached molecule
155-
gt mol step done <step> # Complete a molecule step
76+
# Patrol lifecycle
77+
gt patrol new # Create patrol wisp and hook it
78+
gt patrol report --summary "..." # Close current patrol, start next cycle
15679
```
15780

15881
## Polecat Workflow
15982

160-
Polecats receive work via their hook - a pinned molecule attached to an issue.
161-
They execute molecule steps sequentially, closing each step as they complete it.
83+
Polecats receive work via their hook — a root wisp attached to an issue.
84+
They see the formula checklist inline when they run `gt prime` and work
85+
through each step in order.
16286

163-
### Molecule Types for Polecats
87+
### Polecat Workflow Summary
88+
89+
```
90+
1. Spawn with work on hook
91+
2. gt prime # Shows formula checklist inline
92+
3. Work through each step
93+
4. Persist findings: bd update <issue> --notes "..."
94+
5. gt done # Submit, nuke sandbox, exit
95+
```
96+
97+
### Molecule Types
16498

16599
| Type | Storage | Use Case |
166100
|------|---------|----------|
167-
| **Regular Molecule** | `.beads/` (synced) | Discrete deliverables, audit trail |
168-
| **Wisp** | `.beads/` (ephemeral) | Patrol cycles, operational loops |
101+
| **Root-only Wisp** | `.beads/` (ephemeral) | Polecat work, patrols |
169102

170-
Polecats typically use **regular molecules** because each assignment has audit value.
171-
Patrol agents (Witness, Refinery, Deacon) use **wisps** to prevent accumulation.
103+
All formula-based work uses root-only wisps. Steps are read from the
104+
embedded binary, not materialized as database rows.
172105

173-
### Hook Management
106+
## Patrol Workflow
174107

175-
```bash
176-
gt hook # What's on MY hook?
177-
gt mol attach-from-mail <id> # Attach work from mail message
178-
gt done # Signal completion (syncs, submits to MQ, notifies Witness)
179-
```
180-
181-
### Polecat Workflow Summary
108+
Patrol agents (Deacon, Witness, Refinery) cycle through patrol formulas:
182109

183110
```
184-
1. Spawn with work on hook
185-
2. gt hook # What's hooked?
186-
3. bd mol current # Where am I?
187-
4. Execute current step
188-
5. bd close <step> --continue
189-
6. If more steps: GOTO 3
190-
7. gt done # Signal completion
111+
1. gt patrol new # Create root-only patrol wisp
112+
2. gt prime # Shows patrol checklist inline
113+
3. Work through each step
114+
4. gt patrol report --summary "..." # Close + start next cycle
191115
```
192116

193-
### Wisp vs Molecule Decision
194-
195-
| Question | Molecule | Wisp |
196-
|----------|----------|------|
197-
| Does it need audit trail? | Yes | No |
198-
| Will it repeat continuously? | No | Yes |
199-
| Is it discrete deliverable? | Yes | No |
200-
| Is it operational routine? | No | Yes |
117+
`gt patrol report` atomically closes the current patrol root and spawns
118+
a new one for the next cycle.
201119

202120
## Best Practices
203121

204-
1. **CRITICAL: Close steps in real-time** - Mark `in_progress` BEFORE starting, `closed` IMMEDIATELY after completing. Never batch-close steps at the end. Molecules ARE the ledger - each step closure is a timestamped CV entry. Batch-closing corrupts the timeline and violates HOP's core promise.
205-
2. **Use `--continue` for propulsion** - Keep momentum by auto-advancing
206-
3. **Check progress with `bd mol current`** - Know where you are before resuming
207-
4. **Squash completed molecules** - Create digests for audit trail
208-
5. **Burn routine wisps** - Don't accumulate ephemeral patrol data
122+
1. **Persist findings early**`bd update <issue> --notes "..."` before session death
123+
2. **Run `gt done` when complete** — mandatory for polecats (pushes, submits to MQ, nukes)
124+
3. **Use `gt patrol report`** — for patrol agents to cycle (replaces squash+new pattern)
125+
4. **File discovered work**`bd create` for bugs found, don't fix them yourself

docs/concepts/propulsion-principle.md

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -32,25 +32,22 @@ memorize steps or wait for instructions - discover them:
3232

3333
```bash
3434
gt hook # What's on my hook?
35-
bd mol current # Where am I in the molecule?
36-
bd mol current # What step is next?
37-
bd show <step-id> # What does this step require?
35+
gt prime # Shows inline formula checklist
36+
bd show <issue-id> # What's my assigned issue?
3837
```
3938

40-
### Before/After: Step Transitions
39+
### The New Workflow: Inline Formula Steps
40+
41+
Formula steps are shown inline at prime time — no step beads to manage:
4142

42-
**The old workflow (friction):**
4343
```bash
44-
# Finish step 3
45-
bd close gt-abc.3
46-
# Figure out what's next
47-
bd mol current
48-
# Manually claim it
49-
bd update gt-abc.4 --status=in_progress
50-
# Now finally work on it
44+
gt prime # See your checklist
45+
# Work through each step in order
46+
gt done # Submit and self-clean (polecats)
47+
gt patrol report # Close + next cycle (patrol agents)
5148
```
5249

53-
Three commands. Context switches. Momentum lost.
50+
No step closures, no `bd mol current`, no momentum-killing transitions.
5451

5552
**The new workflow (propulsion):**
5653
```bash

docs/reference.md

Lines changed: 17 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -251,42 +251,37 @@ bd mol show <id> # Proto details
251251
bd mol pour <proto> # Create mol
252252
bd mol wisp <proto> # Create wisp
253253
bd mol bond <proto> <parent> # Attach to existing mol
254-
bd mol squash <id> # Condense to digest (explicit ID)
255-
bd mol burn <id> # Discard wisp (explicit ID)
254+
bd mol bond <proto> <parent> # Attach to existing mol
256255
```
257256

258257
### Agent Operations (gt)
259258

260259
```bash
261260
# Hook management (operates on current agent's hook)
262261
gt hook # What's on MY hook
263-
gt mol current # What should I work on next
264-
gt mol progress <id> # Execution progress of molecule
262+
gt prime # Shows inline formula checklist
265263
gt mol attach <bead> <mol> # Pin molecule to bead
266264
gt mol detach <bead> # Unpin molecule from bead
267265
gt mol attach-from-mail <id> # Attach from mail message
268266

269-
# Agent lifecycle (operates on agent's attached molecule)
270-
gt mol burn # Burn attached molecule (no ID needed)
271-
gt mol squash # Squash attached molecule (no ID needed)
272-
gt mol step done <step> # Complete a molecule step
273-
```
267+
# Patrol lifecycle
268+
gt patrol new # Create root-only patrol wisp
269+
gt patrol report --summary "..." # Close current patrol, start next cycle
274270

275-
**Key distinction**: `bd mol burn/squash <id>` take explicit molecule IDs.
276-
`gt mol burn/squash` operate on the current agent's attached molecule
277-
(auto-detected from working directory).
271+
# Legacy (still functional)
272+
gt mol burn # Burn attached molecule
273+
gt mol squash # Squash attached molecule
274+
```
278275

279276
## Agent Lifecycle
280277

281278
### Polecat Shutdown
282279

283280
```
284-
1. Complete work steps
285-
2. gt mol squash (create digest)
286-
3. Submit to merge queue
287-
4. gt handoff (request shutdown)
288-
5. Wait for Witness to kill session
289-
6. Witness removes worktree + branch
281+
1. Work through formula checklist (shown inline by gt prime)
282+
2. Submit to merge queue via gt done
283+
3. gt done nukes sandbox and exits
284+
4. Witness removes worktree + branch
290285
```
291286

292287
### Session Cycling
@@ -687,10 +682,10 @@ Deacon, Witness, and Refinery run continuous patrol loops using wisps:
687682
| **Refinery** | `mol-refinery-patrol` | Process merge queue, review MRs, check integration branches |
688683

689684
```
690-
1. bd mol wisp mol-<role>-patrol
691-
2. Execute steps (check workers, process queue, run plugins)
692-
3. gt mol squash --jitter 10s (or burn if routine)
693-
4. Loop
685+
1. gt patrol new # Create root-only wisp
686+
2. gt prime # Shows patrol checklist inline
687+
3. Work through each step
688+
4. gt patrol report --summary "..." # Close + start next cycle
694689
```
695690

696691
## Plugin Molecules

0 commit comments

Comments
 (0)