Skip to content

ADR-003 AI interface

Generated — do not edit

This page is produced by scripts/generate-runtime-adrs.sh from engineering-runtime/docs/04-design-decisions/adr-003-ai-interface.md. Source commit: 38eec00 (2026-08-04 UTC). Hand edits are overwritten on the next sync and fail scripts/check-generated-adrs.sh. Change the ADR in the runtime repo, then re-run the generator. Relative links from the source ADR are rewritten to GitHub blob URLs.

Status

Unchanged by ADR-005. AI still never executes. What changed is what AI reasons over: a published, discoverable provider operation surface (runtime github --help) instead of a central command registry. The boundary is identical. See adr-005-provider-layer.md.

Adopted, load-bearing. Any AI-facing feature added to this project should be evaluated against this decision — see ../03-core-concepts/ai-and-runtime.md for the full explanatory model this decision produced.

Context

Once Engineering Capabilities exist as the unit of reusable engineering knowledge (see adr-001-capabilities.md), a second question follows immediately: how should AI interact with the runtime at all? The options considered:

  1. Let AI call engineering platforms (REST APIs, CLIs, shell) directly, with the runtime as one tool among many it can reach for.
  2. Let AI call the runtime's execution engines directly, bypassing capability authoring.
  3. Restrict AI to a narrow, well-defined role — understanding intent and issuing requests to the runtime — with the runtime remaining the only thing that ever executes.

Decision

Option 3. AI interacts with the runtime only through a Runtime Agent role: understand intent, discover/resolve capabilities, build a runtime request, and hand off. The Runtime Agent never executes engineering work itself; the Engineering Runtime performs deterministic execution, identically, regardless of which Runtime Agent (if any) initiated the request.

Engineer → Natural Language → Runtime Agent → Engineering Runtime → Engineering Platforms

Why

  1. Determinism requires a single execution path. If AI could execute engineering operations directly (option 1) or bypass capability validation (option 2), "same request → same outcome" (see ../03-core-concepts/deterministic-execution.md) becomes unenforceable — every AI model, prompt phrasing, or client could produce a different execution path.
  2. Policy and audit need one choke point. Bootstrap → Context → Policy → Auth → Execution → Audit only provides real governance if there is no way around it. An AI with direct platform access is a bypass by definition.
  3. AI independence follows directly from this boundary. Because the Runtime Agent is a thin, replaceable translation layer and never the execution platform, any AI (Claude, ChatGPT, Gemini, Copilot, Cursor, enterprise platforms) can fill that role without the Engineering Runtime changing at all.
  4. Vendor neutrality. No engineering capability becomes tied to one AI provider's prompt format, since capabilities are validated/executed by the runtime, not interpreted by a specific model.
  5. Lower migration cost. Adopting a new AI system means implementing a new Runtime Agent, never re-platforming the runtime itself.

Alternatives considered and rejected

  • AI calls engineering platforms directly (no runtime in the loop) — rejected: no consistent way to insert authentication, policy, or audit before execution; see ../01-vision/problem-statement.md.
  • AI calls Runtime Engines directly, skipping capability authoring/validation — rejected: this would let AI's phrasing/model choice influence what actually executes, reintroducing the same non-determinism problem in a different place.

Consequences

  • Any AI-facing feature in this project must be shaped like a Runtime Agent: understand intent, discover/resolve capabilities, hand off — never execute directly. See the responsibility-split table in ../03-core-concepts/ai-and-runtime.md.
  • .claude/skills/*.md and CLAUDE.md in this repo are themselves an instance of this pattern applied to AI coding sessions: an AI reasoning about intent, restricted to a governed, published contract (see ../05-development/coding-guidelines.md), rather than executing arbitrary shell commands from a hidden prompt.
  • The first dedicated Runtime Agent contract lives in the sibling repo engineering-runtime-ai-agent (CLAUDE.md + hooks that restrict shell to runtime). Additional AI-vendor adapters can follow the same shape without changing this runtime.
  • adr-004-execution-engine-selection.md sharpens this same boundary one layer further down: not only does AI never execute directly, it also never selects which Engine (REST/Command/File) performs an operation — that choice belongs to the runtime.