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

refactor: formulas use YAML instead of JSON (gt-8tmz)

Browse Source 
- Convert .formula.json files to .formula.yaml
- Update molecule-algebra.md to specify YAML format
- Update molecular-chemistry.md proto examples
- Add Safety Constraints section: cycle detection, aspect
  self-matching prevention, max expansion depth, graceful degradation

🤖 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 18:48:43 -08:00
parent 74430a1019
commit 0a7630c263
10 changed files with 233 additions and 209 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.beads/formulas/rule-of-five.formula.json
View File

@@ -1,32 +0,0 @@
{
"formula": "rule-of-five",
"type": "expansion",
"description": "Jeffrey Emanuel's discovery: LLM agents produce best work through 4-5 iterative refinements. Breadth-first exploration, then editorial passes.",
"version": 1,
"template": [
{
"id": "{target}.draft",
"description": "Initial attempt at: {target.description}. Don't aim for perfection. Get the shape right. Breadth over depth."
},
{
"id": "{target}.refine-1",
"description": "First refinement pass. Focus: CORRECTNESS. Fix errors, bugs, mistakes. Is the logic sound?",
"needs": ["{target}.draft"]
},
{
"id": "{target}.refine-2",
"description": "Second refinement pass. Focus: CLARITY. Can someone else understand this? Simplify. Remove jargon.",
"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.",
"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"]
}
]
}

35
.beads/formulas/rule-of-five.formula.yaml Normal file
View File

@@ -0,0 +1,35 @@
formula: rule-of-five
type: expansion
description: >
Jeffrey Emanuel's discovery: LLM agents produce best work through 4-5
iterative refinements. Breadth-first exploration, then editorial passes.
version: 1
template:
- id: "{target}.draft"
description: >
Initial attempt at: {target.description}. Don't aim for perfection.
Get the shape right. Breadth over depth.
- id: "{target}.refine-1"
description: >
First refinement pass. Focus: CORRECTNESS. Fix errors, bugs, mistakes.
Is the logic sound?
needs: ["{target}.draft"]
- id: "{target}.refine-2"
description: >
Second refinement pass. Focus: CLARITY. Can someone else understand
this? Simplify. Remove jargon.
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.
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"]

35
.beads/formulas/security-audit.formula.json
View File

@@ -1,35 +0,0 @@
{
"formula": "security-audit",
"type": "aspect",
"description": "Cross-cutting security concern. Applies security scanning before and after implementation steps.",
"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.",
"args": {"target": "{step.id}"}
}
],
"after": [
{
"id": "security-postscan",
"description": "Post-implementation security scan. Scan new code for vulnerabilities (SAST). Check for hardcoded secrets. 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"
}
}
]
}
}
}

31
.beads/formulas/security-audit.formula.yaml Normal file
View File

@@ -0,0 +1,31 @@
formula: security-audit
type: aspect
description: >
Cross-cutting security concern. Applies security scanning before and
after implementation steps.
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.
args:
target: "{step.id}"
after:
- id: security-postscan
description: >
Post-implementation security scan. Scan new code for vulnerabilities
(SAST). Check for hardcoded secrets. 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

53
.beads/formulas/shiny-enterprise.formula.json
View File

@@ -1,53 +0,0 @@
{
"formula": "shiny-enterprise",
"extends": "shiny",
"description": "Enterprise-grade engineering workflow. Shiny + Rule of Five + Security + Performance Testing + Review Loop.",
"version": 1,
"compose": [
{
"expand": {
"target": "implement",
"with": "rule-of-five"
}
},
{
"aspect": {
"pointcut": "implement.*",
"with": "security-audit"
}
},
{
"gate": {
"before": "submit",
"condition": "security-postscan.approved == true",
"message": "Cannot submit without security approval"
}
},
{
"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"}
],
"join": "review"
}
},
{
"loop": {
"step": "review",
"until": "review.output.approved == true",
"max": 3,
"on-max": "escalate"
}
},
{
"advice": {
"target": "*",
"before": {"id": "log-start", "description": "Log: Starting {step.id}"},
"after": {"id": "log-end", "description": "Log: Completed {step.id}"}
}
}
]
}

45
.beads/formulas/shiny-enterprise.formula.yaml Normal file
View File

@@ -0,0 +1,45 @@
formula: shiny-enterprise
extends: shiny
description: >
Enterprise-grade engineering workflow. Shiny + Rule of Five + Security +
Performance Testing + Review Loop.
version: 1
compose:
- expand:
target: implement
with: rule-of-five
- aspect:
pointcut: "implement.*"
with: security-audit
- gate:
before: submit
condition: "security-postscan.approved == true"
message: Cannot submit without security approval
- 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
join: review
- loop:
step: review
until: "review.output.approved == true"
max: 3
on-max: escalate
- advice:
target: "*"
before:
id: log-start
description: "Log: Starting {step.id}"
after:
id: log-end
description: "Log: Completed {step.id}"

35
.beads/formulas/shiny.formula.json
View File

@@ -1,35 +0,0 @@
{
"formula": "shiny",
"description": "Engineer in a Box - the canonical right way. Design before you code. Review before you ship. Test before you submit.",
"version": 1,
"vars": {
"feature": "{{feature}}",
"assignee": "{{assignee}}"
},
"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?"
},
{
"id": "implement",
"description": "Write the code for {{feature}}. Follow the design. Keep it simple. Don't gold-plate.",
"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.",
"needs": ["test"]
}
]
}

39
.beads/formulas/shiny.formula.yaml Normal file
View File

