Key Concepts

Lane

Isolated worktree + environment.

Stack

Chained lanes for stacked PRs.

Pack

Durable agent context bundle.

Checkpoint

Immutable execution snapshot.

Session

Terminal session with metadata.

CTO

Always-on orchestrator agent.

Mission

Structured multi-step AI unit.

Automation

Trigger-driven execution rule.

Worker

Scoped sub-agent that writes code.

ADE CLI

Native action surface for agents.

Job Engine

Background task scheduler.

PR Convergence

Automated PR-to-merge loop.

Conflict

Predicted or actual merge conflict.

Artifact

Proof produced by AI work.

Lane

A Lane is ADE’s unit of parallel work — an isolated execution environment with its own git branch, working directory, terminal sessions, agent context, and environment variables.

Primary Lane

The repository’s main working directory. Every project has exactly one Primary Lane — it represents the cloned repo root itself. Cannot be deleted.

Worktree Lane

A git worktree created by ADE under .ade/worktrees/<name>/. Fully managed by ADE: created, configured, and cleaned up via the Lanes UI.

Attached Lane

An external git worktree that already exists on disk and has been imported into ADE. ADE tracks it but does not move its files. Can be “adopted” into a full Worktree Lane later.

Each lane stores its branch name, appearance (color/icon), environment status, active sessions, and pack reference.

Think of lanes like browser tabs — each is an isolated context that persists even when you are not looking at it.

Stack

A Stack is a chain of lanes for stacked PR workflows — each lane targets the lane directly above it as its base branch.

  main
   └── feature/auth          ← Lane 1 (targets main)
        └── feature/auth-ui  ← Lane 2 (targets feature/auth)
             └── feature/auth-tests  ← Lane 3 (targets feature/auth-ui)

ADE tracks the stack topology and automatically rebases downstream lanes when an upstream lane is updated, surfaces rebase suggestions, and shows the full chain in the inspector. To create a stacked lane, use Lanes → New Child Lane. ADE sets the child’s base branch to the parent’s current branch automatically.

ADE tracks rebase suggestions per-lane. When an upstream branch changes, a compact banner above the lane list surfaces each affected child. From there you can open the full workspace with View in Rebase tab, or dismiss the suggestion if it is not relevant.

Runtime context

ADE keeps runtime context local to the work being done. Agents receive lane/session state, selected artifacts, mission details, memory retrievals, and explicit user instructions. When they need product or architecture knowledge, they inspect the repo directly instead of relying on generated PRD or architecture summaries. ADE also stores some compatibility artifacts under .ade/artifacts/packs/ for audit and replay:

Conflict Pack

A resolution-context pack created when a conflict is detected between two lanes. Contains the conflicting file regions, each lane’s intent, and suggested resolution strategies. Injected into the resolver agent’s context.

Plan Pack

A versioned coding plan generated during a Mission’s Planning phase. Captures the mission’s goal, steps, assumptions, risks, and executor assignments. Serves as the authoritative reference for all workers during execution.

Mission Pack

A deterministic snapshot of a mission at a specific point in time — used for resume, audit, and replay. Contains the full mission state: plan, completed steps, artifacts, interventions, and cost data.

Checkpoint

A Checkpoint is an immutable snapshot created at session or commit boundaries, containing the git SHA, file deltas, timing, and actor metadata. Checkpoints appear in the History view and can be replayed to restore any lane’s state. They are append-only — ADE never deletes them unless you explicitly clear project data.

Session

A Session is a terminal session with metadata attached — full transcript, timing, agent attribution, file delta computation, and mission/step linkage. Every terminal window ADE opens is recorded. The History view groups sessions by lane, mission, and date.

CTO

The CTO (Chief Technical Officer agent) is ADE’s always-on, project-aware AI agent that sits at the top of the agent org chart. Unlike lane-level agents that focus on specific tasks, the CTO maintains a persistent memory of the entire project and orchestrates work across all lanes. The CTO can:

Maintain and update a project memory (architecture, decisions, team conventions)
Spawn Worker agents in specific lanes to handle delegated tasks
Sync with Linear — read issues, update status, create new issues when problems are discovered
Manage budgets — track per-agent and per-mission token spend, enforce limits
Surface risks — proactively flag conflict risks, stale lanes, and budget overruns
Conduct retrospectives — periodically review what missions succeeded and what failed, and update project memory accordingly

The CTO is configured from the CTO tab (model, budget limit, Linear workspace, worker-spawning policy). Related global preferences — per-role models, monthly caps, Linear integration — live under Settings → AI, Settings → Usage, and Settings → Integrations.

If you are a solo developer, think of the CTO as your always-on senior engineer who is watching your project while you sleep. Brief it on your goals at the start of the week; it will decompose the work, assign it to agents, and present you with completed PRs.

Mission

