All docs

Operate

Plugins

The main repository, Repo registrations and the official plugin; the seed, sync, and how changes take effect.

Everything that can change without a new binary lives in plugins: Repo registrations, roles, workflows, harness definitions, prompts and the UI. A plugin is a Git repository in the plugin directory.

Three kinds of plugin

Plugin id What it is
Main repository main The global entry point: it registers every other plugin, holds the Journal, and holds your own content
Official plugin official The roles, workflows, harness definitions, prompts, Router contract rules and base UI that ship with the system. There is one global set
Repo plugin Set at registration A Git repository to work in

The main repository

main/
  ail.yaml               format version
  AGENTS.md              notes for Workers dispatched to the main repository
  repos/<repo id>.md     one registration per Repo
  journal/<year>-<month>.md   the Journal
  skills/<name>/SKILL.md      your own ways of working; optional

A Git repository in this format is the whole entry point. On a fresh installation, put its URL into "Main repository"; the Daemon clones it and then clones every repository it registers.

Registering a Repo

repos/<repo id>.md in the main repository, one per Repo:

---
schema: 1
id: billing
name: Billing
description: The billing service and its admin pages
git: git@example.com:team/billing.git
aliases: [bill]
intents: {disable: [upgrade]}
---

Extra notes for the Router and Workers; may be empty.
Field Required Meaning
id Yes Lower-case letters, digits and hyphens; also the directory name in the plugin directory
name Yes Its name
description Yes One sentence: what this repository is and what should be dispatched to it. The Router picks a Repo by it
git No The Git URL. Without it the repository is local only
aliases No Other names
meta No The id of the meta repository it belongs to
intents, roles No {only: […]} or {disable: […]}: which intents and roles this repository accepts or refuses
archived No true: it no longer appears in the project table and cannot be dispatched to

Registering a Repo takes at least a Git URL, a name and a description:

ail repo add --git git@example.com:team/billing.git --name Billing --description "The billing service and its admin pages"

All Repos are flat; none is nested. The relation between a meta repository and its members is written only in the member's meta.

The official plugin

official/
  workflows.yaml         intents, workflows, called roles, a few limits
  roles.yaml             the binding of every role
  harnesses.yaml         harness definitions
  roles/<role>.md        role descriptions
  frames/                frames for the first message
  prompts/               the global prompt and shared principles
  router/contract.md     the rules of the Router contract
  ui/shell/              the base UI

roles.yaml binds each role to a harness on a Client:

schema: 1
default_client: studio-pc
roles:
  router:   {harness: codex, model: <model>, thinking: medium}
  execute:  {harness: codex, model: <model>, thinking: xhigh}
  media:    {client: media-pc, harness: antigravity, model: <model>}

A binding has four parts: which Client to start on, which harness, which model, how much thinking. model and thinking use the options the harness lists over ACP; they are checked when the session is created, and a wrong value fails.

The seed

A copy of the official plugin ships inside the executable; it is called the seed. When the plugin directory has no official plugin, the Daemon creates a local Git repository, commits the seed on the seed branch and branches main from it. Your changes and the agents' are committed on main.

After a new executable is installed, the Daemon commits the new seed to seed and merges it into main. If there is a conflict or uncommitted work it does not merge; the Config page says so, and you or an agent you dispatch does the merge. An upgrade therefore never overwrites the roles, workflows and UI you changed, and the changes that ship with a new version still reach you.

Sync

ail plugin sync, or the sync button on the Config page: the main repository is fast-forwarded when it can be; missing repositories are cloned from their registrations and the rest fast-forwarded when possible. Nothing is force-pushed and no change is lost; one failing repository does not affect the others.

How changes take effect

What changed How it takes effect
A Repo registration Validated; the Router contract is registered again; a newly registered Repo is fetched automatically
workflows.yaml, roles.yaml Validated; the next dispatch and the next step follow the new version; the Router contract is registered again
harnesses.yaml Validated; the next session is created from the new version
Role descriptions, frames, prompts The first message of the next Worker to start is rendered from the new version
UI plugin source The Daemon rebuilds it, open pages are notified, and a refresh shows the new version

No restart is needed. Workers already started are unaffected: their role description is in their first message.

When a file is malformed, any action that needs it fails at once, and the error says which file and what is wrong. The Router contract and the UI keep the last version that was generated successfully.