From 74430a10196b6bfaad47dacf6e2c187060b71bab Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 23 Dec 2025 18:23:36 -0800 Subject: [PATCH] refactor: formulas use JSON instead of YAML (gt-8tmz) JSON for consistency with beads (issues.jsonl, molecules.jsonl). Agents create/manage formulas; humans use visualizers. - Simpler parsing (Go built-in JSON) - No YAML gotchas - Agents generate JSON flawlessly --- .beads/formulas/rule-of-five.formula.json | 32 +++++++++ .beads/formulas/rule-of-five.formula.yaml | 61 ----------------- .beads/formulas/security-audit.formula.json | 35 ++++++++++ .beads/formulas/security-audit.formula.yaml | 48 ------------- .beads/formulas/shiny-enterprise.formula.json | 53 +++++++++++++++ .beads/formulas/shiny-enterprise.formula.yaml | 66 ------------------ .beads/formulas/shiny.formula.json | 35 ++++++++++ .beads/formulas/shiny.formula.yaml | 67 ------------------- docs/molecule-algebra.md | 60 +++++++---------- 9 files changed, 181 insertions(+), 276 deletions(-) create mode 100644 .beads/formulas/rule-of-five.formula.json delete mode 100644 .beads/formulas/rule-of-five.formula.yaml create mode 100644 .beads/formulas/security-audit.formula.json delete mode 100644 .beads/formulas/security-audit.formula.yaml create mode 100644 .beads/formulas/shiny-enterprise.formula.json delete mode 100644 .beads/formulas/shiny-enterprise.formula.yaml create mode 100644 .beads/formulas/shiny.formula.json delete mode 100644 .beads/formulas/shiny.formula.yaml diff --git a/.beads/formulas/rule-of-five.formula.json b/.beads/formulas/rule-of-five.formula.json new file mode 100644 index 00000000..240500b8 --- /dev/null +++ b/.beads/formulas/rule-of-five.formula.json @@ -0,0 +1,32 @@ +{ + "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"] + } + ] +} diff --git a/.beads/formulas/rule-of-five.formula.yaml b/.beads/formulas/rule-of-five.formula.yaml deleted file mode 100644 index 1b793fe9..00000000 --- a/.beads/formulas/rule-of-five.formula.yaml +++ /dev/null @@ -1,61 +0,0 @@ -# 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"] diff --git a/.beads/formulas/security-audit.formula.json b/.beads/formulas/security-audit.formula.json new file mode 100644 index 00000000..2a6c9194 --- /dev/null +++ b/.beads/formulas/security-audit.formula.json @@ -0,0 +1,35 @@ +{ + "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" + } + } + ] + } + } +} diff --git a/.beads/formulas/security-audit.formula.yaml b/.beads/formulas/security-audit.formula.yaml deleted file mode 100644 index a41618c7..00000000 --- a/.beads/formulas/security-audit.formula.yaml +++ /dev/null @@ -1,48 +0,0 @@ -# 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" diff --git a/.beads/formulas/shiny-enterprise.formula.json b/.beads/formulas/shiny-enterprise.formula.json new file mode 100644 index 00000000..4c1a5dd7 --- /dev/null +++ b/.beads/formulas/shiny-enterprise.formula.json @@ -0,0 +1,53 @@ +{ + "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}"} + } + } + ] +} diff --git a/.beads/formulas/shiny-enterprise.formula.yaml b/.beads/formulas/shiny-enterprise.formula.yaml deleted file mode 100644 index 20d035ed..00000000 --- a/.beads/formulas/shiny-enterprise.formula.yaml +++ /dev/null @@ -1,66 +0,0 @@ -# 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}" diff --git a/.beads/formulas/shiny.formula.json b/.beads/formulas/shiny.formula.json new file mode 100644 index 00000000..6e9ae53b --- /dev/null +++ b/.beads/formulas/shiny.formula.json @@ -0,0 +1,35 @@ +{ + "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"] + } + ] +} diff --git a/.beads/formulas/shiny.formula.yaml b/.beads/formulas/shiny.formula.yaml deleted file mode 100644 index 823d6ecf..00000000 --- a/.beads/formulas/shiny.formula.yaml +++ /dev/null @@ -1,67 +0,0 @@ -# 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] diff --git a/docs/molecule-algebra.md b/docs/molecule-algebra.md index 374ecc9d..3ce17592 100644 --- a/docs/molecule-algebra.md +++ b/docs/molecule-algebra.md @@ -54,45 +54,37 @@ deterministic. ### Formula Format -Formulas are YAML files with `.formula.yaml` extension: +Formulas are JSON files with `.formula.json` extension. JSON for consistency +with beads (agents create/manage these; humans use visualizers): -```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] +```json +{ + "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" +```json +{ + "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