A Mission is a structured AI execution unit for complex, multi-step work. Missions provide accountability, cost tracking, and a formal lifecycle that ad-hoc chat sessions do not.

Missions are visible in every build, but creation and live runs are paused in packaged releases until the orchestration flow is production-ready. Dev and internal builds run missions end-to-end. The Automations tab mirrors this: the mission execution surface is shown but disabled in packaged builds.

Mission Lifecycle

Queued → Planning → [Approval] → Execution → Validation → Completed
                                                         ↘ Failed
                                                         ↘ Canceled

Planning

A planner agent (Claude CLI or Codex CLI) reads the mission goal and generates a structured Plan — a JSON document with steps, executor hints, lane claims, dependencies, and a join policy. The planner also asks clarifying questions if the goal is ambiguous.

Approval (optional)

If the mission requires human approval before execution, ADE pauses here and presents the plan for review. You can accept, edit, or reject the plan. If launchMode is autopilot, this phase is skipped.

Execution

Worker agents execute the plan’s steps. Parallel steps run simultaneously in separate lane worktrees. The Mission coordinator monitors progress, handles failures, and retries steps according to the plan’s retry policy.

Validation

A dedicated validator agent (or self-validation, depending on the phase profile) reviews the completed work against the mission’s goal and acceptance criteria. Computer-use proof may be required (screenshots, browser verification).

Mission Statuses

Status	Meaning
`queued`	Created but not yet started
`planning`	Planner agent generating the execution plan
`in_progress`	Workers executing plan steps
`intervention_required`	Paused — requires human input to continue
`completed`	All steps done and validation passed
`failed`	A step failed and could not be recovered
`canceled`	Stopped by the user

Interventions

When a mission cannot proceed without human input, it creates an Intervention and pauses. Intervention types include:

approval_required — a phase requires explicit sign-off
phase_approval — a phase boundary gate requires approval before advancing
manual_input — the agent needs an answer it cannot infer
conflict — a merge conflict blocks a step
failed_step — a step failed and automatic retry was not successful
budget_limit_reached — the mission has hit its token or cost cap
orchestrator_escalation — the coordinator detected an unrecoverable error
provider_unreachable — the AI provider is unavailable

You resolve interventions from the Mission’s Run panel by providing an answer, accepting defaults, or canceling the run.

Automation

An Automation is a trigger → execution-surface rule that runs in response to:

time-based triggers (schedule)
action-based triggers (webhooks, commits, PR events, manual runs)

Trigger Types

Git Events

Fires on git.push, git.pr_opened, git.pr_merged, git.commit, and other git events. Example: auto-run tests when a PR is opened.

Schedule (Cron)

Fires on a cron schedule. Example: run a dependency audit every Monday at 8am.

File Changes

Fires when specific files or patterns change. Example: regenerate the API documentation whenever openapi.yaml changes.

Webhook events

Fires from GitHub webhooks or generic external webhooks. Example: run a scan when a pull request review is requested.

Execution surface

Each rule chooses one execution surface:

agent-session: creates an automation-only chat thread with AI messages and tool events.
mission: launches a full mission with planner, validation gates, intervention handling, and worker artifacts.
built-in-task: runs a predefined ADE task without full mission semantics.

Agent-session outputs appear in Automations → History. Mission outputs appear in Missions.

Worker / Employee Agent

A Worker (also called an Employee Agent) is a sub-agent spawned by the CTO or by a Mission to handle a specific, scoped task. Workers are the agents that actually write code. Worker characteristics:

Run in a specific lane with a scoped working directory
Have bounded tool access — only the tools their role requires
Operate within a budget limit set by the spawning coordinator
Are attributed in session metadata for full traceability
Can be claude_cli, codex_cli, or unified (in-process API) executor kinds

The Mission coordinator manages worker lifecycle: spawning, monitoring heartbeats, retrying failed workers, and collecting their outputs.

ADE supports parallel workers — multiple workers executing different plan steps simultaneously in different lanes. The parallelismCap field in the mission plan limits how many workers run at once.

ADE CLI and Actions

ADE CLI is the native action surface agents use to operate ADE. The desktop app exposes a private ADE RPC socket at .ade/ade.sock, and ade falls back to a headless local runtime when the desktop socket is unavailable. When an AI agent is running inside ADE (whether via Claude CLI, Codex CLI, or the in-process API), it can run ade commands — which hit the desktop socket when available and fall back to the headless runtime — to perform operations that go beyond simple text generation:

Git operations

Stage files, commit, push, create branches, run merge simulations, cherry-pick, and manage stashes — all with full attribution back to the calling agent.

File access

Read and write files across any lane’s worktree. File writes are atomic and logged as session deltas.

Terminal control

Spawn a new PTY session in a specific lane, write input, and read the output transcript.

Agent spawning

Spawn a new Claude CLI or Codex CLI session in a lane, with a prompt and a budget limit. This is how the CTO delegates work to workers.

