Flight Plan Manifest Spec

Schema

The normative schema is JSON Schema draft 2020-12. It lives outside the docs collection so the site never renders it as a page:

docs/schema/flight-plan-manifest.schema.json

A worked, multi-action example that validates against the schema lives beside it:

docs/schema/flight-plan-manifest.example.skill.md

A committed Go drift-guard test (internal/flightplan/spec) keeps the example and the schema from drifting apart. The Aileron block is the only part the schema constrains. The skill keys it sits beside (name, description, and so on) are governed by the agentskills.io format. The Aileron block is named aileron at the top level of the frontmatter:

---
name: weekly-metrics-digest
description: Read a metrics window, summarize it, and file a tracking issue.
aileron:
  schemaVersion: aileron.flightplan.v1
  requires:
    actions: []          # the actions the plan calls, each with a trust contract
  environment:           # the single container the plan runs in, optional
    tools: []            # curated-catalog tools, or an image, or both
  inputs: []             # declared inputs with resolution rules
  outputs: []            # declared output artifacts
  steps: []              # the deterministic step graph, optional
  # lock: produced by freeze, absent before freeze
---

Field reference

The tables below give every field’s type, required-ness, and semantics. Field names align with ADR-0003 (effect, idempotency, approval routing) and ADR-0019 (the credential-placement scheme set). The idempotency, credential, hosts, and audit vocabulary reuses the connector-spec names from the Sandbox Connector Specs page rather than inventing parallel ones.

aileron (top-level block)

requires

Each actions[] entry:

An unsatisfied requires: entry is a missing-requirement signal the runtime surfaces. It is never a parse failure. A manifest that names an action the host has not installed still parses as a valid skill.

environment

The execution environment is one container per run (ADR-0027 the execution environment). The block is optional; a plan that needs no environment omits it. When present, it declares tools, an image, or both. A present block must declare at least one of the two, so an empty environment: {} is rejected. Freeze resolves the declared environment to a single content-addressed image digest recorded in the lock section.

requires.actions[].trustContract

The trust contract is the field set absorbed from #925, quoted here as context rather than depended on. Freeze attaches this contract, and the detached signature is the human attestation that it is correct.

The credential block:

An oauth2 credential must declare the oauth block. An aws-sigv4 credential is always placed via signing, and an oauth2 credential is always placed in a header.

The placement values map to the ADR-0019 wire mechanisms. header is a bearer or templated header (bearer or header-template). query is query-param. signing is AWS SigV4, which maps to sigv4-resign and is sealed by #1501 ↗. session is the cookie or session-token wire form for a session-authenticated upstream. body carries the credential in the request body. The exact header or wire shape is per service, not per placement alone.

The idempotency block:

The audit block:

The closed audit.fields set is connector-hash, action-manifest-version, credential-binding, identity-label, approved-input, approval-decision, network-target, operation-effect, request-summary, response-summary, and result.

inputs[]

outputs[]

steps[]

Every step carries an id unique within the graph and a kind. The remaining fields depend on the kind.

Composition and the step graph

The steps block is the deterministic composition (ADR-0027). It wires declared actions and deterministic transforms into a directed acyclic graph. The block is optional. A skill with no steps block is instruction-only and still a valid manifest.

There are four step kinds.

The kind enum is closed. By construction no kind other than llm-seam can reach an LLM, so the no-LLM guarantee is structurally checkable. The kind: llm-seam value is the first-class mark the freeze and lint step (#1509 ↗) checks, and the runtime (#1511 ↗) enforces that only that one seam reaches an LLM. A transform and a tool step are the structural guarantee that intermediate logic stays deterministic.

A step reads its data through bindings. A binding is a reference, never a value. An action-call step binds its args; a transform, a tool, and an llm-seam step bind their bindings. A binding takes one of two forms. inputs.<name> references a declared input resolved once at the launch boundary (#1523 ↗). steps.<stepId>.<outputName> references a named output of a prior step. The references make the wiring a graph.

The step graph is a directed acyclic graph. The runtime executes it in deterministic topological order. A JSON Schema cannot express acyclicity, so the schema does not enforce it. The acyclicity rule and the topological-order rule are stated here as invariants, the freeze and lint step (#1509 ↗) checks them, and the runtime (#1511 ↗) enforces them. The drift-guard test asserts the worked example’s references resolve and are acyclic.

An action-call step’s actionRef must match a declared requires.actions[].ref. A JSON Schema cannot express cross-array membership, so this too is a stated invariant the lint step checks and the drift-guard asserts on the example.

A step result wires to a declared output artifact through materializesOutput. The value names a declared outputs[].name. This is how a step result reaches the declared outputs contract that the runtime materializes through the file-map transport. The split between the declared outputs contract and the file-map transport is unchanged. See the Outputs contract versus file-map transport section. v1 materializes utf-8 artifacts only and base64 stays reserved.

No step field may hold a secret. This extends the credential-sealing invariant. A step binds references, never values. Every step kind is a closed object, so an additionalProperties key carrying a value is rejected. The args and bindings values are binding references whose grammar is closed to inputs.<name> and steps.<id>.<output>, so a literal secret cannot be embedded in the wiring.

The composition lives under the aileron block, so it is lossless if stripped. Removing the block removes the steps graph with it and leaves a valid instruction-only skill.

Lossless if stripped

The extension is lossless if stripped. A tool that ignores the Aileron fields still reads a valid skill. The schema encodes this guarantee two ways. The aileron block is optional at the top level, so a manifest with the block removed is not rejected. Every Aileron-specific field is nested under that one key, so removing it leaves the agentskills.io skill keys untouched.

The same worked example with its Aileron block removed is still a valid skill:

---
name: weekly-metrics-digest
description: Read a metrics window, summarize it, and file a tracking issue.
license: Apache-2.0
---

# Weekly Metrics Digest

This skill reads a recent metrics window, writes a short digest, and files a
tracking issue that links to it.

A host without Aileron parses the document above and runs it as an instruction-only skill. An unsatisfied requires: is a missing-requirement signal, never a parse failure, so a host that does read the Aileron block but lacks a named action reports a missing requirement rather than refusing to load the document.

Credential sealing invariant

The manifest declares credential kind and placement. It never declares a credential value. This is load-bearing and follows ADR-0005 and ADR-0019. The runtime mediates credential use at the data-plane proxy boundary so the composed code never holds a raw credential.

No field in the schema can hold a secret. The credential block declares kind, placement, and a non-secret identityLabel. The oauth block declares scopes, endpoint URLs, and refresh behavior, never a token. The audit structure records a credential binding reference, never the credential bytes. The frozen artifact and the audit records carry bindings and references, never secret material.

Inputs and resolution

A Flight Plan is a pinned, agent-invariant function over its declared inputs (ADR-0027, durable record in #1523 ↗). It is deterministic given its resolved inputs. Results legitimately vary as inputs and externally-connected data vary. The crisp line is that an LLM in the runtime loop is forbidden because it injects non-determinism into the logic, while a live or time-relative data read is an allowed input that varies the data, not the logic.

Every input the plan depends on is declared, each with a resolution rule. A value that varies by use case, such as a time window, is a declared input rather than a constant baked into the composition, so one composition serves many operators. Inputs resolve once, at the launch boundary, into a concrete resolved-input set. Two steps that read the same moving value such as the wall clock see one resolved value.

There are three resolution rules, discriminated by the rule field.

Outputs contract versus file-map transport

The outputs: block is the declared interface. The file-map is the transport. They are kept distinct so the transport can change later without changing the declared contract (#1519 ↗).

The outputs: block names each artifact, its mimeType, its encoding, and its publish target. This is the contract the runtime materializes and distribution publishes, and the audit references artifacts by name. The transport is a typed JSON file-map. A step returns an array of {path, mimeType, encoding, content} entries that the runtime materializes into files. The file-map generalizes the existing get-file-content shape. The outputs: block is the contract that names what those files are.

Both the file-entry and the outputs: contract carry mimeType and encoding. The encoding enum is utf-8 and base64. v1 implements utf-8 only. Text-only is the v1 implementation, never the declared interface. Binary outputs are a deferred follow-up blocked on a host-ABI binary-body field, and the mount or run-and-collect boundary (#1510 ↗) is the escape hatch for large or binary artifacts later.

Audit record structure

The audit records resolved inputs to outputs (ADR-0027 audit boundary, #1523 ↗). A scalar input is recorded by value, so a current_timestamp input that resolved to a concrete as_of is written down as that timestamp. A data read is recorded by its resolved binding, which is the parameters, the query, and a result or snapshot identifier with a summary, never the full dataset inline. The dataset is the run’s recorded output, and the audit references it rather than duplicating it.

Each operation’s audit.fields declares which of the closed record fields it emits. The closed set is connector-hash, action-manifest-version, credential-binding, identity-label, approved-input, approval-decision, network-target, operation-effect, request-summary, response-summary, and result. The sink is customer-owned. The recorded binding is what makes a past run explainable without reconstructing it from a moving source.

Freeze and the lock section

Freeze turns a skill into a Flight Plan (ADR-0027 freeze boundary). Freeze resolves every image reference to a content-addressed digest, produces a lockfile that pins those digests and the resolved capability set, binds the execution environment, attaches the per-action trust contract, and signs the result. The lock section is the record of those pins.

The lock section is absent before freeze. Freeze populates it and writes an immutable, signed version into the canonical skill store. See the Freezing a Flight Plan guide for the command and the reproducibility and signature-verification guarantees. See the Launching a Flight Plan guide for how the runtime (#1511 ↗) verifies a frozen unit, resolves inputs once at the launch boundary, walks the step graph with no model in the loop, enforces the per-action trust contract, and materializes the declared outputs.

The version is the content hash plus a semver label. The content hash identifies the exact frozen bytes. The semver label is the human-facing version name.

The execution environment

A Flight Plan runs inside one container declared by the environment block (ADR-0027 the execution environment). environment.tools names curated-catalog tools that freeze composes as devcontainer Features (ADR-0026) onto the Aileron-provided runner base. environment.image names a custom base image, the escape hatch for tooling the catalog does not carry, and declared tools compose onto it when both are present. Freeze resolves the declared environment to a single content-addressed digest pinned in the lock, and launch boots that one image and runs the whole plan inside it. A tool step runs a declared tool as a deterministic subprocess in that container; its optional per-step trust contract seals into the lock stepTrust section, and launch enforces the sealed reach at the daemon proxy. The execution container is agent-free. The image carries no coding agent. The Flight Plan runs composed steps, not an interactive agent session.