docs: add Formula + Cook terminology and example formulas (gt-8tmz)
Updates to molecule-algebra.md: - Added Formulas and Cooking section - Four-tier model: Formula → cook → Proto → pour/wisp → Mol/Wisp - Breaking Bad × Mad Max naming (Let's cook!) - Updated vision diagram New example formulas: - shiny.formula.yaml (Engineer in a Box) - rule-of-five.formula.yaml (Jeffrey's Rule expansion macro) - security-audit.formula.yaml (AOP aspect) - shiny-enterprise.formula.yaml (composed example)
This commit is contained in:
61
.beads/formulas/rule-of-five.formula.yaml
Normal file
61
.beads/formulas/rule-of-five.formula.yaml
Normal file
@@ -0,0 +1,61 @@
|
|||||||
|
# rule-of-five.formula.yaml
|
||||||
|
# Jeffrey's Rule: Agents converge on best output in 4-5 iterations
|
||||||
|
# Breadth-first cognition, then editorial passes
|
||||||
|
|
||||||
|
formula: rule-of-five
|
||||||
|
type: expansion
|
||||||
|
description: |
|
||||||
|
Jeffrey Emanuel's discovery: LLM agents (and humans) produce their best
|
||||||
|
work through iterative refinement. The first pass is breadth-first
|
||||||
|
exploration; subsequent passes are editorial refinement.
|
||||||
|
|
||||||
|
Apply this to any step that benefits from iteration:
|
||||||
|
- Writing (code, docs, plans)
|
||||||
|
- Analysis (reviews, investigations)
|
||||||
|
- Design (architecture, interfaces)
|
||||||
|
|
||||||
|
The expansion replaces one step with five sequential steps.
|
||||||
|
version: 1
|
||||||
|
|
||||||
|
# This is a macro/expansion template
|
||||||
|
# When applied to a target step, it expands to 5 steps
|
||||||
|
|
||||||
|
template:
|
||||||
|
- id: "{target}.draft"
|
||||||
|
description: |
|
||||||
|
Initial attempt at: {target.description}
|
||||||
|
|
||||||
|
Don't aim for perfection. Get the shape right.
|
||||||
|
Breadth over depth. Explore the space.
|
||||||
|
|
||||||
|
- id: "{target}.refine-1"
|
||||||
|
description: |
|
||||||
|
First refinement pass. Focus: CORRECTNESS.
|
||||||
|
|
||||||
|
Review the draft. Fix errors, bugs, mistakes.
|
||||||
|
Is the logic sound? Are the facts right?
|
||||||
|
needs: ["{target}.draft"]
|
||||||
|
|
||||||
|
- id: "{target}.refine-2"
|
||||||
|
description: |
|
||||||
|
Second refinement pass. Focus: CLARITY.
|
||||||
|
|
||||||
|
Can someone else understand this?
|
||||||
|
Simplify. Remove jargon. Add explanations where needed.
|
||||||
|
needs: ["{target}.refine-1"]
|
||||||
|
|
||||||
|
- id: "{target}.refine-3"
|
||||||
|
description: |
|
||||||
|
Third refinement pass. Focus: EDGE CASES.
|
||||||
|
|
||||||
|
What could go wrong? What's missing?
|
||||||
|
Handle the unusual inputs, the error paths, the corner cases.
|
||||||
|
needs: ["{target}.refine-2"]
|
||||||
|
|
||||||
|
- id: "{target}.refine-4"
|
||||||
|
description: |
|
||||||
|
Final polish. Focus: EXCELLENCE.
|
||||||
|
|
||||||
|
This is the last pass. Make it shine.
|
||||||
|
Is this something you'd be proud to ship?
|
||||||
|
needs: ["{target}.refine-3"]
|
||||||
48
.beads/formulas/security-audit.formula.yaml
Normal file
48
.beads/formulas/security-audit.formula.yaml
Normal file
@@ -0,0 +1,48 @@
|
|||||||
|
# security-audit.formula.yaml
|
||||||
|
# AOP aspect for security scanning at implementation boundaries
|
||||||
|
|
||||||
|
formula: security-audit
|
||||||
|
type: aspect
|
||||||
|
description: |
|
||||||
|
Cross-cutting security concern. Applies security scanning
|
||||||
|
before and after implementation steps.
|
||||||
|
|
||||||
|
This is an ASPECT - it doesn't run standalone. Apply it
|
||||||
|
to other formulas using --with-aspect.
|
||||||
|
version: 1
|
||||||
|
|
||||||
|
pointcuts:
|
||||||
|
- glob: "*.implement"
|
||||||
|
- glob: "*.submit"
|
||||||
|
|
||||||
|
advice:
|
||||||
|
around:
|
||||||
|
before:
|
||||||
|
- id: security-prescan
|
||||||
|
description: |
|
||||||
|
Pre-implementation security check.
|
||||||
|
|
||||||
|
- Review for secrets/credentials in scope
|
||||||
|
- Check dependencies for known vulnerabilities
|
||||||
|
- Verify security requirements are understood
|
||||||
|
args:
|
||||||
|
target: "{step.id}"
|
||||||
|
|
||||||
|
after:
|
||||||
|
- id: security-postscan
|
||||||
|
description: |
|
||||||
|
Post-implementation security scan.
|
||||||
|
|
||||||
|
- Scan new code for vulnerabilities (SAST)
|
||||||
|
- Check for hardcoded secrets
|
||||||
|
- Verify auth/authz patterns
|
||||||
|
- Review for OWASP Top 10 issues
|
||||||
|
args:
|
||||||
|
target: "{step.id}"
|
||||||
|
output:
|
||||||
|
approved: boolean
|
||||||
|
findings: list
|
||||||
|
|
||||||
|
- gate:
|
||||||
|
condition: "security-postscan.output.approved == true"
|
||||||
|
message: "Security approval required before proceeding"
|
||||||
66
.beads/formulas/shiny-enterprise.formula.yaml
Normal file
66
.beads/formulas/shiny-enterprise.formula.yaml
Normal file
@@ -0,0 +1,66 @@
|
|||||||
|
# shiny-enterprise.formula.yaml
|
||||||
|
# Full enterprise engineering workflow with all the bells and whistles
|
||||||
|
|
||||||
|
formula: shiny-enterprise
|
||||||
|
extends: shiny
|
||||||
|
description: |
|
||||||
|
Enterprise-grade engineering workflow.
|
||||||
|
|
||||||
|
Builds on Shiny with:
|
||||||
|
- Rule of Five on implementation (5x refinement)
|
||||||
|
- Security scanning (pre and post)
|
||||||
|
- Performance testing branch
|
||||||
|
- Review loop until approved
|
||||||
|
- Full logging
|
||||||
|
|
||||||
|
Cook this to get a ~30 step proto ready for serious work.
|
||||||
|
version: 1
|
||||||
|
|
||||||
|
compose:
|
||||||
|
# Apply Rule of Five to the implement step
|
||||||
|
# This expands implement → 5 steps: draft, refine-1..4
|
||||||
|
- expand:
|
||||||
|
target: implement
|
||||||
|
with: rule-of-five
|
||||||
|
|
||||||
|
# Apply security aspect to all implementation steps
|
||||||
|
# Adds security-prescan before and security-postscan after
|
||||||
|
- aspect:
|
||||||
|
pointcut: "implement.*"
|
||||||
|
with: security-audit
|
||||||
|
|
||||||
|
# Gate on security approval before submit
|
||||||
|
- gate:
|
||||||
|
before: submit
|
||||||
|
condition: "security-postscan.approved == true"
|
||||||
|
message: "Cannot submit without security approval"
|
||||||
|
|
||||||
|
# Parallel performance testing branch
|
||||||
|
# These run in parallel after implementation, before review
|
||||||
|
- branch:
|
||||||
|
from: implement.refine-4
|
||||||
|
steps:
|
||||||
|
- id: perf-test
|
||||||
|
description: Run performance benchmarks
|
||||||
|
- id: load-test
|
||||||
|
description: Run load/stress tests
|
||||||
|
- id: chaos-test
|
||||||
|
description: Run chaos engineering tests (fault injection)
|
||||||
|
join: review
|
||||||
|
|
||||||
|
# Loop review until approved (max 3 attempts)
|
||||||
|
- loop:
|
||||||
|
step: review
|
||||||
|
until: "review.output.approved == true"
|
||||||
|
max: 3
|
||||||
|
on-max: escalate
|
||||||
|
|
||||||
|
# Logging on all steps (AOP-style advice)
|
||||||
|
- advice:
|
||||||
|
target: "*"
|
||||||
|
before:
|
||||||
|
- id: log-start
|
||||||
|
description: "Log: Starting {step.id}"
|
||||||
|
after:
|
||||||
|
- id: log-end
|
||||||
|
description: "Log: Completed {step.id} with status {step.status}"
|
||||||
67
.beads/formulas/shiny.formula.yaml
Normal file
67
.beads/formulas/shiny.formula.yaml
Normal file
@@ -0,0 +1,67 @@
|
|||||||
|
# shiny.formula.yaml
|
||||||
|
# Engineer in a Box - the canonical right way to do engineering
|
||||||
|
# Named for Mad Max: "Shiny and chrome!"
|
||||||
|
|
||||||
|
formula: shiny
|
||||||
|
description: |
|
||||||
|
The canonical engineering workflow. Design before you code.
|
||||||
|
Review before you ship. Test before you submit.
|
||||||
|
|
||||||
|
This is what "doing it right" looks like.
|
||||||
|
version: 1
|
||||||
|
|
||||||
|
vars:
|
||||||
|
feature: "{{feature}}" # What you're building
|
||||||
|
assignee: "{{assignee}}" # Who's doing the work
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- id: design
|
||||||
|
description: |
|
||||||
|
Think carefully about architecture before writing code.
|
||||||
|
|
||||||
|
Consider:
|
||||||
|
- How does this fit into the existing system?
|
||||||
|
- What are the edge cases?
|
||||||
|
- What could go wrong?
|
||||||
|
- Is there a simpler approach?
|
||||||
|
|
||||||
|
Output a brief design doc or notes.
|
||||||
|
|
||||||
|
- id: implement
|
||||||
|
description: |
|
||||||
|
Write the code for {{feature}}.
|
||||||
|
|
||||||
|
Follow the design. Keep it simple. Don't gold-plate.
|
||||||
|
Write code that's easy to review.
|
||||||
|
needs: [design]
|
||||||
|
|
||||||
|
- id: review
|
||||||
|
description: |
|
||||||
|
Review the implementation.
|
||||||
|
|
||||||
|
Check for:
|
||||||
|
- Does it match the design?
|
||||||
|
- Are there obvious bugs?
|
||||||
|
- Is it readable and maintainable?
|
||||||
|
- Are there security concerns?
|
||||||
|
needs: [implement]
|
||||||
|
|
||||||
|
- id: test
|
||||||
|
description: |
|
||||||
|
Write and run tests.
|
||||||
|
|
||||||
|
- Unit tests for new code
|
||||||
|
- Integration tests if needed
|
||||||
|
- Run the full test suite
|
||||||
|
- Fix any regressions
|
||||||
|
needs: [review]
|
||||||
|
|
||||||
|
- id: submit
|
||||||
|
description: |
|
||||||
|
Submit for merge.
|
||||||
|
|
||||||
|
- Final check: git status, git diff
|
||||||
|
- Commit with clear message
|
||||||
|
- Push and create PR (or merge directly if crew)
|
||||||
|
- Notify relevant parties
|
||||||
|
needs: [test]
|
||||||
@@ -18,6 +18,124 @@ Molecules = Graph Algebra (mechanical, gt executes)
|
|||||||
Steps = AI Cognition (agent provides)
|
Steps = AI Cognition (agent provides)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Formulas and Cooking
|
||||||
|
|
||||||
|
> *"Let's cook."* - Walter White
|
||||||
|
|
||||||
|
The molecule algebra lives above molecular chemistry. **Formulas** are the
|
||||||
|
source code; **cooking** is the process that produces executable protos.
|
||||||
|
|
||||||
|
### The Four-Tier Model
|
||||||
|
|
||||||
|
```
|
||||||
|
Formula (.formula.yaml) ← "The secret formula" (source code)
|
||||||
|
↓ cook ← "Let's cook" (pre-expand, flatten)
|
||||||
|
Proto (frozen in beads) ← "Pure product" (compiled, flat graph)
|
||||||
|
↓ pour/wisp ← Instantiate
|
||||||
|
Mol/Wisp (running) ← The work flowing
|
||||||
|
```
|
||||||
|
|
||||||
|
| Tier | Name | Format | Nature |
|
||||||
|
|------|------|--------|--------|
|
||||||
|
| Source | **Formula** | YAML | Composable, has macros/aspects |
|
||||||
|
| Compiled | **Proto** | Beads issue | Frozen, flat graph, fast instantiation |
|
||||||
|
| Running | **Mol/Wisp** | Beads issue | Active, flowing work |
|
||||||
|
|
||||||
|
### Why Cook?
|
||||||
|
|
||||||
|
Cooking **pre-expands** all composition at "compile time":
|
||||||
|
- Macros (Rule of Five) expand to flat steps
|
||||||
|
- Aspects apply to matching pointcuts
|
||||||
|
- Branches and gates wire up
|
||||||
|
- Result: pure step graph with no interpretation needed
|
||||||
|
|
||||||
|
Instantiation then becomes pure **copy + variable substitution**. Fast, mechanical,
|
||||||
|
deterministic.
|
||||||
|
|
||||||
|
### Formula Format
|
||||||
|
|
||||||
|
Formulas are YAML files with `.formula.yaml` extension:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# shiny.formula.yaml
|
||||||
|
formula: shiny
|
||||||
|
description: Engineer in a Box - 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]
|
||||||
|
```
|
||||||
|
|
||||||
|
Formulas with composition:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# shiny-enterprise.formula.yaml
|
||||||
|
formula: shiny-enterprise
|
||||||
|
extends: shiny
|
||||||
|
version: 1
|
||||||
|
|
||||||
|
compose:
|
||||||
|
- expand:
|
||||||
|
target: implement
|
||||||
|
with: rule-of-five
|
||||||
|
- aspect:
|
||||||
|
pointcut: "implement.*"
|
||||||
|
with: security-audit
|
||||||
|
- gate:
|
||||||
|
before: submit
|
||||||
|
condition: "security-postscan.approved"
|
||||||
|
```
|
||||||
|
|
||||||
|
### CLI
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Cook a formula into a proto
|
||||||
|
bd cook shiny-enterprise.formula.yaml
|
||||||
|
# "Cooking shiny-enterprise..."
|
||||||
|
# "✓ Cooked proto: shiny-enterprise (30 steps)"
|
||||||
|
|
||||||
|
# Preview without saving
|
||||||
|
bd cook shiny-enterprise.formula.yaml --dry-run
|
||||||
|
|
||||||
|
# List available formulas
|
||||||
|
bd formula list
|
||||||
|
|
||||||
|
# Show formula details
|
||||||
|
bd formula show rule-of-five
|
||||||
|
|
||||||
|
# Instantiate the cooked proto
|
||||||
|
bd pour shiny-enterprise --var feature="auth"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Formula Storage
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.beads/formulas/ # User formulas
|
||||||
|
~/gt/.beads/formulas/ # Town formulas
|
||||||
|
.beads/formulas/ # Project formulas
|
||||||
|
```
|
||||||
|
|
||||||
|
### Breaking Bad × Mad Max
|
||||||
|
|
||||||
|
The naming spans both universes:
|
||||||
|
- **Formula** = the chemistry, the secret (Breaking Bad, mad scientist)
|
||||||
|
- **Cook** = the process, the craft (Breaking Bad iconic)
|
||||||
|
- **Proto** = the pure product, crystallized (the "blue sky")
|
||||||
|
- Both work in Mad Max (fuel formulas, cooking up schemes)
|
||||||
|
|
||||||
|
Heisenberg's formula is worthless without the cook. The cook is where purity
|
||||||
|
comes from. Same here: formulas define the algebra, but cooking produces the
|
||||||
|
pure proto.
|
||||||
|
|
||||||
## The Phases of Matter
|
## The Phases of Matter
|
||||||
|
|
||||||
Work in Gas Town exists in three phases:
|
Work in Gas Town exists in three phases:
|
||||||
@@ -528,21 +646,28 @@ This keeps evaluation decidable and safe for mechanical execution.
|
|||||||
│ MOL MALL (Marketplace) │
|
│ MOL MALL (Marketplace) │
|
||||||
│ ┌─────────┐ ┌─────────┐ ┌───────────┐ │
|
│ ┌─────────┐ ┌─────────┐ ┌───────────┐ │
|
||||||
│ │ Shiny │ │ Rule of │ │ Security │ │
|
│ │ Shiny │ │ Rule of │ │ Security │ │
|
||||||
│ │ │ │ Five │ │ Aspect │ │
|
│ │ Formula │ │ Five │ │ Aspect │ │
|
||||||
│ └─────────┘ └─────────┘ └───────────┘ │
|
│ └─────────┘ └─────────┘ └───────────┘ │
|
||||||
│ ┌─────────┐ ┌─────────┐ ┌───────────┐ │
|
│ ┌─────────┐ ┌─────────┐ ┌───────────┐ │
|
||||||
│ │Planning │ │ Release │ │ Company │ │
|
│ │Planning │ │ Release │ │ Company │ │
|
||||||
│ │ Form │ │ Cycle │ │ Onboard │ │
|
│ │ Formula │ │ Formula │ │ Onboard │ │
|
||||||
│ └─────────┘ └─────────┘ └───────────┘ │
|
│ └─────────┘ └─────────┘ └───────────┘ │
|
||||||
└─────────────────────────────────────────┘
|
└─────────────────────────────────────────┘
|
||||||
│
|
│
|
||||||
▼ compose
|
▼ compose
|
||||||
┌─────────────────────────────────────────┐
|
┌─────────────────────────────────────────┐
|
||||||
│ YOUR ORGANIZATION WORKFLOW │
|
│ YOUR ORGANIZATION FORMULA │
|
||||||
│ │
|
│ │
|
||||||
│ Planning + Shiny + R5 + Security + │
|
│ Planning + Shiny + R5 + Security + │
|
||||||
│ Release + Onboarding = Company in Box │
|
│ Release + Onboarding = Company in Box │
|
||||||
│ │
|
│ │
|
||||||
|
└─────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼ cook ("Let's cook")
|
||||||
|
┌─────────────────────────────────────────┐
|
||||||
|
│ PURE PROTO │
|
||||||
|
│ Pre-expanded, flat graph, 99.1% pure │
|
||||||
|
│ No macros, no aspects, just steps │
|
||||||
└─────────────────────────────────────────┘
|
└─────────────────────────────────────────┘
|
||||||
│
|
│
|
||||||
▼ pour/wisp
|
▼ pour/wisp
|
||||||
@@ -558,4 +683,4 @@ From issues in git → work composition algebra → companies in a box.
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
*The algebra is the interface. The ledger is the truth. The work gets done.*
|
*The formula is the secret. The cook is the craft. The work gets done.*
|
||||||
|
|||||||
Reference in New Issue
Block a user