Universal Engineering Agent

Overview

A profile-agnostic, runnable, MIT-licensed reference implementation of an engineering-agent operating-kernel contract.

Engineering agents accumulate tribal knowledge in their system prompts until the prompts are 4,000 tokens of opaque context no one outside the author can reuse. The Universal Engineering Agent (UEA) is the opposite direction: it is intentionally small and intentionally profile-agnostic.

What I built

• A 9-stage operating kernel contract: inspect → plan → implement → verify → classify → recover → test → generalize + hygiene.
• A staged verification runner (STATIC → UNIT → INTEGRATION → RUNTIME → DOMAIN) with stable failure classification.
• A 10-class error-code classifier with bounded retry and non-retryable fall-through.
• A checkpoint system that records objectives, known / unknown / hypotheses / decisions / files-changed / tests-run / blockers / next-action.
• A profile-driven runtime so the kernel stays vendor-neutral and project-specific knowledge lives in profiles.
• A self-contained CLI: uea inspect / plan / verify / classify / test / scan.
• 31 self-tests for the agent's own code, plus a pre-publish secret / PII scanner.
• Documentation suite: operating kernel, architecture, missions, integration, roadmap, security.
• Zero runtime dependencies, plain Node.js ≥18.17, MIT-licensed.

Why it matters

It is the smallest possible reusable shell an LLM-driven engineering agent can sit inside and still be production-safe. It can be used standalone, alongside the DeepSeek Harness `dsh-universal-harness-core` plugin, or alongside free-best-router. It is intentionally not a product — it is a contract.

Problem

Engineering agents accumulate tribal knowledge in their system prompts until the prompts are 4,000 tokens of opaque context no one outside the author can reuse. The Universal Engineering Agent (UEA) is the opposite direction: it is intentionally small and intentionally profile-agnostic.

Architecture

MissionSpec ─▶ uh_mission ─┐
                            ├─▶ uh_context_build ─▶ uh_verify
Checkpoint   ─▶ uh_checkpoint│     │                   │
Profile      ─▶ uh_profile   │     ▼                   ▼
Memory       ─▶ uh_memory    │   uh_graph          classify
                            │   filesystem         recover
                            │   documentation      generalize
                            │   runtime            hygiene
                            ▼
                    9-stage kernel:
                    inspect ▸ plan ▸ implement
                      ▸ verify ▸ classify ▸ recover
                      ▸ test ▸ generalize ▸ hygiene

External: profile.yml, checkpoints.jsonl, .uea-test/

Engineering decisions

• Profile-agnostic on purpose. The kernel is what every agent needs; the profile is what a specific project needs.
• Zero runtime dependencies. Every dependency is a future maintenance liability.
• Self-tests are first-class — the test stage tests the agent's own code, the verify stage tests the user's code.
• Stable 10-class failure taxonomy so retries are bounded and fall-through is explicit.
• Checkpoints are JSON-lines on disk, not in a database — easy to inspect, version, and replay.
• A pre-publish scanner that fails the build on secrets / PII, run on every commit.
• No vendor SDKs, no Graphify dependency, no cloud lock-in. The production plugin in DeepSeek Harness provides those; the kernel contract does not require them.

What changed during development

• Earlier attempts to ship "the one true agent prompt" became unmaintainable fast. The split into a small kernel + a project-specific profile was the direct response.
• Early failure handling tried to be clever. The classifier now returns one of ten stable codes and that is it — reasoning is bounded and explicit.
• A first version stored checkpoints in a database. That made "show me what the agent did yesterday" much harder than it needed to be. JSON-lines on disk are the right primitive.

Technical implementation

• Plain Node.js ≥18.17, ESM, no runtime dependencies.
• CLI bin/uea.mjs exposing inspect, plan, verify, classify, test, scan.
• Modular kernel with one file per stage plus a hygiene tracker.
• Self-tests under test/ run with node --test.
• Documentation under docs/ covering the operating kernel, architecture, missions, integration, roadmap, and security.
• Example profiles and missions under examples/ and profiles/.
• CI that runs the self-tests and the secret / PII scanner on every commit.
• MIT license, npm-installable, public registry ready.

Product implications

• A reference implementation is a contract others can build on without asking permission.
• A small, well-scoped kernel with documented profiles is more useful than a large, opinionated framework.
• Tooling that the author themselves uses every day (a scanner, a test runner, a classify command) compounds over time.

Lessons learned

• Split what is universal from what is specific. Universal lives in the kernel; specific lives in the profile.
• A failure taxonomy is a product surface. Stable codes are how you build tooling on top of an agent.
• Self-tests are not optional. If you cannot test your agent's code, you cannot trust your agent.
• Documentation is part of the contract. The 9-stage pattern has a reason for every stage and that reason is written down.

Current state

Reference implementation shipped. MIT, zero runtime deps, 31 self-tests, full docs suite. Featured on the DSH "Show Your Plugins!" board. Used as the canonical public-spec counterpart to the DeepSeek Harness `dsh-universal-harness-core` plugin.