Concepts & glossary

You'll learn what each GAIA term means, in a few lines each, with a link to the page where it matters. Terms are alphabetical.

Acceptance criteria — the checkable statements a ticket must satisfy, written at qualification and repeated with a PASS/FAIL status in every later handoff. See Handoffs & comments.

Addon — an npm package (@gaia-ai/addon-*) that plugs one piece into the CLI: the control plane remote, the executor, the workspace, a coding agent, or a command. Named in a config's addons array. See Engine config.

Agent — the coding agent a run launches: Claude Code by default, or Codex, Kimi, OpenCode, pi, Grok. Chosen per project in the engine config and per ticket through a priority rule. See Choose the coding agent.

Base branch — the branch a ticket's work starts from: the parent ticket's branch if it has a parent, else the project repository's default branch. Computed, never set by hand. See The ticket lifecycle.

Blocked by — a relation between tickets. A ticket is not dispatched while any ticket in its blocked_by list is still open.

Bundle — two unrelated things share the word. A skill bundle is a skill that loads other skills: @gaia/essential-skills bundles the globally applicable workflow skills so a WORKFLOW.md loads one line instead of six. A bundle in gaia dropsh is the entity subtype in a JSON:API target — gaia_ticket/gaia_ticket/<uuid>, search gaia_term --bundle gaia_labels. See Skills and the workflow contract and gaia dropsh.

Claim / lease — the atomic grant the control plane gives one conductor to work one ticket. It is time-limited: an unused claim expires and the ticket becomes claimable again. A run is the claim. A ticket is claimed only by the conductor set on it (conductor_id). See Run a ticket.

Comment — a Markdown note on a ticket. Handoffs are comments with a type (qualification, spec, plan, test, summary …). See Comment types.

Conductor — the gaia conductor process on a developer machine: one per project checkout, polling the control plane, claiming tickets and starting runs. Registered on the control plane with a machine_id. See Run a conductor.

Connection config — gaia.config.js: which control plane to talk to and how to authenticate. Inherited from ~/.gaia/ by every repository unless a project overrides it. See Connection config.

Control plane — the Drupal application that owns projects, tickets, states, claims, runs and comments, and serves the board. The single source of truth.

Domain skills / Standards — two sections of WORKFLOW.md, outside its loaded list, that say what binds work in the repository: the skills that encode its standards (named explicitly in every dispatched handoff) and the sources those standards live in. See Author WORKFLOW.md.

Engine config — conductor.config.js: how this repository's conductor runs — project, machine_id, states it picks up, parallelism, addons. Committed. See Engine config.

Footprint — the effort a run recorded: tokens, duration, turns, tool calls, model. Captured at finalise and rolled up for billing. See Ticket metrics.

Handoff — the typed comment a step publishes for the next one: what was decided, what is accepted, what to check. Markdown in the gaia_rich format.

Identifier — a ticket's human name, <PROJECT-KEY>-<number>, for example GAIA-427. Case insensitive on input; branches carry it lowercased.

Label — a tag on a ticket. work:* labels declare sub-works; agent labels such as codex steer agent choice. See Labels & work types.

Machine context — ~/.gaia/machine.config.js: your identity and the client secret, shared by every project on the machine, never committed.

Origin — the URL of the external issue a ticket was imported from. GAIA mirrors the ticket's state back to it as a label. See GitLab: import and origin labels.

Project — the control-plane entity a repository maps to: name, key, repositories, members, environments. Tickets, conductors and runs belong to one.

Run — one execution attempt at one ticket state by one conductor: the claim, the worktree, the agent session, the log, the footprint. States claimed, running, done, expired, failed.

Skill — a Markdown instruction file the agent reads. A step-owning skill declares which (work type, workflow, step) it owns; a helper skill is a verb a step composes.

State — where a ticket is in its workflow: qualification, spec or diagnose, coding, review, done, cancelled. Claimable states may be dispatched. See The ticket lifecycle.

Step — a state, seen from the skill that works it.

Sub-ticket / parent — tickets nest. A child's base branch is the parent's branch, so a parent can carry an integration branch for its children.

Sub-work — one kind of work a ticket contains, declared by a work:* label: work:code, work:docs, and any work type a project adds. Each sub-work has its own step owner.

Ticket — the unit of dispatch and billing: a title, a Markdown description, a workflow, a state, labels, relations, comments, runs.

Work type — the value of a work:* label without the prefix. Selects which skill owns each step for that sub-work.

Workflow — the code-defined state machine a ticket follows: gaia_feature, gaia_bug, gaia_chore, gaia_deployment, gaia_verification. See Workflows & states.

WORKFLOW.md — the file at a repository root that loads the skills for that project and carries its domain skills and standards. It sequences nothing; it lists. See Author WORKFLOW.md.

Worktree — the isolated git checkout a run works in, on the ticket's branch, under .gaia-worktrees/. Reaped after the ticket is done.

Next

• How GAIA works — the terms in motion.
• The ticket lifecycle — states, transitions, who acts.
• The normative spec — the precise definitions.