Key Concepts

A comprehensive reference for every core ADE concept: Lanes, Stacks, Packs, Checkpoints, Sessions, the CTO, Workers, Automations, ADE CLI, the Job Engine, Conflicts, and Artifacts.

Lane

Isolated worktree + environment.

Stack

Chained lanes for stacked PRs.

Pack

Audit/replay artifact under .ade/artifacts/packs/.

Checkpoint

Immutable execution snapshot.

Session

Terminal session with metadata.

CTO

Always-on orchestrator agent.

Worker run

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, worker run details, 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 Worker run’s Planning phase. Captures the worker run’s goal, steps, assumptions, risks, and executor assignments. Serves as the authoritative reference for all workers during execution.

Worker run Pack

A deterministic snapshot of a worker run at a specific point in time — used for resume, audit, and replay. Contains the full worker run 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 worker run/step linkage. Every terminal window ADE opens is recorded. The History view groups sessions by lane, worker run, 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 coordinates work across lanes and worker agents.

The CTO can:

• 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-worker run token spend, enforce limits
• Surface risks — proactively flag conflict risks, stale lanes, and budget overruns
• Conduct retrospectives — periodically review what worker runs succeeded and what failed

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.

---

Worker run

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

Workers 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 worker runs end-to-end. The Automations tab mirrors this: the worker run execution surface is shown but disabled in packaged builds.

Worker run Lifecycle

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

1. Planning

   A planner agent (Claude CLI or Codex CLI) reads the worker run 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.

2. Approval (optional)

   If the worker run 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.

3. Execution

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

4. Validation

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

Worker run 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 worker run 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 worker run 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 Worker run’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.
• worker run: launches a full worker run with planner, validation gates, intervention handling, and worker artifacts.
• built-in-task: runs a predefined ADE task without full worker run semantics.

Agent-session outputs appear in Automations → History. Worker run outputs appear in Workers.

---

Worker

A Worker is a sub-agent spawned by the CTO or by a Worker run 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 Worker run 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 worker run plan limits how many workers run at once.

---

ADE CLI and Actions

ADE CLI is the native action surface agents use to operate ADE. ade serve exposes the per-machine runtime endpoint at ~/.ade/sock/ade.sock, and ade can run one-off commands in headless mode when you explicitly bypass the machine runtime.

When an AI agent is running inside ADE (whether via Claude CLI, Codex CLI, or a local provider route), it can run ade commands against the same runtime surface as the desktop app and ade code 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 and write the audit/replay packs under .ade/artifacts/packs/ (Conflict Pack, Plan Pack, Worker run Pack). These are records of work for audit and replay — they are not prepended to agent prompts.

Worker run management

Create worker runs, update step status, add artifacts, create interventions, and report progress back to the Worker run coordinator.

Computer-use artifacts

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

Sessions are authenticated by role: orchestrator, agent, external, or evaluator. Coordinator-level tools (spawning agents, creating worker runs) 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:

• Conflict pack refresh — regenerates the audit Conflict Pack for a lane pair when their overlapping changes shift, so resolver context stays accurate
• 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 worker run 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:

1. The agent runs ade proof screenshot, ade proof record, or ade proof ingest from a terminal inside its lane.
2. ADE’s artifact broker in the main process normalizes the input into a standard ComputerUseArtifact record with kind, owner, and metadata.
3. The artifact is routed to its owner — a worker run step, a PR, a Linear issue, or a chat session — based on the flags passed to the CLI.
4. The file is stored under .ade/artifacts/computer-use/ and linked in the database.
5. It appears in the Worker run 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)
│   ├── Checkpoints (immutable snapshots)
│   └── Conflicts ↔ other lanes
│
├── Stacks (chains of lanes)
│
├── Workers (1..n)
│   ├── Plan (generated by Planner)
│   ├── Steps → Workers → Sessions
│   ├── Interventions (human touchpoints)
│   ├── Artifacts (proof, summaries, PRs)
│   └── Worker run Pack (audit snapshot)
│
├── CTO Agent
│   ├── Project Memory
│   ├── Workers (spawned into lanes)
│   └── Linear sync
│
├── Automations
│   └── Triggers → Workers or direct agent runs
│
└── Job Engine
    ├── Conflict prediction
    ├── Conflict 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	An audit/replay artifact stored under .ade/artifacts/packs/ (Conflict Pack, Plan Pack, Worker run Pack). Records work for audit and replay; not 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.
Worker run	A structured multi-step AI execution unit with full lifecycle and audit trail.
Worker	A sub-agent spawned by the CTO or a Worker run to handle a specific task.
Automation	A trigger → executor rule that fires an agent in response to an event.
Automation execution surface	agent-session, worker run, or built-in-task; each determines where results are stored and how much workflow structure is available.
Intervention	A worker run pause point requiring human input to continue.
ADE CLI	The native action surface for agents: a local ade binary that talks to the machine runtime at ~/.ade/sock/ade.sock or runs explicit headless one-off commands.
Job Engine	ADE’s background scheduler for conflict prediction, conflict pack refresh, 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 Worker run’s planner agent.
Phase	A stage in a Worker run’s lifecycle (Planning, Execution, Validation, etc.).
Phase Profile	A reusable configuration of phases and their settings, applied to worker runs 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.

Workers Deep Dive

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

CTO Agent

Configure the CTO with Linear sync and worker spawning policies.

ADE CLI

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