Agentic Engineering Harness

AEH is an OSS-first control plane for governed software engineering with coding agents. It binds agent work to explicit user intent, frozen policy and scope, candidate identity, executable evidence, independent review, deterministic acceptance, and controlled delivery. No paid hosted service or paid license is mandatory.

Core Architecture v2 is the current, complete architecture. The normative contract is docs/CORE_ARCHITECTURE_V2.md; this README is the product entry point, not the full architecture specification.

How AEH works

human request
  -> INFORMATIONAL | AUDIT | CHANGE
  -> governed OperationRecord for engineering work
  -> frozen policy, authority, route, and assurance
  -> candidate identity + WorkGraph + compiled participants
  -> deterministic validation + independent Reviewer assessment
  -> AcceptanceOracle + ObjectiveCompletion
  -> ToolActionGate + delivery
  -> terminal resource reconciliation or explicit recovery

The decision path is hybrid: the Lead interprets user intent and product semantics; deterministic controller rules freeze scope and authority, verify evidence, decide acceptance, and gate effects. Model output cannot choose tools or grant authority, change frozen requirements, accept a candidate, or bypass a gate.

Requests use three entry classes:

• INFORMATIONAL answers or looks up repository information without creating an engineering operation.
• AUDIT performs governed, read-only engineering assessment with deterministic validators and independent reviewers.
• CHANGE routes a requested mutation through NO_AGENT, DIRECT, DELEGATED, or FORMAL_SDD. Assurance (NONE, STANDARD, ELEVATED, or CRITICAL) is decided separately from the route.

The Lead owns user intent, genuine product decisions, semantic ambiguity, and user-facing coordination. The Operation Supervisor owns bounded orchestration. Explorer discovers repository facts when needed; Planner decomposes non-trivial work; Spec Manager authors formal OpenSpec/SDD inputs; compiled Implementers execute assigned tasks; independent Reviewers assess evidence; compiled Repairers handle bounded remediation. Small read-only judgments use SemanticAssessmentService when a canonical participant is not needed.

Formal SDD begins with OpenSpec authoring by the Spec Manager. The deterministic compiler validates and seals the executable TaskContract. After freeze, that compiled contract and seal govern implementation. The Lead does not certify deterministic gates: the AcceptanceOracle evaluates candidate-bound evidence, and ObjectiveCompletion checks the operation's required participants, artifacts, lifecycle, and terminal identity.

The ToolActionGate checks authority and lifecycle before external effects such as pushes, pull requests, or other configured delivery actions. Terminal and recovery paths reconcile only resources proven to belong to the operation; live or unknown resources are preserved and reported.

Start a project

Install AEH as a project development dependency, initialize its Harness files, and run the interactive entry point:

npm install --save-dev agentic-engineering-harness
npm exec aeh -- init --setup
npm exec aeh -- doctor
npm exec aeh -- start

aeh start creates a fresh Lead by default. Use aeh start --resume to explicitly resume a compatible managed Lead. Setup provisions the project-selected toolchain; there is no mutating npm postinstall.

The initialized project includes declarative Harness configuration, the engineering-workflow skill, managed assets, and OpenSpec authoring configuration. Consumer configuration such as .harness/project.yaml, .harness/toolchain.yaml, .harness/provider-versions.json, .harness/agents.source.jsonc, .harness/otel-collector.yaml, and openspec/config.yaml is project-owned and can be versioned. .harness/managed-assets.json is also versioned: it carries the hashes needed to restore missing assets, upgrade untouched assets, preserve local overrides, and retire removed assets safely. Other runtime state under .harness/, plus .config/mise/conf.d/aeh.toml, stays ignored; .config/mise/mise.lock and .config/mise/locks/ remain trackable reproducibility inputs.

aeh init, aeh setup, and aeh start reconcile packaged managed assets in consumer repositories. Untouched managed files can be upgraded; locally modified files are preserved as project overrides.

Operations and evidence

Managed AUDIT, CHANGE, and RUN work can start as detached operations so the Lead can return promptly while the deterministic controller owns durable state. Use aeh operation start, status, wait, and cancel to control those operations. A local Paseo operation workspace groups sessions in the UI; it does not by itself create a Git branch or worktree.

The local Control Center presents operation, candidate, evidence, and human-decision state. It does not grant authority or replace controller checks. Context retrieval is controller-authorized, identity-bound, and budgeted; Graphify and memory provide advisory structural or historical context. Repository edits by Serena and model-written summaries do not control acceptance.

Isolation depends on the execution path and host: when Harness policy or a validator spec requires isolation, rootless bubblewrap isolates that validator or external tool; Podman/OCI worker paths are used when selected and provisioned. A required missing provider fails closed. No claim is made that every provider is installed on every host. See docs/SECURITY.md.

AEH self-hosting uses the same governed candidate and evidence model. The product cold-start trial should install a released package in a fresh environment and start it with aeh start; disposable self-modification fixtures keep campaign mutations out of the source checkout.

Developing AEH itself

When the target is this AEH source checkout, build and use the checkout's own entry point:

npm ci
npm run build
npm run aeh -- start
# equivalent: node dist/main.js start

AEH identifies its source checkout by the package name and repository identity in package.json together with Git metadata. Init/setup then use the checkout's tracked configuration and templates as their canonical sources instead of copying consumer bootstrap files or packaged assets back into the source tree. The source checkout does not install the published AEH package as its own dependency. An external or global AEH invocation targeting an AEH checkout re-enters that checkout's dist/main.js; if the local build is missing, start fails closed with build instructions. Consumer repositories should pin AEH as a development dependency and use their project-local npm exec aeh -- ... binary.

Further reading

• Architecture and authority
• Normative Core Architecture v2
• Paseo integration and Paseo-native boundaries
• SDD operating model
• Publishing and release behavior
• Certification, security and isolation, and component maturity
• Context efficiency, memory, and observability
• Roadmap history and engineering evidence ledger

License

Apache-2.0