Assembly Line Documentation

Assembly Line turns a small agent folder into a pinned runtime artifact. Authors describe the agent in Markdown and YAML. Plugins provide executable capabilities and typed providers. The compiler resolves both into the existing durable manifest and runtime contracts. The exact accepted YAML grammar lives in the canonical Declarative Reference.

agent.md + skills + plugins + assets
                  |
                  v
        validate and resolve
                  |
                  v
    immutable manifest and source bundle
                  |
                  v
       unchanged durable runtime

The runtime does not parse Markdown, YAML, plugin manifests, schedules, or composition rules. That work happens once during compilation.

Agent folder

agent/
  agent.md
  plugins.lock
  skills/
  plugins/
  subagents/
  sandbox/
  assets/
  evals/

Only agent.md is required. Its model prefix must resolve to an installed, locked model plugin; assembly-line init installs and selects OpenRouter. Root Skills are discovered by convention. Every immediate child of plugins/ must be a conforming Agent Plugins v1 package and is active by presence. Published plugins are selected by ID in agent.md and pinned in plugins.lock.

MD-first agents have no root agent.ts, gateway.ts, tools/, hooks/, connections/, or lib/ authoring paths.

agent.md

YAML frontmatter holds inspectable configuration. The Markdown body holds permanent instructions:

---
id: coachgpt
model: openrouter/openai/gpt-5.4
deploy: railway
state: postgres
blob: r2
sandbox: e2b
channels: [photon]
capabilities:
  - mirror
automations:
  morning-brief:
    schedule: weekdays at 07:00
    skill: morning-brief
---

# Role

Coach the user from their training, recovery, and nutrition data.

Unknown keys, duplicate YAML keys, aliases, executable tags, unsafe object keys, malformed profiles, and empty instruction bodies fail compilation. Omitted infrastructure fields use versioned local defaults, which appear in the resolved manifest and inspector.

Infrastructure and channels

Singular infrastructure fields select one plugin with a scalar. A one-key mapping adds plugin-specific options. channels is plural: use a list for defaults or a name-to-options mapping for deviations.

Channels remain explicit because they expose ingress and delivery authority:

channels:
  photon:
    audio: openai
  slack: {}

Channel plugins own authentication, normalization, streaming, typing, attachments, and delivery. Attachment-capable plugins also own a versioned audio transcription default. Capability plugins do not hide channel selection.

Framework tools and plugins

Safe framework tools load by default. Authors do not repeat them in agent.md.

Plugins own every installable or replaceable capability:

model-provider registration, discovery, authentication, embeddings, request semantics, accounting, and deployment requirements;
deploy, state, blob, sandbox, secrets, media, channel, context, and observability providers;
model-callable native tools;
external connections and their tools;
portable MCP servers and Skills;
connection event catalogs and webhook handling;
lifecycle, event, composition, context, instrumentation, and channel hooks.

The runtime still keeps models, adapters, tools, connections, hooks, and lifecycle handlers as different typed systems. The plugin is their package, selection, and permission boundary—not a replacement for those contracts.

The non-plugin kernel is deliberately small: schemas and contracts, safe YAML compilation, durable orchestration, the Node host, Pi's provider-neutral model loop, and local development defaults. It contains no catalog of official vendors. Adding an unknown provider package does not require a framework edit.

A published plugin needs only its ID:

capabilities:
  - mirror
  - github

Use mapping form for schema-validated plugin configuration or a typed tool or connection contribution exception:

capabilities:
  private-search:
    config:
      index: products
    tools:
      approval:
        rebuild_index: always

The plugin owns the config schema; the framework owns the exception grammar. Installed but undeclared published plugins stay inactive.

Custom TypeScript belongs in one cohesive local plugin:

plugins/coachgpt/
  plugin.json
  ai.assemblyline/
    index.ts
    training.ts
    meals.ts
    first-contact.ts

The plugin entry names every executable contribution. The compiler statically reads that entry, validates contained source paths, records authority, packages the exact files, and never executes plugin code during compilation.

Locking and authority

plugins.lock version 3 records each plugin's source, version, integrity, portable capabilities, and executable authority, including model and provider contributions. Local source changes refresh the local lock with a visible diff. Published upgrades that expand authority require explicit confirmation.

The lock is an installation and review boundary, not automatic activation. Only the graph selected by typed agent.md fields, capability declarations, qualified references, and checked-in local-plugin presence enters an artifact. An installed but unselected published plugin contributes no runtime code.

Plugin files and lock contents contribute to agentRevision. A built artifact cannot silently load a different capability set.

Skills

Root skills/<name>/SKILL.md holds agent-specific procedures. Published and local plugins may also ship reusable Agent Skills in the standard plugin layout. Skill bodies and resources load lazily.

Skills explain how to perform work. Plugins implement deterministic actions, external authority, runtime hooks, and protocol boundaries. A Skill may use framework tools to read or write memory, but prose should not replace a custom tool when exact schemas, validation, approvals, or transactional side effects matter.

Automations

Automations live in agent.md or a contained automations.yaml include. Plain-language schedules compile to cron at build time. Connection events start runs only when an automation explicitly subscribes to them.

Named lifecycle code belongs to a plugin. Schedule identity, event identity, filters, delivery, idempotency, and targets remain visible in agent.md.

Composition and mutability

Declarative composition rules can select model, reasoning, instructions, and capabilities from bounded run fields and persistent control state. Arbitrary composition code belongs to a named plugin contribution with declared models, reasoning levels, capabilities, and state keys.

Compiled code stays immutable. mutability sets ceilings for durable learned Skills, runtime-created automations, and dynamic external access. Those values remain overlays under the stable agent ID; the runtime does not rewrite source.

Subagents

Declare children in the parent's agent.md. Each child has its own subagents/<name>/agent.md and may own Skills, plugins, channels, context, sandbox selection, and nested children. The compiler rejects undeclared child folders and validates the full tree.

Subagent tools, connections, context, channels, memory, and workspace scopes remain isolated. The framework adds the delegate tool only when the parent has an enabled child.

Compiler output and inspection

Compilation produces a deterministic manifest, generated setup sources, plugin wrappers, packaged resources, preflight requirements, route and automation tables, agentRevision, and a full build revision.

Use these commands before deployment:

assembly-line validate agent --json
assembly-line inspect agent --resolved
assembly-line explain plugins.mirror agent
assembly-line build agent

Inspection shows authored values, framework defaults, resolved providers, plugin integrity and authority, skills, tools, connections, routes, automations, subagents, source files, and provenance.

Runtime guarantees

The MD compiler feeds typed runtime contracts for:

durable runs, events, checkpoints, approvals, and resumptions;
state, memory, blob, workspace, and sandbox persistence;
tool schemas, timeouts, execution modes, and approval policy;
OAuth, API, SDK, CLI, MCP, A2A, OpenAPI, and webhook connections;
schedules, event filters, lifecycle handlers, and delivery queues;
model usage, telemetry, channel-owned audio processing, and structured output;
recursive subagents and conditional capability snapshots.

Markdown adds no runtime network hop or adapter wrapper. The compiler is the only translation boundary.

Framework guide