diff --git a/docs/architecture.md b/docs/architecture.md index a47bff88..facee60e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,6 +4,8 @@ Gas Town is a multi-agent workspace manager that coordinates AI coding agents wo **Key insight**: Work is a stream, not discrete batches. The Refinery's merge queue is the coordination mechanism. Beads (issues) are the data plane. There are no "swarm IDs" - just epics with children, processed by workers, merged through the queue. +**Molecule-first paradigm**: Gas Town is fundamentally a molecule execution engine. Workers don't just "work on issues" - they execute molecules. The issue is seed data; the molecule defines the workflow. This enables nondeterministic idempotence: any worker can pick up where another left off, surviving crashes, context compaction, and restarts. If a process requires cognition, it should be a molecule. See [Molecules](#molecules-composable-workflow-templates) for full details. + ## System Overview ```mermaid @@ -427,6 +429,43 @@ Both use similar structures but different semantics: - Templates focus on parameterization (`{{variable}}` substitution) - Molecules focus on execution (step states, nondeterministic dispatch) +### Config vs Molecule: When to Use Which + +**The Key Principle: If it requires cognition, it's a molecule.** + +| Use Case | Config | Molecule | +|----------|--------|----------| +| Static policy (max workers, timeouts) | ✅ | ❌ | +| Agent workflow (design → implement → test) | ❌ | ✅ | +| Outpost routing preferences | ✅ | ❌ | +| Error recovery with decisions | ❌ | ✅ | +| Environment variables | ✅ | ❌ | +| Multi-step processes that can fail | ❌ | ✅ | + +**Config** (`config.json`, `outposts.yaml`): +- Declarative settings +- No decision-making required +- Read once at startup +- Changes require restart + +**Molecules**: +- Procedural workflows +- Require agent cognition at each step +- Survive agent restarts +- Track progress through step states + +**Example: Outpost Assignment** + +Static policy in `outposts.yaml`: +```yaml +policy: + default_preference: [local, gce-burst, cloudrun-burst] +``` + +But if assignment requires cognition (analyzing work characteristics, checking outpost health, making tradeoffs), escalate to a molecule like `mol-outpost-assign`. + +**The insight**: Gas Town doesn't spawn workers on issues. It spawns workers on molecules. The issue is just the seed data for the molecule execution. + ### Operational Molecules Molecules aren't just for implementing features. Any multi-step process that requires cognition, can fail partway through, or needs to survive agent restarts should be a molecule. @@ -1591,7 +1630,7 @@ gt capture "" # Run command in polecat session ### Session Management ```bash -gt spawn --issue # Start polecat on issue (creates fresh worktree) +gt spawn --issue --molecule mol-engineer-in-box # Spawn polecat with workflow gt handoff # Polecat requests shutdown (run when done) gt session stop

# Kill polecat session (Witness uses this) ``` diff --git a/docs/bootstrap.md b/docs/bootstrap.md index a17eb2c6..ad8987a5 100644 --- a/docs/bootstrap.md +++ b/docs/bootstrap.md @@ -221,4 +221,4 @@ echo "Bootstrap complete!" After bootstrapping: 1. Start a Mayor session: `gt mayor attach` 2. Check for work: `bd ready` -3. Spawn workers as needed: `gt spawn --issue ` +3. Spawn workers with molecules: `gt spawn --issue --molecule mol-engineer-in-box` diff --git a/docs/federation-design.md b/docs/federation-design.md index 129b38a1..5fc6a492 100644 --- a/docs/federation-design.md +++ b/docs/federation-design.md @@ -394,6 +394,8 @@ policy: prefer: gce-worker-1 ``` +**When policy becomes a molecule**: Static policy handles simple preference-based routing. But when assignment requires cognition - analyzing work characteristics, checking outpost health in real-time, making cost/speed tradeoffs, or handling degraded outposts - escalate to `mol-outpost-assign`. The policy file declares preferences; the molecule executes intelligent assignment. See [Config vs Molecule](architecture.md#config-vs-molecule-when-to-use-which) for the general principle. + ## Implementation Phases ### Phase 1: Outpost Abstraction (Local) diff --git a/internal/templates/roles/mayor.md.tmpl b/internal/templates/roles/mayor.md.tmpl index 69932b99..221c13e8 100644 --- a/internal/templates/roles/mayor.md.tmpl +++ b/internal/templates/roles/mayor.md.tmpl @@ -53,7 +53,7 @@ Town ({{ .TownRoot }}) ### Work Management - `bd ready` - Issues ready to work (no blockers) - `bd list --status=open` - All open issues -- `gt spawn --issue ` - Start polecat on issue +- `gt spawn --issue --molecule ` - Spawn polecat with molecule workflow ### Delegation Prefer delegating to Refineries, not directly to polecats: