From 57a84c6bade8a3bc43aaecfda3a8cc71e30a611d Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 25 Dec 2025 22:06:01 -0800 Subject: [PATCH] Update documentation and priming (gt-xmyha) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix CLAUDE.md: joe→max for correct crew worker identity - Add TOML formula documentation to molecules.md - Update wisp-architecture.md with wisp-gc docs - Update architecture.md with bd formula commands - Update molecular-chemistry.md with TOML examples - Add diagnostics section to CLAUDE.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 36 ++++++++++++++--- docs/architecture.md | 21 +++++----- docs/molecular-chemistry.md | 77 ++++++++++++++++++++++--------------- docs/molecules.md | 55 +++++++++++++++++++++++++- docs/wisp-architecture.md | 31 +++++++++++++++ 5 files changed, 172 insertions(+), 48 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4ee88d51..4fdb5eae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ > **Recovery**: Run `gt prime` after compaction, clear, or new session -## Your Role: CREW WORKER (joe in gastown) +## Your Role: CREW WORKER (max in gastown) You are a **crew worker** - the overseer's (human's) personal workspace within the gastown rig. Unlike polecats which are witness-managed and transient, you are: @@ -17,7 +17,7 @@ the overseer, not as part of a swarm. ## Your Identity -**Your mail address:** `gastown/joe` +**Your mail address:** `gastown/crew/max` Check your mail with: `gt mail inbox` @@ -29,7 +29,7 @@ Town (/Users/stevey/gt) ├── gastown/ ← Your rig │ ├── .beads/ ← Issue tracking (you have write access) │ ├── crew/ -│ │ └── joe/ ← You are here (your git clone) +│ │ └── max/ ← You are here (your git clone) │ ├── polecats/ ← Ephemeral workers (not you) │ ├── refinery/ ← Merge queue processor │ └── witness/ ← Polecat lifecycle (doesn't monitor you) @@ -63,7 +63,7 @@ go test ./... ### Communication - `gt mail send mayor/ -s "Subject" -m "Message"` - To Mayor -- `gt mail send gastown/crew/joe -s "Subject" -m "Message"` - To yourself (handoff) +- `gt mail send gastown/crew/max -s "Subject" -m "Message"` - To yourself (handoff) ## Git Workflow: Work Off Main @@ -119,6 +119,30 @@ Issue prefix: `gt-` everything: sends handoff mail, respawns with fresh context, and your work continues from where you left off via your pinned molecule. -Crew member: joe +## Formulas + +Formulas are workflow templates stored in `.beads/formulas/`. They support both +TOML (preferred) and JSON formats: + +```bash +bd formula list # List available formulas +bd formula show shiny # Show formula details +bd formula convert --all # Convert JSON to TOML +bd cook shiny # Compile formula to proto +``` + +TOML is preferred for human-edited formulas (multi-line strings, comments). + +## Key Diagnostics + +```bash +gt doctor # Run all health checks +gt doctor --fix # Auto-fix common issues +gt doctor -v # Verbose output +gt status # Town-wide status +bd doctor # Beads-specific checks +``` + +Crew member: max Rig: gastown -Working directory: /Users/stevey/gt/gastown/crew/joe +Working directory: /Users/stevey/gt/gastown/crew/max diff --git a/docs/architecture.md b/docs/architecture.md index 8e88a907..63b86bd0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -365,7 +365,7 @@ workflows that any worker can execute, with full auditability and the ability fo any worker to pick up where another left off. Work flows through the **Rig → Cook → Run** lifecycle: -- **Rig**: Compose workflow formulas (YAML source files with `extends`, `compose`) +- **Rig**: Compose workflow formulas (TOML/JSON files with `extends`, `compose`) - **Cook**: Transform formulas into executable protos (`bd cook` expands macros, applies aspects) - **Run**: Agents execute the cooked workflow (pour creates mols, wisp creates ephemeral traces) @@ -375,7 +375,7 @@ See [molecular-chemistry.md](molecular-chemistry.md) for the full lifecycle spec | Concept | Name | Description | |---------|------|-------------| -| Source | **Formula** | YAML workflow definition with composition rules (.formula.yaml) | +| Source | **Formula** | TOML/JSON workflow definition with composition rules (.formula.toml preferred) | | Template | **Proto Molecule** | Cooked workflow pattern (the "fuel") | | Running execution | **Wisp Molecule** | Transient execution trace (the "steam") | | Permanent record | **Digest** | Compressed summary of completed work (the "distillate") | @@ -735,22 +735,25 @@ investigate → document ``` Exploration workflow for understanding problems. -Cook formula files into proto beads: +Formula files support both TOML (preferred) and JSON formats: ```bash -bd cook +bd formula list # List available formulas +bd formula show shiny # Show formula details +bd formula convert --all # Convert JSON to TOML +bd cook # Cook formula into proto bead ``` ### Usage ```bash -# List available molecules -gt molecule list +# List available molecules (cooked protos) +bd mol list # Show molecule details -gt molecule show mol-shiny +bd mol show mol-shiny -# Instantiate on an issue -gt molecule instantiate mol-shiny --parent=gt-xyz +# Bond (instantiate) a molecule +bd mol bond mol-shiny --var feature_name="auth" # Spawn polecat with molecule gt spawn --issue gt-xyz --molecule mol-shiny diff --git a/docs/molecular-chemistry.md b/docs/molecular-chemistry.md index 8338f8b6..a07794dc 100644 --- a/docs/molecular-chemistry.md +++ b/docs/molecular-chemistry.md @@ -25,7 +25,7 @@ RIG ────→ COOK ────→ RUN | **Cook** | Instantiate artifacts | `cook`, `pour`, `wisp` | Proto, Mol, Wisp | | **Run** | Execute steps | (agent execution) | Work done | -**Rig** is authoring time - writing and composing formula YAML files. +**Rig** is authoring time - writing and composing formula files (TOML preferred, JSON supported). **Cook** is compile time - expanding macros, applying aspects, flattening to pure graphs. **Run** is execution time - agents provide cognition for each step. @@ -73,10 +73,10 @@ Gas Town has **two** composition operators at different abstraction levels: | Operator | Level | Inputs | When to Use | |----------|-------|--------|-------------| -| **Rig** | Source | Formula + Formula | Authoring time, in YAML | +| **Rig** | Source | Formula + Formula | Authoring time, in TOML/JSON | | **Bond** | Artifact | Proto/Mol/Wisp + any | Runtime, on cooked artifacts | -**Rig** composes formulas (YAML with `extends`, `compose`). +**Rig** composes formulas (TOML/JSON with `extends`, `compose`). **Bond** composes artifacts (cooked protos, running mols/wisps). This separation is key: rig for design-time composition, bond for runtime composition. @@ -102,41 +102,54 @@ In our chemistry: ## Formulas: The Source Layer **Formulas** sit above protos in the artifact hierarchy. They're the source code - -YAML files that define workflows with composition operators. +TOML or JSON files that define workflows with composition operators. -```yaml -# shiny.formula.yaml - a basic workflow -formula: shiny -description: The canonical right way -version: 1 -steps: - - id: design - description: Think carefully about architecture - - id: implement - needs: [design] - - id: review - needs: [implement] - - id: test - needs: [review] - - id: submit - needs: [test] +TOML is preferred for human-edited formulas (multi-line strings, comments): + +```toml +# shiny.formula.toml - a basic workflow +formula = "shiny" +description = "The canonical right way" +version = 1 + +[[steps]] +id = "design" +description = "Think carefully about architecture" + +[[steps]] +id = "implement" +needs = ["design"] + +[[steps]] +id = "review" +needs = ["implement"] + +[[steps]] +id = "test" +needs = ["review"] + +[[steps]] +id = "submit" +needs = ["test"] ``` +Convert existing JSON formulas with `bd formula convert --all`. + ### Formula Composition (Rigging) Formulas compose at the source level using `extends` and `compose`: -```yaml -# shiny-enterprise.formula.yaml -formula: shiny-enterprise -extends: shiny # Inherit from base formula -compose: - - expand: - target: implement - with: rule-of-five # Apply macro expansion - - aspect: - pointcut: "implement.*" - with: security-audit # Weave in cross-cutting concern +```toml +# shiny-enterprise.formula.toml +formula = "shiny-enterprise" +extends = ["shiny"] # Inherit from base formula + +[compose] +aspects = ["security-audit"] # Weave in cross-cutting concern + +[[compose.expand]] +target = "implement" +with = "rule-of-five" # Apply macro expansion ``` ### Cooking: Formula → Proto @@ -178,7 +191,7 @@ encode reusable work structures. They're the "molds" from which instances are ca Protos are stored as beads issues with `labels: ["template"]` and structured step data: ```yaml -# Example: shiny.formula.yaml (source) → cooked proto (beads) +# Example: shiny.formula.toml (source) → cooked proto (beads) formula: shiny description: The canonical right way version: 1 diff --git a/docs/molecules.md b/docs/molecules.md index e0155d17..968dfac3 100644 --- a/docs/molecules.md +++ b/docs/molecules.md @@ -285,9 +285,62 @@ Gas Town work follows the **Rig → Cook → Run** lifecycle: ``` **Full lifecycle:** -- **Formula** (.formula.yaml) = Recipe (source code for workflows) +- **Formula** (.formula.toml or .formula.json) = Recipe (source code for workflows) - **Proto** = Fuel (cooked template, ready to instantiate) - **Mol/Wisp** = Steam (active execution) - **Digest** = Distillate (crystallized work) See [molecular-chemistry.md](molecular-chemistry.md) for the complete specification. + +## Formula File Formats + +Formulas support both TOML (preferred) and JSON formats: + +```bash +# List available formulas +bd formula list + +# Show formula details +bd formula show shiny + +# Convert JSON to TOML (better for human editing) +bd formula convert shiny # Single formula +bd formula convert --all # All formulas +bd formula convert shiny --stdout # Preview +``` + +**Why TOML?** +- Multi-line strings without `\n` escaping +- Comments allowed +- Human-readable diffs +- Same parsing semantics as JSON + +The loader tries `.formula.toml` first, falling back to `.formula.json`. + +### Example Formula (TOML) + +```toml +formula = "shiny" +type = "workflow" +version = 1 +description = """ +Engineer in a Box - design before code, review before ship. +""" + +[vars.feature] +description = "The feature being implemented" +required = true + +[[steps]] +id = "design" +title = "Design {{feature}}" +description = """ +Think carefully about architecture before writing code. +Consider edge cases and simpler approaches. +""" + +[[steps]] +id = "implement" +title = "Implement {{feature}}" +needs = ["design"] +``` diff --git a/docs/wisp-architecture.md b/docs/wisp-architecture.md index b0446e67..761fab61 100644 --- a/docs/wisp-architecture.md +++ b/docs/wisp-architecture.md @@ -79,6 +79,37 @@ Agent hook files (`hook-.json`) are stored in `.beads/` but are local-onl runtime state, not synced. These track what work is assigned to each agent for restart-and-resume. +## Wisp Garbage Collection + +Wisps can accumulate over time. The `wisp-gc` doctor check cleans up stale wisps: + +```bash +# Check for stale wisps +gt doctor -v + +# Auto-cleanup stale wisps (>1h old by default) +gt doctor --fix + +# Manual cleanup via bd +bd wisp gc # Preview what would be cleaned +bd wisp gc --force # Actually delete stale wisps +bd wisp gc --age 2h # Custom age threshold +``` + +The Deacon includes wisp-gc in its patrol cycle via `gt doctor --fix`. + +### What Gets Cleaned + +- Wisps older than the threshold (default 1 hour) +- Wisps not associated with active sessions +- Orphaned lifecycle mail + +### What's Preserved + +- Wisps with active sessions still running +- Wisps younger than the threshold +- Non-wisp issues (permanent records) + ## Decision Matrix | Question | Answer | Use |