Documentation Index
Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
How the CTO Uses Linear
The CTO owns ADE’s bidirectional Linear integration. It monitors your workspace for issue changes, routes them to the right execution target (worker, mission, or PR convergence), and pushes updates back when work completes — tracking the full lifecycle from intake to closeout based on configurable workflow definitions.Connecting Linear
Authenticate
Click Connect Linear. Choose between:
- OAuth (recommended) — authorizes ADE to access Linear on your behalf with scoped permissions. ADE stores the token securely using Electron’s safeStorage.
- Personal Access Token — paste a token from your Linear account settings (
Settings > API > Personal API keys)
Select projects and teams
ADE discovers your Linear workspace and lists accessible projects and teams. Select which ones the CTO should monitor. You can change this later without re-authenticating.
Configure workflow definitions
Set up workflow rules that map Linear events to ADE actions. Each workflow definition specifies:
- Trigger conditions — which issues match (assignee, labels, priority, team, state transitions)
- Execution target — what ADE does (launch a mission, start a worker session, open a PR convergence run)
- Lane selection — where the work happens (primary lane, fresh issue-specific lane, or operator-prompted)
- Closeout policy — what happens when the work completes (update issue state, add comments, apply labels)
Workflow Definitions
A workflow definition is the core configuration unit for Linear integration. Each definition describes a complete automation pipeline: which issues to act on, how to process them, and what to do when they complete.Trigger Conditions
Triggers filter which Linear issues a workflow applies to. You can combine multiple conditions — all must match for the workflow to fire.| Condition | Description |
|---|---|
| Assignees | Only issues assigned to specific users |
| Labels | Only issues with specific Linear labels |
| Project slugs | Only issues in specific Linear projects |
| Team keys | Only issues belonging to specific teams |
| Priority | Filter by priority level: urgent, high, normal, low, or none |
| State transitions | Fire only when an issue moves between specific states (e.g., from “Backlog” to “In Progress”) |
| Metadata tags | Custom tags added by the CTO for internal routing |
Execution Targets
When a workflow triggers, the CTO dispatches work to one of these targets:| Target | When to use |
|---|---|
| Mission | Complex issues that need a structured plan, multiple steps, and validation |
| Employee session | Issues where a single agent chat session can handle the work |
| Worker run | Background worker execution managed by the CTO |
| PR resolution | Issues that map directly to an existing PR that needs convergence work |
| Review gate | Issues that need human review before the CTO proceeds |
Lane Selection
| Mode | Behavior |
|---|---|
| Primary | Work happens in the primary lane (the main checkout) |
| Fresh issue lane | ADE creates a new lane specifically for this issue, branching from the default branch |
| Operator prompt | The CTO asks the human operator which lane to use before starting |
PR Timing
| Setting | Behavior |
|---|---|
| None | No PR is created automatically |
| After start | A draft PR is opened as soon as the first commit lands |
| After target complete | PR is opened only after the execution target reports success |
Closeout Policy
When a workflow run completes (successfully or not), the closeout policy determines what happens in Linear:- Success state — move the issue to this Linear state (e.g., “Done”)
- Failure state — move the issue to this state on failure (e.g., “Blocked”)
- Comments — add a completion or failure comment with configurable templates
- Labels — apply specific labels on completion
- Reopen on failure — automatically reopen the issue if the workflow fails
- Artifact mode — attach proof artifacts as Linear attachments or as links in comments
Inbound Flow (Linear to ADE)
When a Linear issue changes and matches a workflow trigger, the CTO processes it through a pipeline:Intake
The Linear sync service detects the issue change (new issue, state transition, assignment change). It normalizes the issue data and checks if it matches any enabled workflow.
Queue
Matched issues enter a sync queue. The queue deduplicates rapid changes (e.g., multiple quick state updates) and batches processing for efficiency. Issues that are already being processed or have reached a terminal state are skipped.
Routing
The CTO’s routing service evaluates which workflow to apply, resolves the execution target and lane selection, and prepares the dispatch context.
Dispatch
The dispatcher creates the execution target — starts a mission, opens a chat session, or launches a worker run. The issue’s description, comments, and attachments are injected as context.
Reconciliation
The sync service runs a periodic reconciliation loop (default: every 30 seconds) to catch any issues that were missed by event-based triggers. It compares the tracked issue state against Linear’s current state and re-queues any discrepancies.Outbound Flow (ADE to Linear)
The CTO pushes updates back to Linear through the outbound service:- Issue state updates — move issues to configured states when work completes or fails
- Workpad comments — maintain a persistent “workpad” comment on each issue that the CTO updates with progress notes, PR links, and analysis results. The workpad uses content hashing to avoid duplicate updates.
- New sub-issues — when the CTO discovers additional scope during implementation, it can create child issues in Linear
- Label management — apply or remove labels based on workflow outcomes
- Proof artifacts — attach mission artifacts, test reports, or screenshots as Linear attachments or comment links
Sync Dashboard
The Linear sub-tab in the CTO view shows a live sync dashboard with:- Queue status — how many issues are queued, processing, or completed
- Active workflow runs — which issues have in-flight execution targets
- Recent sync events — a timeline of all sync activity with issue IDs, event types, and outcomes
- Error log — any sync failures with diagnostic details
Linear vs. Automation Rules
Both the CTO’s Linear integration and Automation rules can react to Linear events. They serve different purposes:| Aspect | CTO Linear Integration | Automation Rules |
|---|---|---|
| Intelligence | Stateful — tracks issue lifecycle, makes routing decisions, manages workflow runs | Stateless — fires once per trigger, no memory of past events |
| Scope | Full workflow from intake to closeout | Single action per trigger |
| Configuration | Workflow definitions with triggers, targets, and closeout policies | Simple trigger-action pairs |
| Best for | Ongoing issue management, complex routing, PR convergence | Simple notifications, one-shot tasks, scheduled checks |
Automation rules that trigger on Linear events use the
linear.issue_created or linear.issue_updated trigger types (separate from the CTO’s sync). They do not conflict with the CTO’s workflows — both can be active simultaneously.Troubleshooting
Issues are not being picked up
Issues are not being picked up
Check that: (1) the workflow is enabled, (2) the trigger conditions match the issue (assignee, labels, team, priority), and (3) the issue is not in a terminal state (completed, canceled). Review the sync dashboard’s event log for diagnostic details.
OAuth token expired
OAuth token expired
Re-authenticate from the Linear sub-tab. ADE stores tokens securely but cannot refresh expired OAuth tokens automatically in all cases. If re-auth fails, try disconnecting and reconnecting.
Duplicate comments on issues
Duplicate comments on issues
The outbound service uses content hashing to prevent duplicate workpad comments. If you see duplicates, check if multiple workflow runs are targeting the same issue simultaneously. The sync dashboard shows active runs per issue.
Next Steps
CTO-Linear Workflow Guide
Step-by-step guide for setting up a complete CTO-driven Linear workflow from issue creation to PR merge.
CTO Workers
Learn how the CTO delegates execution to workers — the agents that do the actual coding work.