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.
| 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.
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.
- 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-verifyJSON evidence interface
| 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.
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
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
- Strategy and architecture decisions
- Ambiguity resolution
- Novel reasoning
- Candidate generation
- Judgment calls where deterministic evidence is insufficient
- Structural facts
- Dependency relationships
- Repeatable validation
- Property exploration
- Constraint checking
- Test-quality measurement
- Evidence recording
- Routing where rules are sufficient
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.
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_alland 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.
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.
git clone https://github.com/aspire488/Universal-Engineering-Augmentation.git
cd Universal-Engineering-Augmentation
pip install -e ".[dev]"Requirements: Python 3.10+ and Git.
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 standardpython scripts/verify_all.py
pytest tests/ -vCI validates Python 3.10, 3.11, and 3.12. Dependabot tracks Python and GitHub Actions dependencies weekly.
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.
- 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
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.
Issues and pull requests are welcome, especially improvements that increase engineering capability without coupling the core to a single coding agent. See CONTRIBUTING.md.
- 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.
MIT — see LICENSE.