Skip to content

About

Universal, agent-neutral software engineering augmentation infrastructure for coding agents, providing deterministic code intelligence, verification, specialized analysis, memory, orchestration, and reusable engineering capabilities.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Universal Engineering Augmentation — Turn agent output into evidence you can verify.

CI Status: public alpha, v0.1.0, no tagged release yet Python 3.10+ MIT license

Universal Engineering Augmentation

A deterministic engineering layer for coding agents.

UEA moves repeatable software-engineering work out of probabilistic reasoning and into tools that can inspect, verify, measure, and preserve evidence. It works beside OpenCode, Claude Code, Codex, and other agents without binding the core to one host.

Agents propose. Deterministic systems verify. Evidence records what actually happened.

Capability map

Engineering capability What UEA establishes
Code intelligence Tree-sitter structure, symbols, and parsing
Impact analysis Dependency graphs, affected symbols, blast radius
Verification Tiered checks from minimal through security and full
Test quality Property exploration and mutation testing
Formal methods SAT/SMT constraints through Z3
Candidate isolation Parallel implementations in Git worktrees
Routing Deterministic-first specialist selection
Evidence Provenance, event records, and reproducible results
Analytics DuckDB queries over engineering events
Integration Agent adapters and stable JSON CLI

Project status: Public alpha · v0.1.0 · deterministic-first routing with optional Laya System-1 fallback.


Why this exists

Coding agents are strongest when they reason about novel problems. They are a poor place to repeatedly re-derive facts that deterministic tools can establish faster and more reliably.

Universal Engineering Augmentation provides reusable engineering capabilities that can sit beside OpenCode, Claude Code, Codex, or other coding agents without making the core dependent on any one agent.

Core capabilities

  • Structural code analysis — tree-sitter parsing and symbol extraction
  • Dependency & impact analysis — import graphs, symbol impact, blast radius
  • Tiered verification — minimal → standard → strict → security → full
  • Property testing — Hypothesis-driven edge-case exploration
  • Mutation testing — measure whether tests actually detect faults
  • Formal verification — SAT/SMT constraints with Z3
  • Candidate isolation — Git worktrees for parallel implementations
  • Specialist routing — deterministic-first task routing
  • Deterministic scoring — repeatable candidate/evidence evaluation
  • Provenance — evidence lineage and audit trails
  • Event logging — structured SQLite records
  • Analytics — DuckDB queries over engineering events
  • Project detection — select capability profiles from repository structure
  • Agent adapters — Claude Code and Codex integration surfaces
  • Stable CLI — uea-verify JSON evidence interface

Structural language capability matrix

Language File extensions Extracted structure
Python .py Functions, classes, imports
JavaScript .js, .jsx Parsing supported; extraction follows grammar node coverage
TypeScript .ts, .tsx Parsing supported; extraction follows grammar node coverage
JSON .json Syntax tree and node counts
Go .go Functions, methods, structs/interfaces, imports
Rust .rs Functions, structs, enums, traits, use declarations

Unsupported extensions return an explicit error from parse_file; they are not silently treated as Python.

Architecture

Deterministic engineering pipeline

flowchart LR
    A[Coding Agent] --> B[UEA Router]
    B --> C[Code Intelligence]
    B --> D[Impact / Dependency Analysis]
    B --> E[Candidate Engine]
    B --> F[Verification]
    B --> G[Formal / Specialized Engines]
    C --> H[Evidence]
    D --> H
    E --> H
    F --> H
    G --> H
    H --> I[Result / Provenance]
    E <--> F
    K[KIO execution kernel] -. optional integration .-> B
Loading

UEA keeps the probabilistic boundary explicit: agents generate strategy and candidates; deterministic capabilities establish structure, dependencies, verification results, constraints, and provenance.

Coding Agent
(OpenCode / Claude Code / Codex / other)
        │
        ▼
┌──────────────────────────────────────┐
│ Universal Engineering Augmentation   │
├──────────────────────────────────────┤
│ Router + Specialist Registry         │
│ Code Intelligence                    │
│ Impact / Dependency Analysis         │
│ Candidate Engine + Worktrees         │
│ Verification + Testing               │
│ Formal / Specialized Engines         │
│ Provenance + Event Log               │
│ Analytics                            │
└──────────────────────────────────────┘
        │
        ▼
Evidence → Candidate → Verification → Result

What stays with the LLM

  • Strategy and architecture decisions
  • Ambiguity resolution
  • Novel reasoning
  • Candidate generation
  • Judgment calls where deterministic evidence is insufficient

What should be deterministic

  • Structural facts
  • Dependency relationships
  • Repeatable validation
  • Property exploration
  • Constraint checking
  • Test-quality measurement
  • Evidence recording
  • Routing where rules are sufficient

