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

docs: Plugins ARE molecules - remove YAML/markdown format

Browse Source 
- Updated molecules.md to reflect actual JSONL storage format
- Updated architecture.md molecule sections with ASCII diagrams
- Replaced markdown "## Step:" format with tree diagrams
- Changed plugin system from directory-based to molecule-based
- Plugins now use labels for metadata (tier, phase, role)
- Mol Mall distributes molecules.jsonl fragments

Related: gt-u818, gt-9za0

🤖 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-23 05:15:13 -08:00
parent 91992c7582
commit a473a35fe9
2 changed files with 350 additions and 877 deletions
Download Patch File Download Diff File Expand all files Collapse all files

431
docs/architecture.md
View File

@@ -438,66 +438,61 @@ The choice between **Mol** (durable) and **Wisp** (transient) depends on the wor
### Molecule Format
Molecules use a prose-based format with structured step definitions:
Molecules are stored as JSONL in `molecules.jsonl`:
```markdown
## Molecule: engineer-in-box
Full workflow from design to merge.
## Step: design
Think carefully about architecture. Consider:
- Existing patterns in the codebase
- Trade-offs between approaches
- Testability and maintainability
Write a brief design summary before proceeding.
## Step: implement
Write the code. Follow codebase conventions.
Needs: design
## Step: review
Self-review the changes. Look for bugs, style issues, missing error handling.
Needs: implement
## Step: test
Write and run tests. Cover happy path and edge cases.
Needs: implement
## Step: submit
Submit for merge via refinery.
Needs: review, test
```json
{
"id": "mol-engineer-in-box",
"title": "Engineer in Box: {{feature}}",
"description": "Full workflow from design to merge.",
"labels": ["template"],
"issue_type": "epic"
}
```
**Key format elements:**
- `## Step: <name>` - Step header with reference name
- Prose instructions - What the step should accomplish
- `Needs: <step1>, <step2>` - Dependencies (optional)
- `Tier: haiku|sonnet|opus` - Model hint (optional)
Steps are hierarchical children with dependencies encoded as beads edges:
```
mol-engineer-in-box
├── .1 design "Think about architecture"
├── .2 implement "Write the code" ← depends on .1
├── .3 review "Self-review changes" ← depends on .2
├── .4 test "Write and run tests" ← depends on .2
└── .5 submit "Submit for merge" ← depends on .3, .4
```
**Key points:**
- Storage is JSONL (standard beads issue format)
- `{{var}}` placeholders resolved at bond time
- Steps are child issues, not embedded markdown
- Dependencies are beads edges, not text directives
### Molecule Composition
Molecules can include other molecules to create derived workflows:
Molecules compose via bonding - attaching one molecule to another:
```markdown
## Molecule: gastown-polecat
Full workflow for Gas Town polecats including binary installation.
```
mol-gastown-polecat (composed)
├── [mol-engineer-in-box steps bonded here]
│ ├── .1 design
│ ├── .2 implement
│ ├── .3 review
│ ├── .4 test
│ └── .5 submit
└── .6 install-binary ← depends on .5 (submit)
```
Includes: mol-engineer-in-box
## Step: install-binary
After merge is submitted, rebuild and install the local gt binary.
Run from the rig directory:
go build -o gt ./cmd/gt
go install ./cmd/gt
Needs: submit
**Composition via bond:**
```bash
bd mol bond mol-engineer-in-box $PARENT_MOL
bd create "Install binary" --parent=$PARENT_MOL --deps=.5
```
**Semantics:**
- `Includes:` brings in all steps from the referenced molecule
- New steps can depend on included steps (e.g., `Needs: submit`)
- Multiple includes are supported for complex polymers
- Dependencies are resolved transitively at parse time
- Bonding attaches one molecule's steps as children
- New steps can depend on bonded steps
- Multiple bonds create complex polymers
- Dependencies are standard beads edges
### Nondeterministic Idempotence
@@ -823,127 +818,48 @@ Molecules aren't just for implementing features. Any multi-step process that req
#### mol-polecat-work
The full polecat lifecycle, not just "do the issue":
The full polecat lifecycle:
```markdown
## Molecule: polecat-work
Full polecat lifecycle from assignment to decommission.
## Step: load-context
Run gt prime and bd prime. Verify issue assignment.
Check inbox for any relevant messages.
## Step: implement
Implement the solution. Follow codebase conventions.
File discovered work as new issues.
Needs: load-context
## Step: self-review
Review your own changes. Look for bugs, style issues,
missing error handling, security concerns.
Needs: implement
## Step: verify-tests
Run existing tests. Add new tests for new functionality.
Ensure adequate coverage.
Needs: implement
## Step: rebase-main
Rebase against main to incorporate any changes.
Resolve conflicts if needed.
Needs: self-review, verify-tests
## Step: submit-merge
Submit to merge queue. Create PR if needed.
Verify CI passes.
Needs: rebase-main
## Step: generate-summary
Generate summary for molecule squash.
File any remaining work as issues.
Needs: submit-merge
## Step: request-shutdown
Send shutdown request to Witness.
Wait for termination.
Needs: update-handoff
```
mol-polecat-work
├── .1 load-context "gt prime, bd prime, check inbox"
├── .2 implement "Write code, file discovered work" ← .1
├── .3 self-review "Check for bugs, security issues" ← .2
├── .4 verify-tests "Run tests, add coverage" ← .2
├── .5 rebase-main "Rebase, resolve conflicts" ← .3, .4
├── .6 submit-merge "Submit to queue, verify CI" ← .5
├── .7 generate-summary "Squash summary, file remaining work" ← .6
└── .8 request-shutdown "Signal Witness, wait for kill" ← .7
```
**Why this matters**: A polecat that crashes after step 4 doesn't lose work. On restart, it reads molecule state, sees "verify-tests: completed, rebase-main: pending", and continues rebasing.
**Why this matters**: A polecat that crashes after step 4 doesn't lose work. On restart, it reads molecule state, sees ".4: completed, .5: pending", and continues rebasing.
#### mol-rig-activate
Activating a rig for work:
```markdown
## Molecule: rig-activate
Activate a rig and spawn workers.
## Step: verify-rig
Check rig exists and is properly configured.
Verify git remote is accessible.
## Step: start-witness
Start Witness if not running.
Verify Witness is healthy.
Needs: verify-rig
## Step: start-refinery
Start Refinery if not running.
Verify Refinery is healthy.
Needs: verify-rig
## Step: sync-beads
Sync beads from remote.
Resolve any conflicts.
Needs: start-witness
## Step: identify-ready
Query bd ready for available work.
Prioritize by issue priority.
Needs: sync-beads
## Step: spawn-workers
Spawn polecats for ready issues.
Respect max_workers limit.
Needs: identify-ready, start-refinery
```
mol-rig-activate
├── .1 verify-rig "Check config, git remote"
├── .2 start-witness "Start if needed, verify health" ← .1
├── .3 start-refinery "Start if needed, verify health" ← .1
├── .4 sync-beads "Sync from remote" ← .2
├── .5 identify-ready "Query bd ready, prioritize" ← .4
└── .6 spawn-workers "Spawn polecats for work" ← .5, .3
```
#### mol-graceful-shutdown
Shutting down Gas Town properly:
```markdown
## Molecule: graceful-shutdown
Graceful shutdown with handoff preservation.
## Step: notify-agents
Send shutdown notification to all agents.
Record which agents acknowledged.
## Step: wait-squash
Wait for agents to squash their molecules.
Track completion status.
Needs: notify-agents
## Step: verify-clean
Verify all git states are clean.
Check for uncommitted work.
Needs: wait-handoffs
## Step: kill-workers
Terminate polecat sessions.
Remove worktrees.
Needs: verify-clean
## Step: kill-core
Terminate Witness, Refinery, Mayor, Deacon.
In correct order.
Needs: kill-workers
## Step: final-sync
Final beads sync to preserve state.
Needs: kill-core
```
mol-graceful-shutdown
├── .1 notify-agents "Send shutdown to all agents"
├── .2 wait-squash "Wait for molecule completion" ← .1
├── .3 verify-clean "Check git states clean" ← .2
├── .4 kill-workers "Terminate polecats, worktrees" ← .3
├── .5 kill-core "Terminate Witness, Refinery" ← .4
└── .6 final-sync "Final beads sync" ← .5
```
**Key principle**: If a multi-step process requires cognition and can fail partway through, it should be a molecule. This applies to:
@@ -954,113 +870,77 @@ Needs: kill-core
### Pluggable Molecules
Some workflows benefit from **pluggable steps** - dimensions that can be added or removed by creating/deleting directories. The canonical example is **code review**, where each review dimension (security, performance, test coverage) is a plugin.
Some workflows benefit from **pluggable steps** - dimensions that can be added or removed dynamically. The canonical example is **code review**, where each review dimension (security, performance, test coverage) is a plugin molecule.
#### Philosophy: Plugins Are Directories
#### Philosophy: Plugins ARE Molecules
In Gas Town, a plugin is just a directory that agents notice. If the directory exists, the plugin exists. No registration, no manifests, no YAML configs.
In Gas Town, plugins are molecules with specific labels. No separate format, no YAML configs, no directory conventions. Just beads.
```
~/gt/molecules/code-review/
├── discovery/
│ ├── file-census/
│ │ └── CLAUDE.md # Instructions for this step
│ ├── dep-graph/
│ │ └── CLAUDE.md
│ └── duplication-scan/
│ └── CLAUDE.md
├── structural/
│ ├── architecture-review/
│ │ └── CLAUDE.md
│ └── missing-abstractions/
│ └── CLAUDE.md
└── tactical/
├── security-scan/
│ └── CLAUDE.md
├── performance-review/
│ └── CLAUDE.md
└── test-gaps/
└── CLAUDE.md
```json
{
"id": "mol-security-scan",
"title": "Security scan: {{scope}}",
"description": "Check for OWASP Top 10 vulnerabilities in {{scope}}",
"labels": ["template", "plugin", "code-review", "phase:tactical", "tier:sonnet"],
"issue_type": "task"
}
```
**Add a dimension**: Create a directory with CLAUDE.md
**Remove a dimension**: Delete the directory
**Customize a dimension**: Edit its CLAUDE.md
**Add a dimension**: Install a plugin molecule (`bd mol install mol-security-scan`)
**Remove a dimension**: Uninstall or don't bond it
**Customize a dimension**: Fork and modify the molecule
#### Plugin Metadata
#### Plugin Labels
Each plugin can include frontmatter in its CLAUDE.md:
Labels encode metadata that would otherwise go in config files:
```markdown
---
phase: tactical
needs: [structural-complete]
tier: sonnet
---
| Label | Purpose |
|-------|---------|
| `plugin` | Marks as bondable at hook points |
| `code-review` | Which molecule can use this plugin |
| `phase:tactical` | Grouping for ordering |
| `tier:sonnet` | Model hint |
| `witness` / `deacon` | Which patrol can use it |
# Security Scan
#### Dynamic Assembly
Look for OWASP Top 10 vulnerabilities...
```
| Field | Description |
|-------|-------------|
| `phase` | Grouping for ordering (discovery, structural, tactical, synthesis) |
| `needs` | Dependencies - other steps that must complete first |
| `tier` | Model hint (haiku, sonnet, opus) |
#### Dynamic Molecule Assembly
When instantiating a pluggable molecule, the system:
1. **Scans** plugin directories under the molecule root
2. **Parses** metadata from each plugin's CLAUDE.md
3. **Assembles** the DAG based on phase groupings and dependencies
4. **Creates** beads for each discovered step
At runtime, the parent molecule bonds plugins based on labels:
```bash
gt molecule instantiate code-review --parent=gt-xyz --scope=src/auth
# In mol-code-review, during plugin-run step:
for plugin in $(bd mol list --label plugin,code-review --json | jq -r '.[].id'); do
bd mol bond $plugin $CURRENT_MOL --var scope="$SCOPE"
done
```
Creates beads like:
Creates a structure like:
```
gt-xyz.discovery-file-census
gt-xyz.discovery-dep-graph
gt-xyz.structural-architecture-review # blocks tactical
gt-xyz.tactical-src-auth-security
gt-xyz.tactical-src-auth-performance
gt-xyz.synthesis
gt-xyz (mol-code-review instance)
├── discovery plugins (parallel)
│ ├── .file-census
│ ├── .dep-graph
│ └── .coverage-map
├── structural plugins (sequential) ← depends on discovery
│ ├── .architecture-review
│ └── .abstraction-analysis
├── tactical plugins (parallel) ← depends on structural
│ ├── .security-scan
│ └── .performance-review
└── .synthesis ← depends on tactical
```
The **directory structure IS the molecule**. No separate molecule definition needed.
#### Phases and Ordering
Pluggable molecules support phased execution:
| Phase | Purpose | Parallelism |
|-------|---------|-------------|
| `discovery` | Inventory, analyze codebase | Fully parallel |
| `structural` | Big picture issues (architecture, abstractions) | Sequential for coherence |
| `tactical` | Per-component detailed review | Parallel per component |
| `synthesis` | Aggregate, dedupe, prioritize | Single coordinator |
Steps in earlier phases block steps in later phases. Within a phase, parallelism depends on explicit `needs` declarations.
#### Code Review Molecule
The **code-review** molecule is the reference implementation:
The **mol-code-review** molecule is the reference implementation:
**Discovery Phase** (parallel scouts):
- `file-census` - Inventory: sizes, ages, churn rates
- `dep-graph` - Dependencies, cycles, inversions
- `coverage-map` - Test coverage, dead code
- `duplication-scan` - Near-duplicate files, copy-paste debt
- `mol-file-census` - Inventory: sizes, ages, churn rates
- `mol-dep-graph` - Dependencies, cycles, inversions
- `mol-coverage-map` - Test coverage, dead code
**Structural Phase** (sequential):
- `architecture-review` - Does structure match domain?
- `abstraction-analysis` - Wrangling at wrong layers?
- `consolidation-planner` - What should be unified?
- `mol-architecture-review` - Does structure match domain?
- `mol-abstraction-analysis` - Wrangling at wrong layers?
**Tactical Phase** (parallel per hotspot):
- `security-scan` - OWASP Top 10, injection, auth bypass
@@ -1104,13 +984,13 @@ Each instantiation is independent. The ledger shows all runs, enabling compariso
| Aspect | Static Molecule | Pluggable Molecule |
|--------|-----------------|-------------------|
| Definition | Steps in issue description | Steps from directory scan |
| Add step | Edit molecule bead | Create directory |
| Remove step | Edit molecule bead | Delete directory |
| Customization | Edit description | Edit plugin CLAUDE.md |
| Definition | Steps defined at template time | Steps bonded at runtime |
| Add step | Edit molecule template | Install plugin molecule |
| Remove step | Edit molecule template | Don't bond it |
| Customization | Edit description | Fork plugin molecule |
| Use case | Fixed workflows | Extensible workflows |
Both patterns are valid. Use static molecules for well-defined workflows (engineer-in-box, polecat-work). Use pluggable molecules when dimensions should be customizable (code-review, migration-analysis).
Both patterns are valid. Use static molecules for well-defined workflows (mol-engineer-in-box, mol-polecat-work). Use pluggable molecules when dimensions should be customizable (mol-code-review, mol-witness-patrol).
## Directory Structure
@@ -1287,10 +1167,7 @@ For reference without mermaid rendering (see [hq.md](hq.md) for creation/setup):
│ │ │ └── <project files> # (inherits beads from rig)
│ │ └── Toast/ # Git worktree from Mayor's clone
│ │
│ └── plugins/ # Optional plugins
│ └── merge-oracle/
│ ├── CLAUDE.md
│ └── state.json
│ └── molecules.jsonl # Optional local molecule catalog
│
└── wyvern/ # Another rig (same structure)
├── config.json
@@ -1650,9 +1527,9 @@ sequenceDiagram
- Zero new infrastructure needed (uses existing mail, beads, identities)
- Composable - plugins can invoke other plugins via mail
- Debuggable - just look at mail logs and bead history
- Extensible - anyone can add a plugin by creating a directory
- Extensible - anyone can add a plugin molecule to their catalog
**Structure**: `<rig>/plugins/<name>/` with optional `rig/`, `CLAUDE.md`, `mail/`, `state.json`.
**Structure**: Plugin molecules in `molecules.jsonl` with labels for discovery.
### 8. Rig-Level Beads via BEADS_DIR
@@ -2088,47 +1965,41 @@ Gas Town is intentionally rough and lightweight. A "credible plugin system" with
### Plugin Structure
Plugins live in a rig's `plugins/` directory:
Plugins are molecules with specific labels, stored in `molecules.jsonl`:
```json
{
"id": "mol-merge-oracle",
"title": "Analyze merge queue",
"description": "Analyze pending changesets for conflicts and ordering.",
"labels": ["template", "plugin", "refinery", "tier:sonnet"],
"issue_type": "task"
}
```
wyvern/ # Rig
├── plugins/
│ └── merge-oracle/ # A plugin
│ ├── rig/ # Plugin's git clone (if needed)
│ ├── CLAUDE.md # Plugin's instructions/prompts
│ ├── mail/inbox.jsonl # Plugin's mailbox
│ └── state.json # Plugin state (optional)
```
That's it. No plugin.yaml, no special registration. If the directory exists, the plugin exists.
### Invoking Plugins
Plugins are invoked like any other agent - via mail:
Plugins are bonded during patrol execution:
```bash
# Refinery asks merge-oracle to analyze pending changesets
gt send wyvern/plugins/merge-oracle -s "Analyze merge queue" -m "..."
# Mayor asks plan-oracle for a work breakdown
gt send beads/plugins/plan-oracle -s "Plan for bd-xyz" -m "..."
# In mol-refinery-patrol plugin-run step:
bd mol bond mol-merge-oracle $PATROL_WISP \
--var queue_state="$QUEUE_JSON"
```
Plugins do their work (potentially spawning Claude sessions) and respond via mail, creating any necessary artifacts (beads, files, branches).
Plugins execute as molecule steps, creating any necessary artifacts (beads, files, branches).
### Hook Points
Existing agents can be configured to notify plugins at specific points. This is just convention - agents check if a plugin exists and mail it:
Patrol molecules bond plugins at specific points. Discovery uses labels:
| Workflow Point | Agent | Example Plugin |
|----------------|-------|----------------|
| Before merge processing | Refinery | merge-oracle |
| Before work dispatch | Mayor | plan-oracle |
| On worker stuck | Witness | debug-oracle |
| On PR ready | Refinery | review-oracle |
| Periodic / on-demand | Mayor | beads-hygiene |
| Workflow Point | Patrol | Label Filter |
|----------------|--------|--------------|
| Refinery patrol | mol-refinery-patrol | `plugin,refinery` |
| Witness patrol | mol-witness-patrol | `plugin,witness` |
| Deacon patrol | mol-deacon-patrol | `plugin,deacon` |
Configuration is minimal - perhaps a line in the agent's CLAUDE.md or state.json noting which plugins to consult.
Configuration is via labels - agents bond plugins that match their role.
### Example: Merge Oracle
@@ -2149,7 +2020,7 @@ The **merge-oracle** plugin analyzes changesets before the Refinery processes th
- Mail to Refinery with recommendation (proceed / escalate to Mayor)
- If escalation needed: mail to Mayor with explanation
The merge-oracle's `CLAUDE.md` contains the prompts and classification criteria. Gas Town doesn't need to know the internals.
The mol-merge-oracle's description contains the prompts and classification criteria. Gas Town doesn't need to know the internals.
### Example: Plan Oracle
@@ -2210,7 +2081,7 @@ Workers sometimes get confused about which database they're in, especially when:
- Mayor can invoke periodically (nightly hygiene scan)
- Any agent can invoke on-demand when confused
**CLAUDE.md prompt core**:
**mol-beads-hygiene description (prompt core)**:
```
You are reviewing beads databases for cross-pollution between Gas Town's
two-level architecture:

892
docs/molecules.md
View File

@@ -1,691 +1,293 @@
# Molecules: Composable Workflow Templates
This document covers the molecule system in depth, including pluggable molecules
and the code-review molecule design.
This document covers the molecule system in depth.
For an overview, see [architecture.md](architecture.md#molecules-composable-workflow-templates).
## Core Concepts
A **molecule** is a crystallized workflow pattern stored as a beads issue. When
instantiated on a parent issue, it creates child beads forming a DAG of steps.
| Concept | Description |
|---------|-------------|
| Molecule | Read-only workflow template (type=molecule in beads) |
| Step | Individual unit of work within a molecule |
| Bond | Dependency between steps (Needs: directive) |
| Instance | Concrete beads created when molecule is instantiated |
## Two Molecule Types
### Static Molecules
Steps are embedded in the molecule's description field:
```markdown
## Step: design
Think carefully about architecture...
## Step: implement
Write the code...
Needs: design
## Step: test
Run tests...
Needs: implement
```
**Use case**: Well-defined, fixed workflows (engineer-in-box, polecat-work).
**Commands**:
```bash
bd create --type=molecule --title="My Workflow" --description="..."
gt molecule instantiate mol-xyz --parent=issue-123
```
### Pluggable Molecules
Steps are discovered from directories. Each directory is a plugin:
A **molecule** is a workflow template stored as a beads issue with `labels: ["template"]`.
When bonded, it creates child issues forming a DAG of steps.
```
~/gt/molecules/code-review/
├── discovery/
│ ├── file-census/CLAUDE.md
│ └── dep-graph/CLAUDE.md
├── structural/
│ └── architecture-review/CLAUDE.md
└── tactical/
├── security-scan/CLAUDE.md
└── performance-review/CLAUDE.md
```
**Use case**: Extensible workflows where dimensions can be added/removed.
**Commands**:
```bash
gt molecule instantiate code-review --parent=issue-123 --scope=src/
```
## Molecule CLI Reference
The `bd mol` commands manage the molecule lifecycle: bonding (instantiation), squashing
(completion with digest), and burning (abandonment).
### bd mol bond
Instantiate a proto molecule into a runnable molecule (Mol or Wisp).
```bash
bd mol bond <proto-id> [--wisp] [--assignee=<addr>]
```
**Arguments:**
| Argument | Required | Description |
|----------|----------|-------------|
| `<proto-id>` | Yes | ID of the proto molecule to instantiate |
| `--wisp` | No | Create a Wisp (ephemeral) instead of Mol (durable) |
| `--assignee` | No | Address of the agent who will execute this molecule |
**Behavior:**
- **Default (Mol)**: Creates a durable molecule tracked in the main `.beads/` database.
Steps become permanent issues that survive indefinitely.
- **With --wisp**: Creates a wisp (transient molecule) in `.beads-wisp/`. Steps are
transient and will be cleaned up on squash or burn.
**Examples:**
```bash
# Create a durable Mol from engineer-in-box proto
bd mol bond mol-engineer-in-box
# Create a Wisp assigned to a polecat
bd mol bond mol-quick-fix --wisp --assignee=gastown/polecats/toast
# Bond a proto with a specific template variant
bd mol bond mol-engineer-in-box --template=minimal
```
**Output:**
Returns the ID of the newly created molecule instance (e.g., `gt-xyz.exec-001`).
---
### bd mol squash
Complete a molecule and generate a digest (permanent summary record).
```bash
bd mol squash <mol-id> --summary='...'
```
**Arguments:**
| Argument | Required | Description |
|----------|----------|-------------|
| `<mol-id>` | Yes | ID of the molecule instance to squash |
| `--summary` | Yes | Summary of what was accomplished (agent-generated) |
**Behavior:**
- **For Mol (durable)**: Creates a digest issue in the permanent beads database.
The digest contains the summary and links back to the original proto.
- **For Wisp (transient)**: Evaporates the wisp (deletes from `.beads-wisp/`)
and creates a digest in the permanent database. The execution trace is gone,
but the outcome is preserved.
**The summary is critical**: Agents generate the summary describing what was
accomplished. This becomes the permanent record. Beads is a tool - the intelligence
for summarization comes from the agent.
**Examples:**
```bash
# Squash a completed molecule with summary
bd mol squash gt-xyz.exec-001 --summary='Implemented user auth with JWT tokens. Added login/logout endpoints and middleware for protected routes.'
# Squash with multi-line summary (use quotes)
bd mol squash gt-xyz.exec-001 --summary='Fixed authentication bug.
Changes:
- Corrected token expiry calculation
- Added refresh token rotation
- Updated tests'
```
**Output:**
Returns the ID of the created digest (e.g., `gt-xyz.digest-001`).
---
### bd mol burn
Abandon a molecule without completing it. No digest is created.
```bash
bd mol burn <mol-id> [--reason='...']
```
**Arguments:**
| Argument | Required | Description |
|----------|----------|-------------|
| `<mol-id>` | Yes | ID of the molecule instance to burn |
| `--reason` | No | Explanation of why the molecule was abandoned |
**Behavior:**
- Discards all molecule state (steps, progress, artifacts)
- No digest is created - the molecule leaves no permanent record
- For Wisps: Simply deletes from `.beads-wisp/`
- For Mols: Marks as abandoned/closed without digest
**When to burn vs squash:**
| Situation | Use |
|-----------|-----|
| Work completed successfully | `squash` - preserve the outcome |
| Routine work, no audit needed | `burn` - no record necessary |
| Work abandoned/cancelled | `burn` - nothing to record |
| Experiment that failed | `burn` - don't clutter history |
| Investigation with findings | `squash` - findings are valuable |
**Examples:**
```bash
# Burn a molecule that's no longer needed
bd mol burn gt-xyz.exec-001
# Burn with explanation
bd mol burn gt-xyz.exec-001 --reason='Superseded by different approach in gt-abc'
# Burn a failed experiment
bd mol burn gt-xyz.exec-001 --reason='Approach proved unworkable - see notes in PR #123'
```
---
### Lifecycle Summary
```
Proto Molecule (template in catalog)
Proto (template)
│
▼ bd mol bond
┌────────────────────┐
│ Mol (durable) or │
│ Wisp (ephemeral) │
└────────┬───────────┘
┌─────────────────┐
│ Mol (durable) │ ← .beads/ (synced, auditable)
│ or │
│ Wisp (ephemeral)│ ← .beads-wisp/ (gitignored)
└────────┬────────┘
│
┌────────┴────────┐
┌─────┴─────┐
▼ ▼
bd mol burn bd mol squash
(no record) (creates digest)
```
**Key insight**: The molecule lifecycle maps to Gas Town's steam engine metaphor:
- **Proto** = Fuel (frozen template)
- **Mol/Wisp** = Steam (active execution)
- **Digest** = Distillate (condensed permanent record)
- **Burn** = Steam dissipates (no condensation)
- **Squash** = Steam condenses (captured as digest)
| Concept | Description |
|---------|-------------|
| Proto | Template molecule (is_template: true in beads) |
| Mol | Durable instance in .beads/ |
| Wisp | Ephemeral instance in .beads-wisp/ |
| Digest | Condensed completion record |
| Bond | Instantiate proto → mol/wisp |
## Plugin CLAUDE.md Format
## Molecule Storage
Each plugin directory contains a CLAUDE.md with optional frontmatter:
Molecules are standard beads issues stored in `molecules.jsonl`:
```markdown
---
phase: tactical
needs: [structural-complete]
tier: sonnet
---
# Security Scan
## Objective
Identify security vulnerabilities in the target code.
## Focus Areas
- OWASP Top 10 vulnerabilities
- Injection attacks (SQL, command, LDAP)
- Authentication/authorization bypasses
- Hardcoded secrets
- Insecure deserialization
## Output
For each finding, create a bead with:
- Clear title describing the vulnerability
- File path and line numbers
- Severity (P0-P4)
- Suggested remediation
Tag findings with `label: security`.
```json
{
"id": "mol-engineer-in-box",
"title": "Engineer in Box: {{feature_name}}",
"description": "Full workflow from design to merge.\n\nVars:\n- {{feature_name}} - What to build",
"labels": ["template"],
"issue_type": "epic"
}
```
### Frontmatter Fields
**Loaded from multiple sources** (later overrides earlier):
1. Built-in (embedded in bd binary)
2. Town-level: `~/gt/.beads/molecules.jsonl`
3. User-level: `~/.beads/molecules.jsonl`
4. Project-level: `.beads/molecules.jsonl`
| Field | Type | Description |
|-------|------|-------------|
| `phase` | string | Execution phase: discovery, structural, tactical, synthesis |
| `needs` | list | Step references that must complete first |
| `tier` | string | Model hint: haiku, sonnet, opus |
## Variable Substitution
### Phase Semantics
Molecules support `{{var}}` placeholders resolved at bond time:
| Phase | Blocks | Parallelism | Purpose |
|-------|--------|-------------|---------|
| discovery | nothing | full | Inventory, gather data |
| structural | discovery | sequential | Big picture analysis |
| tactical | structural | per-component | Detailed review |
| synthesis | tactical | single | Aggregate results |
```bash
bd mol bond mol-engineer-in-box --var feature_name="user auth"
# Creates: "Engineer in Box: user auth"
```
Variables work in:
- Title
- Description
- Child step titles/descriptions
## Steps as Children
Steps are hierarchical children of the molecule:
```
mol-engineer-in-box (epic)
├── mol-engineer-in-box.1 "Design"
├── mol-engineer-in-box.2 "Implement" Needs: .1
├── mol-engineer-in-box.3 "Review" Needs: .2
├── mol-engineer-in-box.4 "Test" Needs: .3
└── mol-engineer-in-box.5 "Submit" Needs: .4
```
Dependencies are encoded in beads edges, not in step descriptions.
## Molecule CLI Reference
### bd mol bond
Instantiate a proto molecule into a runnable mol or wisp.
```bash
bd mol bond <proto-id> [--wisp] [--var key=value...]
```
| Flag | Description |
|------|-------------|
| `--wisp` | Create ephemeral wisp instead of durable mol |
| `--var` | Variable substitution (repeatable) |
| `--ref` | Custom reference ID for the instance |
**Examples:**
```bash
# Durable mol
bd mol bond mol-engineer-in-box --var feature_name="auth"
# Ephemeral wisp for patrol
bd mol bond mol-witness-patrol --wisp
# Dynamic child with custom ref (Christmas Ornament pattern)
bd mol bond mol-polecat-arm $PATROL_ID --ref arm-ace --var polecat=ace
```
### bd mol squash
Complete a molecule and generate a permanent digest.
```bash
bd mol squash <mol-id> --summary='...'
```
The summary is agent-generated - the intelligence comes from the agent, not beads.
**For Mol**: Creates digest in .beads/, original steps remain.
**For Wisp**: Evaporates wisp, creates digest. Execution trace gone, outcome preserved.
### bd mol burn
Abandon a molecule without record.
```bash
bd mol burn <mol-id> [--reason='...']
```
Use burn for:
- Routine patrol cycles (no audit needed)
- Failed experiments
- Cancelled work
Use squash for:
- Completed work
- Investigations with findings
- Anything worth recording
### bd mol list
List available molecules:
```bash
bd mol list # All templates
bd mol list --label plugin # Plugin molecules only
```
## Plugins ARE Molecules
Patrol plugins are molecules with specific labels:
```json
{
"id": "mol-security-scan",
"title": "Security scan for {{polecat_name}}",
"description": "Check for vulnerabilities.\n\nVars: {{polecat_name}}, {{captured_output}}",
"labels": ["template", "plugin", "witness", "tier:haiku"],
"issue_type": "task"
}
```
Label conventions:
- `plugin` - marks as bondable at hook points
- `witness` / `deacon` / `refinery` - which patrol uses it
- `tier:haiku` / `tier:sonnet` - model hint
**Execution in patrol:**
```bash
# plugin-run step bonds registered plugins:
bd mol bond mol-security-scan $PATROL_WISP \
--ref security-{{polecat_name}} \
--var polecat_name=ace \
--var captured_output="$OUTPUT"
```
## The Christmas Ornament Pattern
Dynamic bonding creates tree structures at runtime:
```
★ mol-witness-patrol
/|\
┌─────┘ │ └─────┐
PREFLIGHT │ CLEANUP
│ │ │
┌───┴───┐ │ ┌───┴───┐
│inbox │ │ │aggreg │
│load │ │ │summary│
└───────┘ │ └───────┘
│
┌─────────┼─────────┐
│ │ │
● ● ● mol-polecat-arm (dynamic)
ace nux toast
│ │ │
┌──┴──┐ ┌──┴──┐ ┌──┴──┐
│steps│ │steps│ │steps│
└──┬──┘ └──┬──┘ └──┬──┘
│ │ │
└─────────┴─────────┘
│
⬣ base
```
**Key primitives:**
- `bd mol bond ... --ref` - creates named children
- `WaitsFor: all-children` - fanout gate
- Arms execute in parallel
## Mol Mall
Distribution through molecule marketplace:
```bash
# Install from registry
bd mol install mol-security-scan
# Updates ~/.beads/molecules.jsonl
```
Mol Mall serves `molecules.jsonl` fragments. Installation appends to your catalog.
## Code Review Molecule
The code-review molecule is the reference implementation for pluggable molecules.
### Directory Structure
The code-review molecule is a pluggable workflow:
```
~/gt/molecules/code-review/
├── README.md # Molecule overview
mol-code-review
├── discovery (parallel)
│ ├── file-census
│ ├── dep-graph
│ └── coverage-map
│
├── discovery/ # Phase 1: Parallel scouts
│ ├── file-census/
│ │ └── CLAUDE.md # Inventory: sizes, ages, churn
│ ├── dep-graph/
│ │ └── CLAUDE.md # Dependencies, cycles, inversions
│ ├── coverage-map/
│ │ └── CLAUDE.md # Test coverage, dead code
│ └── duplication-scan/
│ └── CLAUDE.md # Near-duplicates, copy-paste
├── structural (sequential)
│ ├── architecture-review
│ └── abstraction-analysis
│
├── structural/ # Phase 2: Sequential for coherence
│ ├── architecture-review/
│ │ └── CLAUDE.md # Structure vs domain alignment
│ ├── abstraction-analysis/
│ │ └── CLAUDE.md # Wrong-layer wrangling
│ └── consolidation-planner/
│ └── CLAUDE.md # What should be unified
├── tactical (parallel per component)
│ ├── security-scan
│ ├── performance-review
│ └── complexity-analysis
│
├── tactical/ # Phase 3: Parallel per hotspot
│ ├── security-scan/
│ │ └── CLAUDE.md # OWASP, injection, auth
│ ├── performance-review/
│ │ └── CLAUDE.md # N+1, caching, memory
│ ├── complexity-analysis/
│ │ └── CLAUDE.md # Cyclomatic, nesting
│ ├── test-gaps/
│ │ └── CLAUDE.md # Untested paths, edge cases
│ └── elegance-review/
│ └── CLAUDE.md # Magic numbers, naming
│
└── synthesis/ # Phase 4: Single coordinator
└── aggregate/
└── CLAUDE.md # Dedupe, prioritize, sequence
└── synthesis (single)
└── aggregate
```
### Discovery Phase Plugins
Each dimension is a molecule that can be:
- Swapped for alternatives from Mol Mall
- Customized by forking and installing your version
- Disabled by not bonding it
#### file-census
**Purpose**: Build inventory of what we're reviewing.
**Output**:
- Total files, lines, and size
- Files by age (old = potential legacy)
- Files by churn (high churn = hotspots)
- Largest files (candidates for splitting)
#### dep-graph
**Purpose**: Map dependencies and structure.
**Output**:
- Dependency graph (imports, requires)
- Circular dependencies
- Orphaned code (unreachable)
- Inverted dependencies (high-level depending on low-level)
#### coverage-map
**Purpose**: Understand test coverage.
**Output**:
- Overall coverage percentage
- Untested files/functions
- Coverage by component
- Dead code (never executed)
#### duplication-scan
**Purpose**: Find duplicated logic.
**Output**:
- Near-duplicate files
- Copy-paste code blocks
- Redundant implementations of same concept
### Structural Phase Plugins
#### architecture-review
**Purpose**: Assess high-level structure.
**Questions**:
- Does directory structure match domain concepts?
- Are boundaries clean between components?
- Is there a clear layering strategy?
- Are cross-cutting concerns (logging, auth) handled consistently?
**Output**: Structural findings as beads, with refactoring recommendations.
#### abstraction-analysis
**Purpose**: Find missing or wrong abstractions.
**Signs of problems**:
- Same boilerplate repeated
- Business logic mixed with infrastructure
- Leaky abstractions (implementation details exposed)
- Primitive obsession (should be domain types)
**Output**: Abstraction issues as beads.
#### consolidation-planner
**Purpose**: Identify what should be unified.
**Looks for**:
- Multiple implementations of same concept
- Similar code in different places
- Parallel hierarchies
- Scattered handling of same concern
**Output**: Consolidation recommendations as beads.
### Tactical Phase Plugins
These run in parallel, each agent reviewing assigned files/components.
#### security-scan
**Focus**:
- OWASP Top 10
- Injection vulnerabilities
- Authentication/authorization issues
- Secrets in code
- Insecure configurations
#### performance-review
**Focus**:
- N+1 queries
- Missing caching opportunities
- Memory leaks
- Unnecessary computation
- Blocking operations in hot paths
#### complexity-analysis
**Focus**:
- Cyclomatic complexity > 10
- Deep nesting (> 4 levels)
- Long functions (> 50 lines)
- God classes/files
- Complex conditionals
#### test-gaps
**Focus**:
- Untested public APIs
- Missing edge cases
- No error path testing
- Brittle tests (mock-heavy, order-dependent)
#### elegance-review
**Focus**:
- Magic numbers/strings
- Unclear naming
- Inconsistent style
- Missing documentation for complex logic
- Overly clever code
### Synthesis Phase
#### aggregate
**Purpose**: Combine all findings into actionable backlog.
**Tasks**:
1. Deduplicate similar findings
2. Group related issues
3. Establish fix dependencies (fix X before Y)
4. Prioritize by impact
5. Sequence for efficient fixing
**Output**: Prioritized backlog ready for swarming.
## Implementation Plan
### Phase 1: Pluggable Molecule Infrastructure
1. **Directory scanner** (`internal/molecule/scanner.go`)
- Scan molecule directories for plugins
- Parse CLAUDE.md frontmatter
- Build plugin registry
2. **DAG builder** (`internal/molecule/dag.go`)
- Assemble dependency graph from plugins
- Respect phase ordering
- Validate no cycles
3. **Instantiation** (`internal/molecule/instantiate.go`)
- Create beads for each step
- Wire dependencies
- Support scope parameter
### Phase 2: Code Review Molecule
1. **Plugin directory structure**
- Create ~/gt/molecules/code-review/
- Write CLAUDE.md for each dimension
2. **Discovery plugins** (4)
- file-census, dep-graph, coverage-map, duplication-scan
3. **Structural plugins** (3)
- architecture-review, abstraction-analysis, consolidation-planner
4. **Tactical plugins** (5)
- security-scan, performance-review, complexity-analysis, test-gaps, elegance-review
5. **Synthesis plugin** (1)
- aggregate
### Phase 3: CLI Integration
1. **gt molecule scan** - Show discovered plugins
2. **gt molecule validate** - Validate plugin structure
3. **gt molecule instantiate** - Create beads from plugins
4. **gt review** - Convenience wrapper for code-review molecule
## Usage Examples
### Basic Code Review
**Usage:**
```bash
# Run full code review on project
gt molecule instantiate code-review --parent=gt-review-001
# Check what's ready to work
bd ready
# Swarm it
gt swarm --parent=gt-review-001
bd mol bond mol-code-review --var scope="src/"
```
### Scoped Review
```bash
# Review only src/auth/
gt molecule instantiate code-review --parent=gt-review-002 --scope=src/auth
# Review only tactical dimensions
gt molecule instantiate code-review --parent=gt-review-003 --phases=tactical
```
### Adding a Custom Dimension
```bash
# Create plugin directory
mkdir -p ~/gt/molecules/code-review/tactical/accessibility-review
# Add CLAUDE.md
cat > ~/gt/molecules/code-review/tactical/accessibility-review/CLAUDE.md << 'EOF'
---
phase: tactical
needs: [structural-complete]
tier: sonnet
---
# Accessibility Review
Check for WCAG 2.1 compliance issues...
EOF
# Now it's automatically included in code-review
gt molecule scan code-review
```
### Iteration
```bash
# First review pass
gt molecule instantiate code-review --parent=gt-review-001
# ... fix issues ...
# Second pass (fewer findings expected)
gt molecule instantiate code-review --parent=gt-review-002
# ... fix remaining issues ...
# Third pass (should be at noise floor)
gt molecule instantiate code-review --parent=gt-review-003
```
## Beads Generated by Reviews
Each review step generates findings as beads:
## Lifecycle Summary
```
gt-sec-001 SQL injection in login() type=bug priority=1 label=security
gt-sec-002 Missing CSRF protection type=bug priority=2 label=security
gt-perf-001 N+1 query in user list type=bug priority=2 label=performance
gt-arch-001 Auth logic in controller type=task priority=3 label=refactor
```
Findings link back to the review:
```
discovered-from: gt-review-001.tactical-security-scan
```
This enables querying: "What did the security scan find?"
## Feed the Beast Pattern
Code review is a **work generator**:
```
Low on beads?
┌─────────────┐
│ Proto │ Template in molecules.jsonl
│ (frozen) │ labels: ["template"]
└──────┬──────┘
│
▼
gt molecule instantiate code-review
▼ bd mol bond [--wisp]
┌─────────────┐
│ Mol/Wisp │ Active execution
│ (flowing) │ Mol: .beads/ | Wisp: .beads-wisp/
└──────┬──────┘
│
▼
Generates 50-200 fix beads
│
▼
Prioritize and swarm
│
▼
Codebase improves overnight
│
▼
Repeat weekly
┌────┴────┐
▼ ▼
burn squash
│ │
▼ ▼
(gone) Digest
(permanent)
```
## Cross-Project Dependencies and Parking
Molecules can hit external dependencies that block progress. See
[cross-project-deps.md](cross-project-deps.md) for the full design.
### Parking a Molecule
When a molecule step depends on a capability from another project:
```bash
# Polecat discovers external dependency not satisfied
gt park --step=gt-mol.3 --waiting="beads:mol-run-assignee"
```
The molecule enters a **parked** state (derived from: in_progress + no assignee + blocked step).
### Resuming a Parked Molecule
When the external dependency is satisfied:
```bash
# Manual resume
gt spawn --continue gt-mol-root
# Or automated via Deacon patrol (future)
```
### Parked State
"Parked" is not a new status - it's derived from existing fields:
- Molecule status: `in_progress`
- Molecule assignee: `null` (no polecat owns it)
- Has step with unsatisfied `blocked_by: external:...`
Query parked molecules:
```bash
bd list --status=in_progress --no-assignee --type=molecule
```
## Future Extensions
### Custom Molecule Types
Beyond code-review, pluggable molecules could support:
- **migration-analysis**: Database migrations, API versioning
- **onboarding-review**: New hire documentation gaps
- **compliance-audit**: Regulatory requirements check
- **dependency-audit**: Outdated/vulnerable dependencies
### Scheduled Reviews
```yaml
# In rig config
scheduled_molecules:
- molecule: code-review
scope: "**/*.go"
schedule: "0 0 * * 0" # Weekly Sunday midnight
priority: 3
```
### Review Trends
Track findings over time:
```bash
gt review history --molecule=code-review
# Shows: findings per run, categories, fix rate
```
**Steam engine metaphor:**
- Proto = Fuel (potential energy)
- Mol/Wisp = Steam (kinetic energy)
- Digest = Distillate (crystallized work)
- Burn = Steam dissipates
- Squash = Steam condenses