Pack management

Read, write, and refresh context packs. Agents can update their own lane pack with new context they have discovered.

Mission management

Create missions, update step status, add artifacts, create interventions, and report progress back to the Mission coordinator.

Memory

Add to and search the project’s persistent memory store. Rate-limited per session to prevent memory spam.

Computer-use artifacts

Route screenshots, browser traces, video recordings, and console logs to their owners (missions, PRs, Linear issues, chat sessions).

Sessions are authenticated by role: orchestrator, agent, external, or evaluator. Coordinator-level tools (spawning agents, creating missions) are only available to orchestrator-role callers.

Job Engine

The Job Engine is ADE’s background task scheduler that handles work that should happen automatically, without user interaction. Current job types:

Lane pack refresh — triggered when a lane’s files change significantly, to keep the lane’s context pack current
Conflict prediction — periodically runs merge simulations between all active lane pairs to surface potential conflicts early
Rebase suggestion generation — detects when upstream branches have moved and generates rebase suggestions for downstream lanes
Automation execution — receives trigger events and executes the appropriate automation rules

The Job Engine uses a per-lane queue with deduplication: if a lane refresh is already running, a second trigger is coalesced into a single pending request rather than creating a duplicate job.

In development mode, the Job Engine’s periodic conflict prediction is disabled by default (to reduce noise). Set ADE_ENABLE_CONFLICT_PREDICTION=1 to force-enable it.

PR Convergence

PR Convergence is ADE’s automated loop for driving a pull request from “has issues” to “ready to merge.” It combines an issue inventory, AI-powered resolution rounds, and an optional auto-converge poller into a single workflow accessible from the Path to Merge tab on any PR. The convergence system:

Scans the PR for failing CI checks, review comments requesting changes, and bot feedback (CodeRabbit, Copilot, Codex)
Launches rounds — each round creates an agent session that reads the open issues, makes code changes, and commits
Polls for CI completion and comment stabilization between rounds
Decides whether to launch another round (if new issues appeared) or mark the PR as converged
Auto-merges (optional) when convergence is complete and all checks pass

Two modes are available:

Manual — you trigger each round explicitly and review results between rounds
Auto-Converge — ADE runs the full loop autonomously, pausing only when it hits a limit (max rounds, rebase needed, or agent error)

Pipeline settings control convergence behavior: max rounds, merge method, auto-merge, and rebase policy. These can be configured per-PR or set as project defaults in .ade/ade.yaml.

The CTO agent can also drive PR convergence programmatically using five dedicated operator tools, enabling fully autonomous PR management without human interaction.

Conflict

A Conflict in ADE is a predicted or actual merge conflict between two lanes. ADE distinguishes between:

Predicted conflicts: File-level overlaps detected by running git merge --no-commit --no-ff simulations between lane pairs. These are surfaced in the Conflicts view before you attempt an actual merge.
Active conflicts: A real merge conflict that has occurred during a rebase or merge operation and requires resolution.

The Conflict view shows:

A risk matrix — which lane pairs have the highest overlap risk
File-level overlaps — which specific files are touched by multiple lanes
AI resolution proposals — generated by ADE’s conflict resolver agent, with a diff-level proposed resolution
External resolver sessions — if you prefer to use a CLI resolver (e.g., a dedicated agent), ADE can prepare and finalize resolver sessions

Proof / Artifact

A Proof (also called an Artifact) is evidence produced during AI-driven work. ADE collects, normalizes, and routes proof artifacts to the appropriate owners.

Artifact Types

Type	Description
`screenshot`	A static image of the browser or desktop at a specific moment
`browser_verification`	A structured record of a browser-based verification test
`browser_trace`	A full Playwright/CDP trace recording of a browser session
`video_recording`	A short screen recording captured via `ade proof record`
`console_logs`	Browser or Node.js console output captured during testing
`test_report`	A structured test run result (pass/fail per test case)
`summary`	A human-readable summary of completed work
`pr`	A link to an opened or merged pull request
`patch`	A raw git patch file
`plan`	The generated mission plan document

Proof Capture Flow

Agents capture intentional evidence by calling the ade proof CLI — screenshot, short recording, or ingestion of an external browser trace:

The agent runs ade proof screenshot, ade proof record, or ade proof ingest from a terminal inside its lane.
ADE’s artifact broker in the main process normalizes the input into a standard ComputerUseArtifact record with kind, owner, and metadata.
The artifact is routed to its owner — a mission step, a PR, a Linear issue, or a chat session — based on the flags passed to the CLI.
The file is stored under .ade/artifacts/computer-use/ and linked in the database.
It appears in the Mission Artifacts tab, the PR attachments panel, the chat session artifact panel, or the Linear issue sidebar, depending on routing.

Relationships Between Concepts

