Logic Specification Framework

A language-agnostic standard for extracting pure logic from implementations into logic.yaml.

Quick Start

# logic.yaml
meta:
  spec_version: "1.0"
  name: my-module
  version: "1.0.0"

inputs:
  - name: data
    type: string

outputs:
  - name: result
    type: string

logic:
  - id: process
    type: transform
    input: data
    output: result
    algorithm: |
      1. Transform input
      2. Return output

Why

| Problem | Solution | |----------|----------| | AI agents drown in implementation details | Clean spec they can parse | | Logic locked to one language | Portable across any runtime | | Tests scattered in codebase | Assertions in the spec | | State machines implicit | Explicit state definitions | | Errors handled inconsistently | Declared failure modes |

Documentation

| File | Purpose | |------|---------| | skill.md | Skill definition and workflow | | SPEC.md | Full specification | | REFERENCE.md | Quick reference card | | schema.json | JSON Schema for validation | | examples/ | Example logic.yaml files |

Examples

| Example | Demonstrates | |---------|--------------| | minimal.yaml | Basic transform | | state-machine.yaml | State machine | | smart-glass-supervisor.yaml | Full complex system |

Core Principles

┌────────────────────────┬─────────────────────────────────────────┐
│      Principle         │                   Why                   │
├────────────────────────┼─────────────────────────────────────────┤
│ I/O at edges           │ Logic blocks are pure                  │
│ Algorithm as text      │ Human-readable, language-agnostic      │
│ Types explicit         │ Schema validation                      │
│ State first-class      │ State machines are explicit            │
│ Constraints separate   │ Performance not buried in code         │
│ Failures declared      │ Errors part of the contract            │
│ Composable blocks      │ Logic chains, not monoliths            │
│ Versioned              │ Spec can evolve without breaking       │
│ Observable             │ Metrics/logging hooks built-in         │
│ Testable               │ Assertions in spec                     │
└────────────────────────┴─────────────────────────────────────────┘

Sections

| Section | Required | Purpose | |---------|----------|---------| | meta | ✅ | Identity, version | | inputs | ✅ | Entry points | | outputs | ✅ | Exit points | | types | ❌ | Custom type definitions | | logic | ✅ | Pure function blocks | | state | ❌ | State machine | | flows | ❌ | Logic composition | | failures | ❌ | Error handling | | constraints | ❌ | Performance bounds | | dependencies | ❌ | External services | | observability | ❌ | Metrics/logging | | tests | ❌ | Built-in assertions |

Validate

# Using ajv-cli
bunx ajv-cli validate -s schema.json -d logic.yaml

# Or using yajsv
bunx yajsv -s schema.json logic.yaml

Use with AI

Extract from code:

"Extract logic.yaml from this authentication module"

Generate from spec:

"Generate TypeScript from this logic.yaml"

Validate spec:

"Validate this logic.yaml against the spec"

License

MIT