gastown/docs/polecat-wisp-architecture.md

Polecat Wisp Architecture

How polecats use molecules and wisps to execute work in Gas Town.

Overview

Polecats receive work via their hook - a pinned molecule attached to an issue. They execute molecule steps sequentially, closing each step as they complete it.

Molecule Types for Polecats

Type	Storage	Use Case
Regular Molecule	.beads/ (synced)	Discrete deliverables, audit trail
Wisp	.beads/ (ephemeral, type=wisp)	Patrol cycles, operational loops

Polecats typically use regular molecules because each assignment has audit value. Patrol agents (Witness, Refinery, Deacon) use wisps to prevent accumulation.

Step Execution

The Traditional Approach

# 1. Check current status
gt hook

# 2. Find next step
bd ready --parent=gt-abc

# 3. Claim the step
bd update gt-abc.4 --status=in_progress

# 4. Do the work...

# 5. Close the step
bd close gt-abc.4

# 6. Repeat from step 2

The Propulsion Approach

# 1. Check where you are
bd mol current

# 2. Do the work on current step...

# 3. Close and advance in one command
bd close gt-abc.4 --continue

# 4. Repeat from step 1

The --continue flag:

• Closes the current step
• Finds the next ready step in the same molecule
• Auto-marks it in_progress
• Outputs the transition

Example Session

$ bd mol current
You're working on molecule gt-abc (Implement user auth)

  ✓ gt-abc.1: Design schema
  ✓ gt-abc.2: Create models
  → gt-abc.3: Add endpoints [in_progress] <- YOU ARE HERE
  ○ gt-abc.4: Write tests
  ○ gt-abc.5: Update docs

Progress: 2/5 steps complete

$ # ... implement the endpoints ...

$ bd close gt-abc.3 --continue
✓ Closed gt-abc.3: Add endpoints

Next ready in molecule:
  gt-abc.4: Write tests

→ Marked in_progress (use --no-auto to skip)

$ bd mol current
You're working on molecule gt-abc (Implement user auth)

  ✓ gt-abc.1: Design schema
  ✓ gt-abc.2: Create models
  ✓ gt-abc.3: Add endpoints
  → gt-abc.4: Write tests [in_progress] <- YOU ARE HERE
  ○ gt-abc.5: Update docs

Progress: 3/5 steps complete

Molecule Completion

When closing the last step:

$ bd close gt-abc.5 --continue
✓ Closed gt-abc.5: Update docs

Molecule gt-abc complete! All steps closed.
Consider: bd mol squash gt-abc --summary '...'

After all steps are closed:

# Squash to digest for audit trail
bd mol squash gt-abc --summary "Implemented user authentication with JWT"

# Or if it's routine work
bd mol burn gt-abc

Hook Management

Checking Your Hook

gt hook

Shows what molecule is pinned to your current agent and the associated bead.

Attaching Work from Mail

gt mail inbox
gt mol attach-from-mail <mail-id>

Completing Work

# After all molecule steps closed
gt done

# This:
# 1. Syncs beads
# 2. Submits to merge queue
# 3. Notifies Witness

Polecat Workflow Summary

1. Spawn with work on hook
2. gt hook           # What's hooked?
3. bd mol current          # Where am I?
4. Execute current step
5. bd close <step> --continue
6. If more steps: GOTO 3
7. gt done                 # Signal completion
8. Wait for Witness cleanup

Wisp vs Molecule Decision

Question	Molecule	Wisp
Does it need audit trail?	Yes	No
Will it repeat continuously?	No	Yes
Is it discrete deliverable?	Yes	No
Is it operational routine?	No	Yes

Polecats: Use molecules (deliverables have audit value) Patrol agents: Use wisps (routine loops don't accumulate)