> ## Documentation Index
> Fetch the complete documentation index at: https://ade-ac1c6011-ade-im-seeing-error-messag-eright-58df792e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Isolated worktree + environment.
Chained lanes for stacked PRs.
Audit/replay artifact under `.ade/artifacts/packs/`.
Immutable execution snapshot.
Terminal session with metadata.
Always-on orchestrator agent.
Structured multi-step AI unit.
Trigger-driven execution rule.
Scoped sub-agent that writes code.
Native action surface for agents.
Background task scheduler.
Automated PR-to-merge loop.
Predicted or actual merge conflict.
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.
The repository's main working directory. Every project has exactly one Primary Lane — it represents the cloned repo root itself. Cannot be deleted.
A git worktree created by ADE under `.ade/worktrees//`. Fully managed by ADE: created, configured, and cleaned up via the Lanes UI.
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:
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.
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.
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
```
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.
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.
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.
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
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.
Fires on a cron schedule. Example: run a dependency audit every Monday at 8am.
Fires when specific files or patterns change. Example: regenerate the API documentation whenever `openapi.yaml` changes.
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:
Stage files, commit, push, create branches, run merge simulations, cherry-pick, and manage stashes — all with full attribution back to the calling agent.
Read and write files across any lane's worktree. File writes are atomic and logged as session deltas.
Spawn a new PTY session in a specific lane, write input, and read the output transcript.
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.
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.
Create worker runs, update step status, add artifacts, create interventions, and report progress back to the Worker run coordinator.
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
Everything about lane creation, templates, environment isolation, and proxy routing.
Phase profiles, budget management, interventions, and audit log export.
Configure the CTO with Linear sync and worker spawning policies.
Review the native ADE CLI action surface and project readiness settings.