All Docs/Autopilot Setup Guide

Autopilot Setup Guide

This guide walks you through setting up DevSpec Autopilot for the first time. By the end, you will have an AI coding agent connected to your DevSpec project that automatically picks up action items, implements code changes, runs tests, and pushes results — all while validating that it is working against the correct repository and branch. DevSpec supports Claude Code, Antigravity, Cursor, and Grok Build as runner providers.

What is Autopilot?

DevSpec Autopilot connects AI coding agents to your project so they can autonomously process action items. Runners poll your DevSpec project for staged work, claim items one at a time, create isolated git branches, implement the changes, run your test suite, and push the results. You control what gets automated and can monitor everything from the DevSpec dashboard.

How it works

A runner connects to your DevSpec project via MCP (Model Context Protocol) using an API token.
It checks for staged action items — continuously (Claude Code) or on-demand (Antigravity, Grok Build, Cursor).
When it finds one, it creates a git branch, implements the changes, runs tests, commits, pushes, and optionally merges.
It sends a heartbeat so you can see it on the dashboard in real time.
The runner validates that your local repository and branch match what the project expects before picking up any work.

Supported providers

Claude Code — Persistent runner. Polls continuously in the background using git worktrees for isolation. Best for always-on automation.
Antigravity — Ephemeral runner (Google's agent). Processes one item per invocation via skills and exits. Best for on-demand processing.
Cursor — Interactive extension. Command-palette driven, one item per invocation.
Grok Build — Ephemeral runner with skills. Interactive TUI or headless one-shots.
Any MCP client — DevSpec's MCP-based architecture means other agents that support MCP tool calling can connect too.

Each runner instance connects to exactly one DevSpec project at a time. The connection is defined by your MCP configuration and API token.

1. Prerequisites

Before you begin, make sure you have the following:

Common requirements

A DevSpec account with at least one project that has a repository connected
The repository cloned locally on your machine
Node.js 18 or later installed
Git configured and authenticated (able to push to the remote)

For Claude Code

Claude Code installed (v2.0 or later)

For Antigravity

Antigravity CLI (agy) and/or desktop app installed from antigravity.google
DevSpec skills installed (see step 4)

2. Generate a DevSpec API Token

The autopilot plugin communicates with DevSpec through an MCP endpoint that requires an API token. You need to generate one from your project settings.

Open your DevSpec project and navigate to Project Settings.
Find the API / MCP section.
Click "Generate Token" and select the read_write scope. Autopilot needs write access to claim items, report results, and send heartbeats.
Copy the token immediately — it starts with dvs_ and is only shown once.
Store it somewhere safe (e.g., a password manager). If you lose it, you will need to generate a new one.

The token is scoped to a single project. If you work on multiple projects, you will need a separate token and MCP configuration for each.

3. Configure the MCP Connection

Each provider has its own way of configuring the MCP connection to DevSpec. Follow the instructions for your chosen provider.

Claude Code

Create or edit the .mcp.json file in your project root (the same directory as your repository):

{
  "mcpServers": {
    "devspec": {
      "type": "http",
      "url": "https://devspec.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dvs_your_token_here"
      }
    }
  }
}

Antigravity

CLI — merge into ~/.gemini/antigravity-cli/mcp_config.json (note the serverUrl key):

{
  "mcpServers": {
    "devspec": {
      "type": "http",
      "serverUrl": "https://devspec.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dvs_your_token_here"
      }
    }
  }
}

Desktop — Settings → MCP → Add server (HTTP), paste the same URL and Authorization header.

Replace dvs_your_token_here with the actual token you generated in the previous step. If you are using a staging or self-hosted instance, replace the URL accordingly.

The token determines which DevSpec project the runner connects to. You cannot connect to multiple projects simultaneously from the same session.

4. Install the Runner Plugin / Extension

Each provider uses a plugin or extension to add the autopilot workflow.

Claude Code

Install the plugin directly from Claude Code:

/plugin install devspec-autopilot@devspec-autopilot-marketplace

This is a one-time install. The plugin will load automatically in every future Claude Code session — no extra flags needed. After installing, run /reload-plugins to confirm the plugin loaded.

Antigravity

Install the DevSpec skills from the Antigravity plugin:

./scripts/install.sh                  # ./.agents/skills
# or:
./scripts/install.sh --global         # ~/.gemini/antigravity/skills

Skills add workflows such as devspec-work, devspec-brainstorm, and devspec-autopilot. MCP still needs to be configured separately (step 3).

5. Configure Autopilot Settings in DevSpec

Before starting the autopilot, configure how it should behave in your DevSpec project settings.

Navigate to Project Settings and scroll to the Autopilot Configuration section. The key settings are:

Enabled — Toggle autopilot on or off for the project. Must be enabled for the runner to pick up work.
Branch Prefix — The prefix for feature branches created by autopilot (default: autopilot/action-item-). Each branch is named with this prefix plus the first 8 characters of the action item ID.
Auto Push — Whether to automatically push branches to the remote after committing (default: on).
Auto Merge — Whether to automatically merge the feature branch back into your working branch after pushing (default: on).
Test Commands — Commands to run before committing: unit tests, E2E tests, and typecheck. Only configure what applies to your project.
Protected Paths — File patterns the autopilot must never modify (e.g., .env*, package-lock.json). If the autopilot touches a protected file, it fails the item.
Polling Interval — How often the autopilot checks for new work in seconds (default: 60).
Project Agent Instructions — Durable team rules for every agent (in-app Dev system prompt, MCP, remote control, and autopilot). Edited under Project Settings → General only (Coding Agents links there). Use this for engineering principles and conventions (e.g., "No hack workarounds", "Prefer Clerk/Supabase over custom auth"). Not personal chat style — that lives in Account → Chat Response Style.

6. Check Your Repository and Branch

This is a critical step. The autopilot validates that your local repository and branch match what your DevSpec project expects. If they do not match, the runner will be gated from picking up work.

DevSpec compares your local environment against the repositories connected to your project (the ones you added via the Add Repository page). It checks two things:

Repository — Is the same repository (by remote URL) present in your local workspace?
Branch — Are you on the default branch configured for that repository?

For example, if your project has DevSpecAI/DevSpecV2 connected with a default branch of main, your local checkout must be the same repository on the main branch. If you are on staging or a feature branch, the runner will show as "Branch Mismatch" and will not pick up work.

You can override a mismatch from the DevSpec dashboard if you intentionally want to work on a different branch. But for most users, simply being on the correct branch is the simplest path.

How to verify

cd /path/to/your/repo
git branch --show-current
# Should output the expected branch (e.g., main)

7. Start Autopilot

Open your chosen AI agent in your repository directory and run the autopilot command.

Claude Code (persistent polling)

/autopilot.start

Claude Code enters a continuous polling loop. You will see the startup sequence:

It fetches your project settings from DevSpec.
It discovers the local repositories and branches in your workspace.
It sends an initial heartbeat to register the runner on the dashboard.
It displays a startup banner showing your configuration.
It enters the polling loop, checking for work every 60 seconds.

What the startup banner looks like

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ◆  DEVSPEC AUTOPILOT  ▸  ONLINE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  host: YOUR-PC  ·  session: abc...1234
  repo: YourRepo → main (7abccf0)
  interval: 60s
  push: on  ·  merge: on  ·  prefix: [autopilot]
  tests: typecheck
  protected: .env*, package-lock.json
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Antigravity (single invocation)

Use the devspec-autopilot skill

Or work a specific item:

/devspec-work <action-item-id>

Antigravity processes one item (or a named item) and exits. Re-run the skill to process the next item.

What to Expect When It Works

Once autopilot is running and your branch is aligned, here is what you will see:

On the Dashboard

Your runner appears in the Active Runners section with a green "Aligned" badge.
The runner shows its hostname, repository name, branch, and uptime.
When it picks up work, the status changes to "Working" with the current task title.
Claude Code runners show as "online" or "offline". Ephemeral runners (Antigravity, Grok Build) show as "last active X minutes ago" since they exit after each invocation.

In Claude Code

Idle cycles appear as a single line: ▸ Cycle 3 · idle followed by the timestamp.
When work is found, you see step-by-step progress: claiming, creating worktree, implementing, testing, pushing, merging, and cleanup.
Each completed step shows a checkmark. Failures show the error.

In Antigravity

Antigravity displays the action item details and works through each step sequentially (worktree, implement, test, push/merge, report).
On completion, it prints the commit SHA, branch name, and file count.
If nothing is staged, it prints that there is nothing to process and exits.

In DevSpec

The action item status changes from "Staged" to "In Progress" to "Completed".
Completed items show the branch name, commit SHA, and which provider processed them.
Implementation notes document what was changed and why.

What to Expect When Something is Wrong

Here are the common issues and what they look like:

Branch Mismatch

If your local branch does not match the project's expected branch, the runner shows an amber "Branch Mismatch" badge on the dashboard. A warning banner appears at the top of the autopilot page. In Claude Code, the runner continues heartbeating but skips work-claiming. Fix: switch to the correct branch locally, or override the mismatch from the dashboard.

Repository Not Found

If your local workspace does not contain the project's connected repository, the runner shows a red "Repository Not Found" badge. Fix: make sure you are running Claude Code from the correct directory (the one containing the repository).

Runner Not Appearing on Dashboard

If the runner does not appear on the dashboard, check: Is the MCP connection working? (Claude Code: try running /autopilot.status. Antigravity: run /mcp and confirm devspec is listed). Is autopilot enabled in project settings? Is the API token valid and not revoked?

Action Items Not Being Picked Up

Items must be staged (agent_activity = "staged") to be picked up. Check that you have clicked "Stage for Autopilot" on the action item in DevSpec. Also verify the runner is in "Aligned" or "Manual Override" state — mismatched runners will not claim work. If items are staged but still not picked up, check for unresolved blocking dependencies — staged items whose blockers have not reached "done" status are held and skipped. Verify or complete the blocking items first to unblock them.

Task Failures

If a task fails, check the error on the action item detail page in DevSpec. Common causes: vague description ("Requires human judgment"), test failures (typecheck/unit), protected path violations, or merge conflicts. Refine the description and retry.

Commands Reference

Each provider offers its own set of commands.

Claude Code commands

/autopilot — The full unattended loop. Polls DevSpec for staged items, implements them one at a time in isolated worktrees, and repeats until nothing is staged or you stop it.
/autopilot.start — Kicks off the polling loop. Checks that autopilot is enabled in project settings first, then displays a startup banner and begins cycling.
/autopilot.stop — Gracefully stops the loop after the current cycle completes. Prints a session summary (cycles run, completed, failed).
/autopilot.status — Snapshot of the current autopilot state: online/offline, staged-item count, items in-progress, and key settings.
/autopilot.history — Lists recently completed and failed autopilot runs, sorted by most recent, with relative timestamps and branch names.

Antigravity skills

devspec-autopilot — Fetch the next staged item, implement it, and report results.
/devspec-work — Pick up a specific action item by id. Supports --unattended for fire-and-forget execution.
/devspec-brainstorm — Brainstorm an action item to refine scope and approach before implementing.
devspec-commit — Generate a deployment-tracked commit message.
devspec-done — Log completed work back to DevSpec with commits and testing notes.
/autopilot-status — Show staged / in-progress counts and push/merge settings.
autopilot-history — Show recent autopilot execution history.

How Autopilot Processes Work

Understanding the execution flow helps you write better action items and troubleshoot issues. The core cycle is the same across all providers.

The Execution Cycle

1. Claim — The runner claims the action item (sets status to in_progress) and reserves a branch name.
1. Branch — Creates a feature branch. Claude Code and Antigravity use an isolated git worktree so your working directory is never touched.
1. Implement — Reads the action item description and implements the changes. Follows your custom instructions and existing code conventions.
1. Test — Runs your configured test commands (typecheck, unit tests, E2E). If tests fail due to the changes, the item is marked as failed.
1. Commit & Push — Stages specific files, commits with your configured prefix, and pushes the feature branch.
1. Merge — If auto-merge is enabled, merges the feature branch back into the target branch and pushes.
1. Report — Updates the action item to "completed" with the commit SHA, implementation notes, testing notes, and a verification report.
1. Cleanup — Claude Code removes the worktree and starts the next cycle. Ephemeral runners (Antigravity, Grok Build) remove the worktree and exit.

Each runner processes one item per cycle. If an item fails, it reports the error. The next cycle picks up the next item — it does not retry the failed one automatically.

Tips for Best Results

The autopilot works best when action items are clear and specific.

Write action items with clear, specific descriptions. "Fix the login bug" is too vague. "Fix the login timeout by increasing the session TTL from 5m to 30m in src/auth/config.ts" is actionable.
Use the planning mode first for complex items. Request an agent plan, review it, then approve for execution.
Configure protected paths for files that should never be auto-modified (.env, lock files, CI configs).
Add custom instructions for project conventions the agent should follow.
Keep your local branch aligned with the project. If you switch branches, the autopilot will detect it and pause.
Monitor the dashboard during initial setup to verify heartbeats are flowing and validation is working.