Assembly Line Documentation

Assembly Line is a plugin-oriented agent framework. You assemble an agent with declarative Markdown and a system prompt. Plugins supply executable capabilities and provider implementations.

agent source                         compiled artifact

agent.md          intent            manifest.json
Markdown body     instructions  ->  runtime bundle
skills/           procedures        route and automation tables
plugins/          code              source and authority hashes

The compiler performs this conversion once. The runtime reads the compiled artifact and never parses Markdown or YAML.

Start with the minimum

---
model: openrouter/openai/gpt-5.4-mini
---

You are a concise assistant.

This is a complete local agent. Omitted fields use documented framework defaults. Add a line only when the agent needs a different product choice:

---
id: coachgpt
name: CoachGPT
description: Reviews training and recovery data.
model: openrouter/openai/gpt-5.4-mini
channels: [photon]
deploy: hetzner
state: postgres
blob: r2
sandbox: e2b
capabilities: [strava]
timezone: America/Chicago
automations:
  morning-review:
    schedule: weekdays at 07:00
    message: Review the latest training and recovery data.
---

You are a careful endurance coach. Give specific, evidence-based guidance.

Each singular scalar selects a complete plugin. Plural fields use lists. For example, channels: [photon] includes Photon routes, authentication, attachments, delivery, rich tools, and OpenRouter audio transcription. Channel selection activates the plugin's channel-owned tools, so Photon is not repeated under capabilities:. Optional connections remain explicit. sandbox: e2b disables internet. The source does not repeat those plugin-owned details.

Authoring rule

Declare each concern once, where it is owned:

Concern	Owner	Agent declaration
Identity, model, stable policy, permanent instructions	`agent.md`	Direct typed field or Markdown body
Channel routes, authentication, attachments, delivery, and default audio	Channel plugin	`channels: [photon]`
Deploy, state, blob, sandbox, and secrets behavior	Typed plugin location	`deploy: hetzner`, `state: postgres`
Schedule polling, claiming, and dispatch	Framework kernel over the state adapter	Declared automations; no `scheduler:` field
Optional procedures and reference material	Skill	`skills/<name>/SKILL.md`
Executable tools, connections, hooks, or custom providers	Plugin	Local plugin presence or published plugin selection
Credentials and deployment inventory	Operator environment	Environment, secret store, or host inventory
Resolved packages, requirements, routes, and hashes	Compiler	Inspect the artifact; do not author them

This leads to four syntax rules:

Omit a concern to use its documented default.
Use a scalar for a singular plugin location.
Use a list for a plural plugin location.
Use a mapping when a selected plugin needs a typed deviation.

# Default E2B behavior: internet disabled.
sandbox: e2b

# One explicit exception: this agent needs internet.
sandbox:
  e2b:
    internet: enabled

Unknown fields and options fail compilation. There are no generic metadata, options, use, or with escape hatches in agent.md. Capability plugin config is accepted only against the selected plugin's locked JSON Schema. See the canonical selection grammar.

Agent folder

agent/
  agent.md                         required
  skills/<name>/SKILL.md           optional; auto-discovered
  plugins/<name>/plugin.json       optional; local plugin, auto-activated
  plugins.lock                     generated plugin integrity and authority
  sandbox/<name>.yaml              optional named sandbox environment
  subagents/<name>/agent.md        optional complete child agent
  automations.yaml                 optional automation include
  evals/                           optional behavior tests
  assets/                          optional stable resources
  migrations/                      optional provider migrations

Root executable folders such as tools/, hooks/, connections/, and channels/ are invalid. Executable behavior belongs inside a plugin's ai.assemblyline extension.

Plugins and Skills

A checked-in local plugin activates when its valid plugin.json is present. Do not repeat it under capabilities:. A published plugin must be installed, selected by stable plugin ID, and pinned in plugins.lock:

capabilities: [notion, github]

The plugin decides its default capability and permission surface. Mapping form adds schema-validated plugin config or narrows a specific contribution:

capabilities:
  meal-memory:
    config:
      dataset: household
    tools:
      disable: [delete_meal]
      approval:
        save_meal: always

Root Skills are independent of plugins and activate by presence under skills/. The runtime exposes their name and description, then loads the full Skill only when needed. Plugin-bundled Skills stay namespaced to their plugin.

Channels and providers

Channels and infrastructure remain visible in agent.md because they define public ingress and operational boundaries. They do not move into the capabilities: list even though packages implement them.

channels: [photon]
deploy: railway
state: postgres
blob: r2
sandbox: e2b

Channel audio is profile-owned. Photon, Slack, Teams, and Telegram use OpenRouter by default. Override or disable audio inside that channel only:

channels:
  photon:
    audio: openai
  slack:
    audio: disabled

There is no top-level media field.

Automations and subagents

An automation has exactly one schedule or provider event trigger:

timezone: America/Chicago
automations:
  morning:
    schedule: weekdays at 07:00
    message: Prepare the morning review.
  activity-changed:
    trigger: strava.activity.create
    filter:
      object_type: activity
    skill: review-activity

A parent lists each child by directory name:

subagents: [researcher]

subagents/researcher/agent.md is a complete agent surface with its own model, description, instructions, capabilities, Skills, sandbox, context, automations, and output schema. The root deployment still owns the physical runtime, state, and blob services.

Validate source and inspect resolution

Use source validation while authoring:

assembly-line validate agent

Inspect the complete executable contract before deployment:

assembly-line inspect agent --resolved
assembly-line capabilities agent

The resolved view includes selected packages, provider defaults, environment requirements, routes, capabilities, permissions, plugin hashes, and authority. It is audit output, not a template for agent.md.

When plugin files change, refresh their lock:

assembly-line plugin lock agent

New executable authority requires explicit confirmation:

assembly-line plugin lock agent --confirm-upgrade

Reference map

Declarative Reference: every field, accepted value, default, and typed exception.
Building Agents: the end-to-end authoring workflow.
Agent Build Stack: each supported file and folder.
Plugins: installation, contribution types, and trust model.
Runtime and Deployment: artifact, runtime, and production operations.

MD-First Agents