Autopilot

The DevSpec Autopilot is an autonomous agent that picks up action items marked as ready for automation, implements the required code changes, runs tests, and pushes the results back to the branch you started on. Runners are validated against your project's connected repositories to prevent work from being done against the wrong codebase or branch.

Staging Action Items

Any open action item can be staged — the act of staging is the readiness decision. Items display two buttons: "Stage for Autopilot" (fully autonomous execution) and "Request Agent Plan" (the agent analyzes the item and proposes a plan for your review before implementing). Stage an item and the next polling cycle picks it up. The rare exception is items marked human-only — pure off-platform work (call the lawyer, buy the domain) that agents never pick up. If an item has blocking dependencies, it will remain staged (held) until all of its blockers have been completed — the autopilot automatically respects the correct execution order.

Intelligent Ordering & Conflict Blocking

Staged work is not processed as a simple first-in, first-out list. When you stage work, DevSpec analyzes the staged items and orders them intelligently — higher-priority items rise to the top, and the work is sequenced so that prerequisites are implemented before the items that depend on them. A runner always picks up the next eligible staged item from this ordering, so the most important, unblocked work is picked up first.

DevSpec also holds back items that would conflict with work already in progress. If a staged item overlaps with a task a runner has already claimed — for example, it touches the same files, or it is a sibling of an in-progress item under the same brief — it is held until the conflicting work finishes. This prevents two runners from editing the same code at the same time and producing a merge conflict. Held items are picked up automatically once the conflicting task completes; you do not need to re-stage them.

Conflict blocking is automatic and based on overlapping scope. It is distinct from the explicit "blocks" relationships you can set between action items, which enforce a deliberate execution order — see Action Items → Dependencies & Blocking. Both mechanisms keep staged work running in a safe order.

Planning Mode

For complex items, use "Request Agent Plan." The autopilot reads the codebase, analyzes the item, and writes a proposed implementation plan as an implementation note. You review the plan in DevSpec and either approve (advances to staged for execution) or reject (resets to no agent status).

Action Item Lifecycle

Every action item follows a workflow from creation to completion. The status badges you see on action items reflect where they are in this lifecycle. Understanding these states helps you use Autopilot effectively.

Workflow States

• No Status — The item has just been created. You can choose to Stage it (immediate execution) or request a Plan (human-driven review).
• Planning — A human writes an investigation or implementation plan in the item notes. Another team member reviews it. This is a human-driven process; the autopilot does not pick up planning items. When the plan is ready, click "Approve & Stage" to send it to execution.
• Staged — The item is staged for automation, waiting for the next available autopilot runner to pick it up. Items are processed one at a time in priority order.
• In Progress — The autopilot has claimed this item and is actively implementing the changes. You can see which runner is working on it from the dashboard.
• Awaiting Approval — The item has been planned or investigated and needs human review before execution. Click "Approve & Stage" to proceed or "Reject" to cancel.
• Awaiting Verification — The autopilot has completed the work. A human must verify the result before the item is marked done. You can verify, request changes (re-stages the item), or verify with a follow-up.
• Completed — The work is done. The commit, branch, and implementation notes are available on the item detail page.
• Deferred — The item has been consciously parked for later. Autopilot skips deferred items; they sit in the Deferred lane until you Resume them (which re-stages them). Deferring is reversible and, unlike dismissing, keeps the work — it just stops the item holding its brief open.
• Failed — Something went wrong during execution. Check the error message on the item detail page, refine the description if needed, and click "Retry" to re-stage.

Common Workflows

• Fast path: Stage → In Progress → Awaiting Verification → Done. Best for clear, well-defined items.
• Human-driven planning: Plan → Awaiting Approval → Stage → In Progress → Awaiting Verification → Done. Best for complex items that need human design input first.
• Direct execution: Stage → In Progress → Done. When verification is not required.

Gathering Info is a planned workflow where the autopilot investigates an item first (reads code, checks logs), writes findings back, and waits for your approval before executing. This is distinct from Planning, which is human-driven. This workflow is coming soon.

Runner Validation

When a runner connects, DevSpec validates its local repository and branch against the repositories connected to your project. Each runner is classified into one of four states:

• Aligned — The runner's repository and branch match the project. Work proceeds normally.
• Branch Mismatch — The runner has the correct repository but is on a different branch than expected (e.g., on staging when the project expects main). The runner is gated from picking up work.
• Repository Not Found — The runner's workspace does not contain any of the project's expected repositories. The runner is gated from picking up work.
• Manual Override — A team member has acknowledged and accepted a mismatch. The runner can pick up work despite the mismatch.

Validation uses your project's connected repositories (from the Add Repository page) and their default branches. You do not need to configure anything extra — if your project has repos connected, validation is automatic.

Overriding a Mismatch

If a runner shows a Branch Mismatch or Repository Not Found state, you can override it from the runners dashboard. Click the override button on the runner card to open a confirmation dialog explaining the specific risk. For branch mismatches, the dialog explains that worktrees will be created from the wrong base. For repository mismatches, a mandatory checkbox ("I understand and accept responsibility") is required before confirming. Overrides are visible to all team members and reset automatically when the runner disconnects or changes branch.

Mismatch Notifications

When a runner has a mismatch, a warning banner appears at the top of the autopilot page identifying the runner, the expected configuration, and the actual state. Each mismatch gets its own banner with a "Review Runner" button that takes you directly to the runner card. Banners dismiss automatically when the mismatch is resolved.

Verification & Review Workflow

Autopilot supports a human-in-the-loop review gate. When verification is enabled (per-item or via project workflow rules), completed items are routed to "Awaiting Verification" instead of being marked done. A reviewer can then verify the work, request changes (which re-stages the item with feedback), or verify with a follow-up action item.

How it works

• Enable verification per item by toggling "Requires Verification" on the action item, or set project-wide rules in Settings → Workflow Rules.
• When autopilot completes an item with verification enabled, it enters "Awaiting Verification" status.
• The verification panel shows the implementation notes, commit reference, and branch link.
• "Verify" marks the item as done. "Request Changes" re-stages it with your feedback so autopilot can try again.
• "Verify with Follow-up" marks the item as done and creates a new action item for remaining work.

Approval Gates

For higher-risk items, enable "Requires Approval" to add a pre-execution gate. These items enter "Awaiting Approval" before being staged. An authorized approver must approve the item before autopilot will pick it up.

Configuration

Open Project Settings → Coding Agents for execution settings: branch prefix, test commands (unit, e2e, typecheck), protected file paths, and under Autopilot the polling interval. Project agent instructions (durable team rules for Dev, MCP, remote control, and autopilot) live under Project Settings → General. The merge target branch is determined automatically — the autopilot merges back into whatever branch it started on.

Monitoring Results

Each action item shows its agent status as a badge (planning, staged, in progress, completed, failed). Completed items display links to the branch and commit. Failed items show the error message and offer a Retry button. The Autopilot Runs dashboard shows aggregate metrics including success rate and average duration. The runners panel shows each runner's repository, branch, and validation state in real time.

Troubleshooting

If items fail: check the error message on the action item detail view. Common causes include vague descriptions (the agent reports "Requires human judgment"), protected path violations, and test failures. Refine the action item description and retry. If a runner shows "Branch Mismatch," either switch your local branch to match the project's default branch or use the override flow. If the autopilot process crashes, stale claims are automatically detected and marked as failed after the configured timeout (default: 30 minutes).