Deterministic-first routing with Laya fallback

Routing is deterministic-first: keyword classification runs first, and only when it returns UNKNOWN does core/laya_router.py consult the local Laya model (UEA_LAYA_ENABLED, default false, lazy single checkpoint). A Laya label is validated against the task-type set before use and then feeds the exact same capability/specialist/verification stack — it never bypasses validation, the harness, or permissions. No Laya install, a disabled flag, or any model failure leaves routing exactly as the deterministic classifier produced it.

Current verified state

The current main baseline includes deterministic-first specialist routing with an optional local Laya System-1 fallback for UNKNOWN classifications. The integration is complete and verified; UEA remains public alpha rather than a frozen project.

  • Deterministic classification always runs first.
  • Laya is consulted only when deterministic routing returns UNKNOWN.
  • Labels are validated against the existing task-type allow-list.
  • The validated result feeds the existing capability, specialist, verification, and permission stack.
  • Laya is lazy-loaded, uses one checkpoint, and can be disabled with UEA_LAYA_ENABLED=false.
  • Missing dependencies or model failures fail soft and preserve deterministic routing.
  • The final Laya integration batch is verified at 62/62 tests passing, with verify_all and compile checks clean.
  • No Laya dependency is required for the base UEA install or CI path.
  • The fallback is advisory only: invalid labels, missing dependencies, or model failures preserve deterministic routing.

This does not turn UEA into an autonomous agent. UEA remains an agent-neutral engineering augmentation layer whose deterministic capabilities establish evidence and verification.

Agent-neutral design

The core package contains no dependency on a specific coding agent.

Reference integration: OpenCode

First-class integration surfaces: Claude Code · Codex · generic CLI

Adapters live outside core/. They translate host-agent lifecycle/configuration into deterministic UEA calls and structured evidence.

See docs/ADAPTER_INTEGRATION.md and docs/ADAPTER_CLI_GUIDE.md.

Installation

git clone https://github.com/aspire488/Universal-Engineering-Augmentation.git
cd Universal-Engineering-Augmentation
pip install -e ".[dev]"

Requirements: Python 3.10+ and Git.

Quick start

from core.tree_sitter_engine import parse_file
from core.impact_model import build_import_graph
from core.verification import run_verification

result = parse_file("my_script.py")
graph = build_import_graph("src/")
report = run_verification(".", level="standard")

For agent integrations or CI, use the stable JSON CLI:

uea-verify . --level standard

Verification

python scripts/verify_all.py
pytest tests/ -v

CI validates Python 3.10, 3.11, and 3.12. Dependabot tracks Python and GitHub Actions dependencies weekly.

Benchmarks

Current measurements demonstrate deterministic capability and latency on a real-world Python codebase:

Operation Time
Tree-sitter parse (10 files) 176ms
Impact analysis (1 file) 24ms
Event log (1 event) 16ms
Candidate proposal (2 candidates) 1.1s
Property test 253ms
DuckDB query 77ms

LLM token/call reduction: not currently measured. The project does not claim token savings without instrumentation that can reproduce them.

The reproducible benchmark harness records machine-readable deterministic measurements while explicitly reporting unavailable host-agent telemetry.

Project maturity roadmap

  • Canonical Python packaging
  • Multi-version CI
  • Unit and integration tests
  • Security and contribution documentation
  • Agent-neutral core boundary
  • Deterministic specialist routing
  • Evidence provenance
  • Reproducible public benchmark harness
  • Dependency update automation
  • Automated tagged release pipeline (built; no release has been tagged yet)
  • Claude Code adapter
  • Codex adapter (AGENTS.md instructions plus the CLI; no code hook)
  • Stable JSON verification CLI
  • Broader language grammars
  • External open-source contribution track

Release process

No release has been tagged yet: v0.1.0 exists in core.__version__, pyproject.toml and the changelog only. Releases will use vX.Y.Z tags. The release workflow verifies that the tag matches core.__version__, validates the corresponding CHANGELOG.md entry, runs verification and tests, builds distributions, and publishes GitHub release notes from the changelog.

See CHANGELOG.md and CONTRIBUTING.md for the maintainer workflow.

Contributing

Issues and pull requests are welcome, especially improvements that increase engineering capability without coupling the core to a single coding agent. See CONTRIBUTING.md.

Security

  • No secrets or credentials are stored in the repository
  • Runtime databases and worktrees are excluded from version control
  • Event logs are metadata-oriented and should not contain secrets

See SECURITY.md for vulnerability reporting.

License

MIT — see LICENSE.

About

Universal, agent-neutral software engineering augmentation infrastructure for coding agents, providing deterministic code intelligence, verification, specialized analysis, memory, orchestration, and reusable engineering capabilities.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages