Universal Engineering Agent — open-source engineering-agent operating kernel

[MajidAsghariTabrizi]

What is this?

Universal Engineering Agent (UEA) is a standalone, open-source reference implementation of a 9-stage engineering-agent operating kernel. It is the smallest possible reusable shell that an LLM-driven coding agent can sit inside and still be production-safe.

npm install universal-engineering-agent-kit | GitHub | MIT | 31 self-tests | Node 18.17+

---

The problem it solves

Most engineering-agent prompts grow until they are unmaintainable. The author keeps adding "and also do X" until the system prompt is 4,000 tokens of tribal knowledge that nobody outside the author can re-use.

UEA takes the opposite direction: it is intentionally profile-agnostic. The product-specific knowledge (which languages, which deployment policy, which safety tier) lives in a profile, not in the kernel. The kernel owns only what every agent needs.

---

The 9 stages

#	Stage	What it does
1	inspect	Walk the workspace and compose a budgeted, ranked context bundle (not a whole-repo dump)
2	plan	Stage a Mission into a task graph with dependency edges
3	implement	Emit an executable trace from the task graph
4	tool-hygiene	Track per-tool fingerprints and 60-second failure storms
5	verify	Staged STATIC → UNIT → INTEGRATION runner (reads commands from your own package.json)
6	classify	Turn any failure into a stable 10-class error code
7	recover	Bounded retry with PERMISSION_ERROR/CONFIG_ERROR/DEPLOYMENT_ERROR always falling through
8	test	Self-tests for the agent's own code
9	generalize	Append-only JSONL checkpoint log, format-compatible with DSH uh_checkpoint

The kernel is a contract. It does not call any LLM, does not persist to a database, and does not depend on any vendor SDK.

---

What is the 10-class failure classifier?

Every failure the agent encounters is routed through a deterministic, rule-based classifier before any retry:

CONTEXT_ERROR | TOOL_ERROR | CODE_ERROR | TEST_ERROR | CONFIG_ERROR
ENVIRONMENT_ERROR | PROVIDER_ERROR | PERMISSION_ERROR | DEPLOYMENT_ERROR | UNKNOWN

The contract says: PERMISSION_ERROR, CONFIG_ERROR, and DEPLOYMENT_ERROR are non-retryable. Everything else gets bounded exponential backoff (max 3 attempts, capped at 8 s). This is the recovery policy that prevents agents from burning quota on unfixable errors.

---

How it relates to the DeepSeek Harness

DSH plugin	The production implementation (dsh-universal-harness-core), loaded inside a DSH session via agent.cordis.yml.
This repo	The standalone, public-spec, npm-installable reference for that same contract. Anyone can npm install it and run uea verify . without DSH.
Are they the same thing?	The contract is identical. The reference kit re-implements the same 9 stages in independent code. The DSH plugin has Graphify, telemetry, 19 native tools, and an event bus. The reference kit has zero runtime dependencies.

They are stack, not overlap.

---

How it relates to Free Best Router

MajidAsghariTabrizi/free-best-router is a sibling OSS project:

• Free Best Router answers: Which free model should the agent use?
• UEA answers: How should the agent perform engineering work reliably around that model?

They are complementary, not competing. You can point the DSH llm block at free-best-router and have the UEA kernel coordinate the agent on top of it.

---

Example missions (generic, no project-specific terms)

Three ready-to-run missions ship with the kit:

Mission	What it exercises
mission-add-readme.json	Inspect → plan → implement → verify
mission-fix-failing-test.json	Inspect → classify → fix → verify (the sample workspace has one deliberate bug in multiply — the agent finds and fixes it)
mission-verify-existing.json	The staged verifier runs static + unit + integration against the sample workspace

Run the second mission right now:

git clone https://github.com/MajidAsghariTabrizi/universal-engineering-agent
cd universal-engineering-agent && npm install && npm test
node bin/uea.mjs verify examples/sample-workspace  # overall: fail (the multiply bug)

Then fix src/index.mjs and re-run: overall: ok.

---

What is deliberately NOT in this repo

• No LLM client. You bring the model.
• No database. Checkpoints are JSON-lines on disk.
• No Graphify dependency. Absent Graphify degrades gracefully.
• No vendor SDK. Plain Node.js 18.17+.
• No product-specific, domain-specific, or vendor-specific terms. (Verified by npm run scan.)

---

Roadmap (honest)

• v0.1.0 ← you are here (31 self-tests, 6-command CLI)
• v0.2.0 — model-based classifier opt-in, Graphify provider as opt-in, event bus for fingerprint/storm events, in-process mission scheduler
• v0.3.0 — persistent checkpoint index, multi-language verification defaults (Python, Go, Rust, Solidity), profile inheritance
• v1.0.0 — API stability committed, DSH plugin parity regression suite, long-term agent memory (uh_memory) surface

Full roadmap at docs/ROADMAP.md.

---

Links

UEA repo	MajidAsghariTabrizi/universal-engineering-agent
UEA docs	docs/OPERATING-KERNEL.md
Free Best Router	MajidAsghariTabrizi/free-best-router
DSH plugin	dsh-universal-harness-core

---

UEA is a reference implementation, not a product pitch. If you are building a coding agent and want an explicit, testable operating kernel for the engineering loop — this is one concrete answer to that question. Feedback, issues, and PRs welcome.