docs: Plugins ARE molecules - remove YAML/markdown format
- 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
@@ -438,66 +438,61 @@ The choice between **Mol** (durable) and **Wisp** (transient) depends on the wor
|
|||||||
|
|
||||||
### Molecule Format
|
### Molecule Format
|
||||||
|
|
||||||
Molecules use a prose-based format with structured step definitions:
|
Molecules are stored as JSONL in `molecules.jsonl`:
|
||||||
|
|
||||||
```markdown
|
```json
|
||||||
## Molecule: engineer-in-box
|
{
|
||||||
Full workflow from design to merge.
|
"id": "mol-engineer-in-box",
|
||||||
|
"title": "Engineer in Box: {{feature}}",
|
||||||
## Step: design
|
"description": "Full workflow from design to merge.",
|
||||||
Think carefully about architecture. Consider:
|
"labels": ["template"],
|
||||||
- Existing patterns in the codebase
|
"issue_type": "epic"
|
||||||
- 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Key format elements:**
|
Steps are hierarchical children with dependencies encoded as beads edges:
|
||||||
- `## Step: <name>` - Step header with reference name
|
|
||||||
- Prose instructions - What the step should accomplish
|
```
|
||||||
- `Needs: <step1>, <step2>` - Dependencies (optional)
|
mol-engineer-in-box
|
||||||
- `Tier: haiku|sonnet|opus` - Model hint (optional)
|
├── .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
|
### Molecule Composition
|
||||||
|
|
||||||
Molecules can include other molecules to create derived workflows:
|
Molecules compose via bonding - attaching one molecule to another:
|
||||||
|
|
||||||
```markdown
|
```
|
||||||
## Molecule: gastown-polecat
|
mol-gastown-polecat (composed)
|
||||||
Full workflow for Gas Town polecats including binary installation.
|
├── [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
|
**Composition via bond:**
|
||||||
|
```bash
|
||||||
## Step: install-binary
|
bd mol bond mol-engineer-in-box $PARENT_MOL
|
||||||
After merge is submitted, rebuild and install the local gt binary.
|
bd create "Install binary" --parent=$PARENT_MOL --deps=.5
|
||||||
Run from the rig directory:
|
|
||||||
go build -o gt ./cmd/gt
|
|
||||||
go install ./cmd/gt
|
|
||||||
Needs: submit
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Semantics:**
|
**Semantics:**
|
||||||
- `Includes:` brings in all steps from the referenced molecule
|
- Bonding attaches one molecule's steps as children
|
||||||
- New steps can depend on included steps (e.g., `Needs: submit`)
|
- New steps can depend on bonded steps
|
||||||
- Multiple includes are supported for complex polymers
|
- Multiple bonds create complex polymers
|
||||||
- Dependencies are resolved transitively at parse time
|
- Dependencies are standard beads edges
|
||||||
|
|
||||||
### Nondeterministic Idempotence
|
### Nondeterministic Idempotence
|
||||||
|
|
||||||
@@ -823,127 +818,48 @@ Molecules aren't just for implementing features. Any multi-step process that req
|
|||||||
|
|
||||||
#### mol-polecat-work
|
#### mol-polecat-work
|
||||||
|
|
||||||
The full polecat lifecycle, not just "do the issue":
|
The full polecat lifecycle:
|
||||||
|
|
||||||
```markdown
|
```
|
||||||
## Molecule: polecat-work
|
mol-polecat-work
|
||||||
Full polecat lifecycle from assignment to decommission.
|
├── .1 load-context "gt prime, bd prime, check inbox"
|
||||||
|
├── .2 implement "Write code, file discovered work" ← .1
|
||||||
## Step: load-context
|
├── .3 self-review "Check for bugs, security issues" ← .2
|
||||||
Run gt prime and bd prime. Verify issue assignment.
|
├── .4 verify-tests "Run tests, add coverage" ← .2
|
||||||
Check inbox for any relevant messages.
|
├── .5 rebase-main "Rebase, resolve conflicts" ← .3, .4
|
||||||
|
├── .6 submit-merge "Submit to queue, verify CI" ← .5
|
||||||
## Step: implement
|
├── .7 generate-summary "Squash summary, file remaining work" ← .6
|
||||||
Implement the solution. Follow codebase conventions.
|
└── .8 request-shutdown "Signal Witness, wait for kill" ← .7
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**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
|
#### mol-rig-activate
|
||||||
|
|
||||||
Activating a rig for work:
|
Activating a rig for work:
|
||||||
|
|
||||||
```markdown
|
```
|
||||||
## Molecule: rig-activate
|
mol-rig-activate
|
||||||
Activate a rig and spawn workers.
|
├── .1 verify-rig "Check config, git remote"
|
||||||
|
├── .2 start-witness "Start if needed, verify health" ← .1
|
||||||
## Step: verify-rig
|
├── .3 start-refinery "Start if needed, verify health" ← .1
|
||||||
Check rig exists and is properly configured.
|
├── .4 sync-beads "Sync from remote" ← .2
|
||||||
Verify git remote is accessible.
|
├── .5 identify-ready "Query bd ready, prioritize" ← .4
|
||||||
|
└── .6 spawn-workers "Spawn polecats for work" ← .5, .3
|
||||||
## 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-graceful-shutdown
|
#### mol-graceful-shutdown
|
||||||
|
|
||||||
Shutting down Gas Town properly:
|
Shutting down Gas Town properly:
|
||||||
|
|
||||||
```markdown
|
```
|
||||||
## Molecule: graceful-shutdown
|
mol-graceful-shutdown
|
||||||
Graceful shutdown with handoff preservation.
|
├── .1 notify-agents "Send shutdown to all agents"
|
||||||
|
├── .2 wait-squash "Wait for molecule completion" ← .1
|
||||||
## Step: notify-agents
|
├── .3 verify-clean "Check git states clean" ← .2
|
||||||
Send shutdown notification to all agents.
|
├── .4 kill-workers "Terminate polecats, worktrees" ← .3
|
||||||
Record which agents acknowledged.
|
├── .5 kill-core "Terminate Witness, Refinery" ← .4
|
||||||
|
└── .6 final-sync "Final beads sync" ← .5
|
||||||
## 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Key principle**: If a multi-step process requires cognition and can fail partway through, it should be a molecule. This applies to:
|
**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
|
### 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.
|
||||||
|
|
||||||
```
|
```json
|
||||||
~/gt/molecules/code-review/
|
{
|
||||||
├── discovery/
|
"id": "mol-security-scan",
|
||||||
│ ├── file-census/
|
"title": "Security scan: {{scope}}",
|
||||||
│ │ └── CLAUDE.md # Instructions for this step
|
"description": "Check for OWASP Top 10 vulnerabilities in {{scope}}",
|
||||||
│ ├── dep-graph/
|
"labels": ["template", "plugin", "code-review", "phase:tactical", "tier:sonnet"],
|
||||||
│ │ └── CLAUDE.md
|
"issue_type": "task"
|
||||||
│ └── 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Add a dimension**: Create a directory with CLAUDE.md
|
**Add a dimension**: Install a plugin molecule (`bd mol install mol-security-scan`)
|
||||||
**Remove a dimension**: Delete the directory
|
**Remove a dimension**: Uninstall or don't bond it
|
||||||
**Customize a dimension**: Edit its CLAUDE.md
|
**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
|
| Label | Purpose |
|
||||||
---
|
|-------|---------|
|
||||||
phase: tactical
|
| `plugin` | Marks as bondable at hook points |
|
||||||
needs: [structural-complete]
|
| `code-review` | Which molecule can use this plugin |
|
||||||
tier: sonnet
|
| `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...
|
At runtime, the parent molecule bonds plugins based on labels:
|
||||||
```
|
|
||||||
|
|
||||||
| 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
|
|
||||||
|
|
||||||
```bash
|
```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 (mol-code-review instance)
|
||||||
gt-xyz.discovery-dep-graph
|
├── discovery plugins (parallel)
|
||||||
gt-xyz.structural-architecture-review # blocks tactical
|
│ ├── .file-census
|
||||||
gt-xyz.tactical-src-auth-security
|
│ ├── .dep-graph
|
||||||
gt-xyz.tactical-src-auth-performance
|
│ └── .coverage-map
|
||||||
gt-xyz.synthesis
|
├── 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
|
#### Code Review Molecule
|
||||||
|
|
||||||
The **code-review** molecule is the reference implementation:
|
The **mol-code-review** molecule is the reference implementation:
|
||||||
|
|
||||||
**Discovery Phase** (parallel scouts):
|
**Discovery Phase** (parallel scouts):
|
||||||
- `file-census` - Inventory: sizes, ages, churn rates
|
- `mol-file-census` - Inventory: sizes, ages, churn rates
|
||||||
- `dep-graph` - Dependencies, cycles, inversions
|
- `mol-dep-graph` - Dependencies, cycles, inversions
|
||||||
- `coverage-map` - Test coverage, dead code
|
- `mol-coverage-map` - Test coverage, dead code
|
||||||
- `duplication-scan` - Near-duplicate files, copy-paste debt
|
|
||||||
|
|
||||||
**Structural Phase** (sequential):
|
**Structural Phase** (sequential):
|
||||||
- `architecture-review` - Does structure match domain?
|
- `mol-architecture-review` - Does structure match domain?
|
||||||
- `abstraction-analysis` - Wrangling at wrong layers?
|
- `mol-abstraction-analysis` - Wrangling at wrong layers?
|
||||||
- `consolidation-planner` - What should be unified?
|
|
||||||
|
|
||||||
**Tactical Phase** (parallel per hotspot):
|
**Tactical Phase** (parallel per hotspot):
|
||||||
- `security-scan` - OWASP Top 10, injection, auth bypass
|
- `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 |
|
| Aspect | Static Molecule | Pluggable Molecule |
|
||||||
|--------|-----------------|-------------------|
|
|--------|-----------------|-------------------|
|
||||||
| Definition | Steps in issue description | Steps from directory scan |
|
| Definition | Steps defined at template time | Steps bonded at runtime |
|
||||||
| Add step | Edit molecule bead | Create directory |
|
| Add step | Edit molecule template | Install plugin molecule |
|
||||||
| Remove step | Edit molecule bead | Delete directory |
|
| Remove step | Edit molecule template | Don't bond it |
|
||||||
| Customization | Edit description | Edit plugin CLAUDE.md |
|
| Customization | Edit description | Fork plugin molecule |
|
||||||
| Use case | Fixed workflows | Extensible workflows |
|
| 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
|
## 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)
|
│ │ │ └── <project files> # (inherits beads from rig)
|
||||||
│ │ └── Toast/ # Git worktree from Mayor's clone
|
│ │ └── Toast/ # Git worktree from Mayor's clone
|
||||||
│ │
|
│ │
|
||||||
│ └── plugins/ # Optional plugins
|
│ └── molecules.jsonl # Optional local molecule catalog
|
||||||
│ └── merge-oracle/
|
|
||||||
│ ├── CLAUDE.md
|
|
||||||
│ └── state.json
|
|
||||||
│
|
│
|
||||||
└── wyvern/ # Another rig (same structure)
|
└── wyvern/ # Another rig (same structure)
|
||||||
├── config.json
|
├── config.json
|
||||||
@@ -1650,9 +1527,9 @@ sequenceDiagram
|
|||||||
- Zero new infrastructure needed (uses existing mail, beads, identities)
|
- Zero new infrastructure needed (uses existing mail, beads, identities)
|
||||||
- Composable - plugins can invoke other plugins via mail
|
- Composable - plugins can invoke other plugins via mail
|
||||||
- Debuggable - just look at mail logs and bead history
|
- 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
|
### 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
|
### 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
|
### Invoking Plugins
|
||||||
|
|
||||||
Plugins are invoked like any other agent - via mail:
|
Plugins are bonded during patrol execution:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Refinery asks merge-oracle to analyze pending changesets
|
# In mol-refinery-patrol plugin-run step:
|
||||||
gt send wyvern/plugins/merge-oracle -s "Analyze merge queue" -m "..."
|
bd mol bond mol-merge-oracle $PATROL_WISP \
|
||||||
|
--var queue_state="$QUEUE_JSON"
|
||||||
# Mayor asks plan-oracle for a work breakdown
|
|
||||||
gt send beads/plugins/plan-oracle -s "Plan for bd-xyz" -m "..."
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
### 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 |
|
| Workflow Point | Patrol | Label Filter |
|
||||||
|----------------|-------|----------------|
|
|----------------|--------|--------------|
|
||||||
| Before merge processing | Refinery | merge-oracle |
|
| Refinery patrol | mol-refinery-patrol | `plugin,refinery` |
|
||||||
| Before work dispatch | Mayor | plan-oracle |
|
| Witness patrol | mol-witness-patrol | `plugin,witness` |
|
||||||
| On worker stuck | Witness | debug-oracle |
|
| Deacon patrol | mol-deacon-patrol | `plugin,deacon` |
|
||||||
| On PR ready | Refinery | review-oracle |
|
|
||||||
| Periodic / on-demand | Mayor | beads-hygiene |
|
|
||||||
|
|
||||||
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
|
### 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)
|
- Mail to Refinery with recommendation (proceed / escalate to Mayor)
|
||||||
- If escalation needed: mail to Mayor with explanation
|
- 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
|
### 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)
|
- Mayor can invoke periodically (nightly hygiene scan)
|
||||||
- Any agent can invoke on-demand when confused
|
- 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
|
You are reviewing beads databases for cross-pollution between Gas Town's
|
||||||
two-level architecture:
|
two-level architecture:
|
||||||
|
|||||||
@@ -1,691 +1,293 @@
|
|||||||
# Molecules: Composable Workflow Templates
|
# Molecules: Composable Workflow Templates
|
||||||
|
|
||||||
This document covers the molecule system in depth, including pluggable molecules
|
This document covers the molecule system in depth.
|
||||||
and the code-review molecule design.
|
|
||||||
|
|
||||||
For an overview, see [architecture.md](architecture.md#molecules-composable-workflow-templates).
|
For an overview, see [architecture.md](architecture.md#molecules-composable-workflow-templates).
|
||||||
|
|
||||||
## Core Concepts
|
## Core Concepts
|
||||||
|
|
||||||
A **molecule** is a crystallized workflow pattern stored as a beads issue. When
|
A **molecule** is a workflow template stored as a beads issue with `labels: ["template"]`.
|
||||||
instantiated on a parent issue, it creates child beads forming a DAG of steps.
|
When bonded, it creates child issues 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:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
~/gt/molecules/code-review/
|
Proto (template)
|
||||||
├── 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)
|
|
||||||
│
|
│
|
||||||
▼ bd mol bond
|
▼ bd mol bond
|
||||||
┌────────────────────┐
|
┌─────────────────┐
|
||||||
│ Mol (durable) or │
|
│ Mol (durable) │ ← .beads/ (synced, auditable)
|
||||||
│ Wisp (ephemeral) │
|
│ or │
|
||||||
└────────┬───────────┘
|
│ Wisp (ephemeral)│ ← .beads-wisp/ (gitignored)
|
||||||
|
└────────┬────────┘
|
||||||
│
|
│
|
||||||
┌────────┴────────┐
|
┌─────┴─────┐
|
||||||
▼ ▼
|
▼ ▼
|
||||||
bd mol burn bd mol squash
|
bd mol burn bd mol squash
|
||||||
(no record) (creates digest)
|
(no record) (creates digest)
|
||||||
```
|
```
|
||||||
|
|
||||||
**Key insight**: The molecule lifecycle maps to Gas Town's steam engine metaphor:
|
| Concept | Description |
|
||||||
- **Proto** = Fuel (frozen template)
|
|---------|-------------|
|
||||||
- **Mol/Wisp** = Steam (active execution)
|
| Proto | Template molecule (is_template: true in beads) |
|
||||||
- **Digest** = Distillate (condensed permanent record)
|
| Mol | Durable instance in .beads/ |
|
||||||
- **Burn** = Steam dissipates (no condensation)
|
| Wisp | Ephemeral instance in .beads-wisp/ |
|
||||||
- **Squash** = Steam condenses (captured as digest)
|
| 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
|
```json
|
||||||
---
|
{
|
||||||
phase: tactical
|
"id": "mol-engineer-in-box",
|
||||||
needs: [structural-complete]
|
"title": "Engineer in Box: {{feature_name}}",
|
||||||
tier: sonnet
|
"description": "Full workflow from design to merge.\n\nVars:\n- {{feature_name}} - What to build",
|
||||||
---
|
"labels": ["template"],
|
||||||
|
"issue_type": "epic"
|
||||||
# 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`.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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 |
|
## Variable Substitution
|
||||||
|-------|------|-------------|
|
|
||||||
| `phase` | string | Execution phase: discovery, structural, tactical, synthesis |
|
|
||||||
| `needs` | list | Step references that must complete first |
|
|
||||||
| `tier` | string | Model hint: haiku, sonnet, opus |
|
|
||||||
|
|
||||||
### Phase Semantics
|
Molecules support `{{var}}` placeholders resolved at bond time:
|
||||||
|
|
||||||
| Phase | Blocks | Parallelism | Purpose |
|
```bash
|
||||||
|-------|--------|-------------|---------|
|
bd mol bond mol-engineer-in-box --var feature_name="user auth"
|
||||||
| discovery | nothing | full | Inventory, gather data |
|
# Creates: "Engineer in Box: user auth"
|
||||||
| structural | discovery | sequential | Big picture analysis |
|
```
|
||||||
| tactical | structural | per-component | Detailed review |
|
|
||||||
| synthesis | tactical | single | Aggregate results |
|
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
|
## Code Review Molecule
|
||||||
|
|
||||||
The code-review molecule is the reference implementation for pluggable molecules.
|
The code-review molecule is a pluggable workflow:
|
||||||
|
|
||||||
### Directory Structure
|
|
||||||
|
|
||||||
```
|
```
|
||||||
~/gt/molecules/code-review/
|
mol-code-review
|
||||||
├── README.md # Molecule overview
|
├── discovery (parallel)
|
||||||
|
│ ├── file-census
|
||||||
|
│ ├── dep-graph
|
||||||
|
│ └── coverage-map
|
||||||
│
|
│
|
||||||
├── discovery/ # Phase 1: Parallel scouts
|
├── structural (sequential)
|
||||||
│ ├── file-census/
|
│ ├── architecture-review
|
||||||
│ │ └── CLAUDE.md # Inventory: sizes, ages, churn
|
│ └── abstraction-analysis
|
||||||
│ ├── dep-graph/
|
|
||||||
│ │ └── CLAUDE.md # Dependencies, cycles, inversions
|
|
||||||
│ ├── coverage-map/
|
|
||||||
│ │ └── CLAUDE.md # Test coverage, dead code
|
|
||||||
│ └── duplication-scan/
|
|
||||||
│ └── CLAUDE.md # Near-duplicates, copy-paste
|
|
||||||
│
|
│
|
||||||
├── structural/ # Phase 2: Sequential for coherence
|
├── tactical (parallel per component)
|
||||||
│ ├── architecture-review/
|
│ ├── security-scan
|
||||||
│ │ └── CLAUDE.md # Structure vs domain alignment
|
│ ├── performance-review
|
||||||
│ ├── abstraction-analysis/
|
│ └── complexity-analysis
|
||||||
│ │ └── CLAUDE.md # Wrong-layer wrangling
|
|
||||||
│ └── consolidation-planner/
|
|
||||||
│ └── CLAUDE.md # What should be unified
|
|
||||||
│
|
│
|
||||||
├── tactical/ # Phase 3: Parallel per hotspot
|
└── synthesis (single)
|
||||||
│ ├── security-scan/
|
└── aggregate
|
||||||
│ │ └── 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
**Usage:**
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Run full code review on project
|
bd mol bond mol-code-review --var scope="src/"
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Scoped Review
|
## Lifecycle Summary
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
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
|
│ Proto │ Template in molecules.jsonl
|
||||||
gt-perf-001 N+1 query in user list type=bug priority=2 label=performance
|
│ (frozen) │ labels: ["template"]
|
||||||
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?
|
|
||||||
│
|
│
|
||||||
▼
|
▼ bd mol bond [--wisp]
|
||||||
gt molecule instantiate code-review
|
┌─────────────┐
|
||||||
|
│ Mol/Wisp │ Active execution
|
||||||
|
│ (flowing) │ Mol: .beads/ | Wisp: .beads-wisp/
|
||||||
|
└──────┬──────┘
|
||||||
│
|
│
|
||||||
▼
|
┌────┴────┐
|
||||||
Generates 50-200 fix beads
|
▼ ▼
|
||||||
│
|
burn squash
|
||||||
▼
|
│ │
|
||||||
Prioritize and swarm
|
▼ ▼
|
||||||
│
|
(gone) Digest
|
||||||
▼
|
(permanent)
|
||||||
Codebase improves overnight
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
Repeat weekly
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Cross-Project Dependencies and Parking
|
**Steam engine metaphor:**
|
||||||
|
- Proto = Fuel (potential energy)
|
||||||
Molecules can hit external dependencies that block progress. See
|
- Mol/Wisp = Steam (kinetic energy)
|
||||||
[cross-project-deps.md](cross-project-deps.md) for the full design.
|
- Digest = Distillate (crystallized work)
|
||||||
|
- Burn = Steam dissipates
|
||||||
### Parking a Molecule
|
- Squash = Steam condenses
|
||||||
|
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|||||||
Reference in New Issue
Block a user