Skip to content

ADR-001 Capabilities

Generated — do not edit

This page is produced by scripts/generate-runtime-adrs.sh from engineering-runtime/docs/04-design-decisions/adr-001-capabilities.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

Grammar note (ADR-005). This decision is unchanged in substance: engineering knowledge lives in Capabilities, and a capability still gets no execution path of its own. Only the workflow step syntax changed — a step now names provider: + args: (the operation, as typed on the CLI) instead of a registered Runtime Command name. See adr-005-provider-layer.md.

Adopted, load-bearing. Do not blur the Skill/Capability boundary when adding AI-facing features — see ../03-core-concepts/ai-and-runtime.md for what a compliant "Runtime Agent" integration looks like.

Context

Every consumer of this project — human, AI, or CI/CD — needs a way to express reusable engineering workflows ("Bootstrap Java Service," "Restart Kubernetes Deployment," "Rotate Cloud Secrets"). Two shapes were available:

  1. Let AI hold this knowledge as prompts/skills, re-derived and re-reasoned every time.
  2. Externalize it as a runtime-executable artifact that AI (or a human) authors once and the runtime executes deterministically, forever, regardless of which AI (if any) is involved.

Decision

Engineering knowledge is captured as an Engineering Capability — executable Markdown with an embedded deterministic runtime block — never as an AI Skill/prompt the runtime depends on.

AI has Skills. Engineering Runtime has Capabilities.

No. AI has skills. Engineering Runtime has capabilities.

  • AI Skill — reasoning/knowledge an AI model uses to understand Engineering Intent. The runtime never executes AI Skills.
  • Engineering Capability — a reusable engineering workflow the runtime does execute, regardless of which (if any) AI authored it.

Why

  1. AI is optional, not foundational. Capabilities can be authored by humans or any AI model (ChatGPT, Claude, Gemini, Copilot, future models) — the runtime never depends on any one of them. Tested repeatedly against the question: would this still make sense with no AI, or a different AI? Answer: yes, every time.
  2. The runtime owns execution; AI never executes anything. Keeping this boundary hard is what makes audit, policy, and determinism possible — an AI that could execute directly would make "same request → same outcome" unenforceable.
  3. A Capability is a new, portable engineering artifact — human-readable, AI-understandable, runtime-executable, versioned, packaged, shareable — comparable to a shell script, Helm chart, or Terraform module. It outlives any particular AI session or model.
  4. The runtime is self-describing. It ships the Runtime Command registry plus Capability/Workflow/Package specifications needed to author new capabilities — nothing is guessed from hidden prompts. An AI (or human) authoring a capability reads specs/capability-spec.md and the relevant per-provider spec, the same file every session reads, rather than being taught through an evolving system prompt.
  5. The architecture survives AI model changes because every layer communicates through published, deterministic contracts (commands, specs, catalogs) rather than model-specific prompting.
  6. Practical effect on AI's role: if a capability already exists, AI doesn't even need to "write" anything — it discovers and invokes the existing capability. AI's role shifts from Executor to Capability Author, and once a capability exists, often not even that.

Alternative considered

Letting AI hold engineering workflows as reasoning/prompts (an "AI Skill") and re-derive the correct sequence of operations each time it's asked. Rejected because it makes execution non-deterministic by construction — the same intent, asked slightly differently or of a different model, could produce a materially different sequence of operations, which is incompatible with audit and policy enforcement. See ../03-core-concepts/deterministic-execution.md.

Origin

An earlier runtime prototype shipped not just commands but also the specs describing them; a separate AI project generated CI/CD workflows purely from those specs. Later, an AI interface built with CLAUDE.md- and hooks-style human-readable contracts restricted an AI to a runtime binary (no arbitrary shell access) and it still reliably produced deterministic reports/workflows. That result — AI governed entirely through a published, human-readable contract rather than a hidden prompt — is the direct origin of the Capability model: CLAUDE.md-style contracts proved AI can be governed this way; Engineering Runtime generalizes it into Capabilities.

Consequences

  • Capability authoring is validated by the runtime (runtime capability validate), never trusted on AI's say-so. See ../02-architecture/capability-model.md.
  • A capability can never invent a new Runtime Command or binary to call — it can only compose what the runtime already exposes. If something is missing, the fix is a new Runtime Command or allowed_binaries entry, never a capability-only escape hatch.
  • Storage/distribution of capabilities is deliberately not solved by the runtime yet (see ../06-roadmap/future.md) — this was a scoping decision to keep v1 small, not an oversight.
  • This decision is why the project's docs describe AI's contribution using words like "author" and "reason," and reserve "execute" exclusively for the runtime.