Here is how all the core concepts connect in a typical workflow:

Project
├── Primary Lane
├── Worktree Lanes (1..n)
│   ├── Sessions (terminal + agent)
│   ├── Pack (context bundle)
│   ├── Checkpoints (immutable snapshots)
│   └── Conflicts ↔ other lanes
│
├── Stacks (chains of lanes)
│
├── Missions (1..n)
│   ├── Plan (generated by Planner)
│   ├── Steps → Workers → Sessions
│   ├── Interventions (human touchpoints)
│   ├── Artifacts (proof, summaries, PRs)
│   └── Mission Pack (audit snapshot)
│
├── CTO Agent
│   ├── Project Memory
│   ├── Workers (spawned into lanes)
│   └── Linear sync
│
├── Automations
│   └── Triggers → Missions or direct agent runs
│
└── Job Engine
    ├── Conflict prediction
    ├── Pack refresh
    └── Automation execution

Glossary

Term	Definition
ADE	Agentic Development Environment. The product.
Lane	Isolated git worktree + process environment, the fundamental unit of parallel work.
Primary Lane	The repository’s root working directory, always present.
Worktree Lane	A lane backed by `git worktree add`, managed by ADE under `.ade/worktrees/`.
Attached Lane	An externally created worktree imported into ADE for tracking.
Stack	A chain of lanes in a stacked PR topology.
Pack	A durable context bundle injected into agent prompts.
Checkpoint	An immutable snapshot of lane state at a session or commit boundary.
Session	A PTY terminal session with metadata, transcript, and delta tracking.
CTO	Always-on project-aware AI agent at the top of the agent org chart.
Mission	A structured multi-step AI execution unit with full lifecycle and audit trail.
Worker / Employee Agent	A sub-agent spawned by the CTO or a Mission to handle a specific task.
Automation	A trigger → executor rule that fires an agent in response to an event.
Automation execution surface	`agent-session`, `mission`, or `built-in-task`; each determines where results are stored and how much workflow structure is available.
Intervention	A mission pause point requiring human input to continue.
ADE CLI	The native action surface for agents — a local `ade` binary plus a JSON-RPC 2.0 server exposed by the desktop app at `.ade/ade.sock`.
Job Engine	ADE’s background scheduler for pack refresh, conflict prediction, and automation execution.
PR Convergence	ADE’s automated loop for resolving PR issues (review comments, CI failures) through AI-driven rounds until the PR is ready to merge.
Path to Merge	The dedicated convergence workspace tab inside each PR detail view.
Conflict	A predicted or actual merge conflict between two lanes.
Artifact / Proof	Evidence captured via `ade proof` (screenshots, recordings, browser traces, console logs, test reports).
Plan	The structured execution document generated by a Mission’s planner agent.
Phase	A stage in a Mission’s lifecycle (Planning, Execution, Validation, etc.).
Phase Profile	A reusable configuration of phases and their settings, applied to missions at launch.
Phase Card	The configuration unit for a single phase: model, budget, validation gate, approval requirement.
baseRef	The project’s primary integration branch (e.g., `main`). Configured in `ade.yaml`.
`.ade/`	The directory ADE creates at the repo root to store its metadata, worktrees, and artifacts.

Next Steps

Lanes Deep Dive

Everything about lane creation, templates, environment isolation, and proxy routing.

Missions Deep Dive

Phase profiles, budget management, interventions, and audit log export.

CTO Agent

Configure the CTO with Linear sync, persistent memory, and worker spawning policies.

ADE CLI

Review the native ADE CLI action surface and project readiness settings.

Welcome

Setup

Documentation Index

Lane

Stack

Pack

Checkpoint

Session

CTO

Mission

Automation

Worker

ADE CLI

Job Engine

PR Convergence

Conflict

Artifact

​Lane

Primary Lane

Worktree Lane

Attached Lane

​Stack

​Runtime context

​Checkpoint

​Session

​CTO

​Mission

​Mission Lifecycle

​Mission Statuses

​Interventions

​Automation

​Trigger Types

Git Events

Schedule (Cron)

File Changes

Webhook events

​Execution surface

​Worker / Employee Agent

​ADE CLI and Actions

​Job Engine

​PR Convergence

​Conflict

​Proof / Artifact

​Artifact Types

​Proof Capture Flow

​Relationships Between Concepts

​Glossary

​Next Steps

Lanes Deep Dive

Missions Deep Dive

CTO Agent

ADE CLI

Lane

Stack

Runtime context

Checkpoint

Session

CTO

Mission

Mission Lifecycle

Mission Statuses

Interventions

Automation

Trigger Types

Execution surface

Worker / Employee Agent

ADE CLI and Actions

Job Engine

PR Convergence

Conflict

Proof / Artifact

Artifact Types

Proof Capture Flow

Relationships Between Concepts

Glossary

Next Steps