OpenEngine

Compile unstructured human intent into verified software.

OpenEngine is a CLI tool that takes a natural-language description of what you want built and produces a working, tested, reviewed codebase. It runs a 16-node pipeline that drafts a specification, generates code, writes tests, repairs failures, conducts a multi-role review, and produces final documentation -- all with deterministic gate checks between each stage.

Quick Start

# Install
npm install -g openengine

# Set your LLM provider key
export ANTHROPIC_API_KEY="sk-ant-..."

# Compile an intent into software
oe compile "Build a CLI tool that converts CSV files to JSON"

# Check progress
oe status

# View generated artifacts
oe inspect --all

The session directory defaults to .oe-session/ in the current working directory. Generated source code is written to .oe-session/output/.

How It Works

Pipeline

OpenEngine executes a directed graph of 16 nodes. Each node performs a specific task (parse intent, generate code, run tests, etc.) and must pass a deterministic gate before the pipeline advances.

intake
  --> constraints_gate --> spec_draft --> spec_review
  --> user_approval --> plan_graph
  --> scaffold --> codegen <--> unit_test <--> repair
  --> integration_test --> conference
  --> link --> final_judge --> done

Nodes that fail their gate are routed to repair, which fixes the issue and re-enters the test loop. The repair loop is budget-capped (max_repair_cycles: 5 per module). Spec-level issues route back to spec_draft for revision (max_revisions: 3).

See docs/pipeline.md for the full node and gate reference.

Three-Layer Architecture

The pipeline reads and writes three persistent YAML artifacts in .oe/:

• Spec IR -- Requirements, architecture (modules, dependencies, constraints), work plan, tech stack. The single source of truth for what is being built.
• Issue Ledger -- Issues raised during review (blocker/major/minor), with lifecycle tracking (open -> confirmed -> fixed/closed) and verification hooks.
• Evidence -- Deterministic proof entries linking tool output (compilation, tests, hooks) to spec claims. Supports staleness tracking after repairs.

See docs/architecture.md for schemas and APIs.

Conference Review

After integration tests pass, a multi-role conference reviews the codebase:

1. Four reviewer roles (Architect, API Designer, Security, Performance) analyze the code in parallel
2. Issues are merged with Jaccard similarity dedup (threshold >= 0.6)
3. A judge deliberates on each issue, executing verification hooks
4. Hook results override judge opinions (test pass -> close, test fail -> confirm)
5. Confirmed blockers route back to repair

See docs/conference.md for the full review protocol.

CLI Commands

| Command | Description | |---------|-------------| | oe compile <intent> | Compile intent into working software | | oe status | Show session progress (current node, step count) | | oe resume | Continue an interrupted or failed session | | oe inspect | View session artifacts (spec, ledger, evidence, history) | | oe validate | Check trace integrity (ref resolution, evidence links) |

All commands accept -o <dir> to specify the session directory (default: .oe-session).

See docs/cli.md for the full flag reference.

Session Directory Layout

.oe-session/
  .oe/
    state.yaml            # Current node, step count, status
    spec-ir.yaml          # Specification IR
    issue-ledger.yaml     # Issues raised during review
    evidence/             # Evidence entries (one YAML per entry)
    transitions.jsonl     # State transition log
    snapshots/            # Access guard snapshots
  output/                 # Generated source code and docs
    src/
    tests/
    package.json
    README.md
    ARCHITECTURE.md

Providers

OpenEngine supports two LLM providers:

| Provider | Default model | Environment variable | |----------|--------------|---------------------| | Anthropic (default) | Claude Sonnet 4.5 | ANTHROPIC_API_KEY | | OpenAI | GPT-4o | OPENAI_API_KEY |

Use --provider openai to switch providers. Use --model <id> to override the default model.

See docs/providers.md for structured output strategy and model profiles.

Documentation

• Architecture -- Three-layer data model, schemas, state machine, events
• Pipeline -- Node reference, gate types, routing, termination
• CLI Reference -- All commands, flags, environment variables
• Conference -- Multi-role review, hooks, merge, overrides
• Security -- Sandbox enforcement, access guard, sensitive path denylist
• Providers -- LLM abstraction, structured output, model config
• Contributing -- Dev setup, testing, adding nodes/gates/roles

License

MIT -- Saleh Mostafa