@@ -0,0 +1,39 @@
formula: shiny
description: >
Engineer in a Box - the canonical right way. Design before you code.
Review before you ship. Test before you submit.
version: 1
vars:
feature: "{{feature}}"
assignee: "{{assignee}}"
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?
- id: implement
description: >
Write the code for {{feature}}. Follow the design. Keep it simple.
Don't gold-plate.
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.
needs: [test]

46
docs/molecular-chemistry.md
View File

@@ -40,37 +40,31 @@ Work in Gas Town exists in three phases, following the states of matter:
Protos or protomolecules are **frozen workflow patterns** - crystallized templates that Protos or protomolecules are **frozen workflow patterns** - crystallized templates that
encode reusable work structures. They're the "molds" from which instances are cast. encode reusable work structures. They're the "molds" from which instances are cast.
```markdown Protos are stored as beads issues with `labels: ["template"]` and structured step data:
## Molecule: engineer-in-box
Full workflow from design to merge.
## Step: design ```yaml
Think carefully about architecture. # Example: shiny.formula.yaml (source) → cooked proto (beads)
Needs: (none) formula: shiny
description: The canonical right way
## Step: implement version: 1
Write the code. steps:
Needs: design - id: design
description: Think carefully about architecture
## Step: review - id: implement
Perform initial code review. needs: [design]
Needs: implement - id: review
needs: [implement]
## Step: test - id: test
Write and run tests. needs: [review]
Needs: review - id: submit
needs: [test]
## Step: submit
Submit for merge.
Needs: test
``` ```
**Properties:** **Properties:**
- Considered immutable once defined (frozen), though editable - Considered immutable once cooked (frozen), though source formulas are editable
- Named (e.g., `mol-engineer-in-box`, `wisp-deacon-patrol`) - Named (e.g., `shiny`, `rule-of-five`)
- Can have any name, but convention says how they will materialize.
- Stored in permanent beads with `template` label - Stored in permanent beads with `template` label
- Can be composed into larger protos (compounds, polymers) - Can be composed into larger protos via formula algebra (extends, compose)
### Mol (Liquid Phase) ### Mol (Liquid Phase)

91
docs/molecule-algebra.md
View File

@@ -54,49 +54,54 @@ deterministic.
### Formula Format ### Formula Format
Formulas are JSON files with `.formula.json` extension. JSON for consistency Formulas are YAML files with `.formula.yaml` extension. YAML for human
with beads (agents create/manage these; humans use visualizers): readability (humans author these; agents cook them):
```json ```yaml
{ formula: shiny
"formula": "shiny", description: Engineer in a Box - the canonical right way
"description": "Engineer in a Box - the canonical right way", version: 1
"version": 1, steps:
"steps": [ - id: design
{"id": "design", "description": "Think carefully about architecture"}, description: Think carefully about architecture
{"id": "implement", "needs": ["design"]}, - id: implement
{"id": "review", "needs": ["implement"]}, needs: [design]
{"id": "test", "needs": ["review"]}, - id: review
{"id": "submit", "needs": ["test"]} needs: [implement]
] - id: test
} needs: [review]
- id: submit
needs: [test]
``` ```
Formulas with composition: Formulas with composition:
```json ```yaml
{ formula: shiny-enterprise
"formula": "shiny-enterprise", extends: shiny
"extends": "shiny", version: 1
"version": 1, compose:
"compose": [ - expand:
{"expand": {"target": "implement", "with": "rule-of-five"}}, target: implement
{"aspect": {"pointcut": "implement.*", "with": "security-audit"}}, with: rule-of-five
{"gate": {"before": "submit", "condition": "security-postscan.approved"}} - aspect:
] pointcut: "implement.*"
} with: security-audit
- gate:
before: submit
condition: "security-postscan.approved"
``` ```
### CLI ### CLI
```bash ```bash
# Cook a formula into a proto # Cook a formula into a proto
bd cook shiny-enterprise.formula.yaml bd cook shiny-enterprise
# "Cooking shiny-enterprise..." # "Cooking shiny-enterprise..."
# "✓ Cooked proto: shiny-enterprise (30 steps)" # "✓ Cooked proto: shiny-enterprise (30 steps)"
# Preview without saving # Preview without saving
bd cook shiny-enterprise.formula.yaml --dry-run bd cook shiny-enterprise --dry-run
# List available formulas # List available formulas
bd formula list bd formula list
@@ -621,6 +626,36 @@ The algebra is intentionally restricted:
This keeps evaluation decidable and safe for mechanical execution. This keeps evaluation decidable and safe for mechanical execution.
## Safety Constraints
The cooker enforces these constraints to prevent runaway expansion:
### Cycle Detection
Circular `extends` chains are detected and rejected:
```
A extends B extends C extends A → ERROR: cycle detected
```
### Aspect Self-Matching Prevention
Aspects only match *original* steps, not steps inserted by the same aspect.
Without this, a pointcut like `*.implement` that inserts `security-prescan`
could match its own insertion infinitely.
### Maximum Expansion Depth
Nested expansions are bounded (default: 5 levels). This allows massive work
generation while preventing runaway recursion. Configurable via:
```yaml
cooking:
max_expansion_depth: 5
```
### Graceful Degradation
Cooking errors produce warnings, not failures where possible. Philosophy:
get it working as well as possible, warn the human, continue. Invalid steps
may be annotated with error metadata rather than blocking the entire cook.
Errors are written to the Gas Town escalation channel for human review.
## What This Enables ## What This Enables
1. **Composition without AI**: gt compiles molecule algebra mechanically 1. **Composition without AI**: gt compiles molecule algebra mechanically