DevSpec
DevSpec
Sign In
Start Your Project
All Docs/Autopilot Setup Guide

Autopilot Setup Guide

This guide connects a coding agent to DevSpec and configures safe implementation on your machine. A connection may stay live or run on demand, but DevSpec does not route action-item work to it. Each implementation starts from a current explicit user request and each agent reserves the requested item ids before claiming them.

What Autopilot means now

Autopilot is coding-agent capacity plus a consistent implementation contract:

  • persistent hosts can remain live and listen for exact-target authorized commands;
  • interactive/on-demand hosts run when a user invokes a work surface;
  • all hosts use reserve_work_items followed by claim_work_item;
  • repository, branch, test, and protected-path checks remain independent safeguards; and
  • commits and implementation evidence are recorded against the claimed item.

Being online, discovering a backlog item, or seeing an old reservation/assignment row never authorizes implementation. Automations are explicit owner-scoped reusable runs and remain separate from action-item work.

1. Prerequisites

  • A DevSpec account and project with at least one connected repository.
  • The repository cloned locally.
  • Git configured for the delivery behavior you intend.
  • A supported MCP-capable coding agent.
  • A read-write DevSpec MCP token.

2. Generate an MCP token

Open You → Connections, create a read-write MCP token, and store it securely. MCP tokens identify the user; each call resolves and checks the relevant project server-side.

3. Configure MCP

Most HTTP MCP clients use this shape:

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

Antigravity uses serverUrl instead of url. Use the DevSpec host where the token was created. Run verify_agent_connection after setup.

4. Install the provider integration

Install the current DevSpec plugin, extension, or skills for your host:

  • Claude Code or OpenCode for persistent capacity;
  • Cursor for an interactive IDE invocation;
  • Antigravity or Grok Build for an on-demand invocation; or
  • another MCP client that can follow the implementation contract.

Provider installation changes host plumbing only. It does not create an execution mode or permission to choose work.

5. Configure repository safeguards

Under Project Settings → Coding Agents configure:

  • target branch and branch prefix;
  • auto-push and auto-merge preferences;
  • unit, E2E, typecheck, and other test commands;
  • protected paths; and
  • project agent instructions.

These settings constrain authorized work. They are not implementation requests.

6. Check repository alignment

The runner compares its local repository and branch with the project's connected repositories:

  • Aligned — expected repository and branch.
  • Branch Mismatch — repository matches but branch differs.
  • Repository Not Found — expected repository is absent.
  • Manual Override — a user accepted the mismatch for this runner.

Alignment does not select work; it only determines whether repository mutation is safe after a request exists.

7. Start capacity and request work

Persistent host

Start the installed runner workflow. To request a batch directly, provide the ordered ids:

/autopilot.start --items=ID1,ID2,ID3

A host may remain live after startup, but it must not implement arbitrary discovered work. You can issue another request from the local host or use DevSpec Send to address an exact connection.

On-demand host

Invoke the work skill with a named action item:

/devspec-work <action-item-id>

For several items, explicitly list their ids and order in the invocation.

Remote conversation

Attach/register the connection, choose that exact connection in DevSpec Send, and ask it to implement named action items. The server checks the sender against the connection's current command_authority. The owner and configured project/allowlist delegates may be authorized; ordinary room messages remain advisory.

8. What the agent does

For an authoritative implementation request, every runner performs the same acquisition:

  1. reserve_work_items with exactly the requested ids in order.
  2. Inspect the response and report any skipped/unavailable ids.
  3. claim_work_item for the first reserved id.
  4. Create an isolated branch/worktree, implement, and run configured checks.
  5. Commit with [devspec:<id>].
  6. Deliver according to project settings.
  7. Call record_implementation with the final commit, affected files, summary, and testing evidence.
  8. Claim the next reserved id, if any.

The reservation batch and its internal assignment_id coordinate competing claims. They are not sent work, do not supersede the user's request, and cannot authorize a different item.

9. Monitoring

The dashboard can show:

  • connection presence/listening state;
  • repository alignment;
  • current claim/activity;
  • branch and commit evidence;
  • failures and released claims; and
  • implemented work awaiting verification.

It observes state; it does not choose the next item for a runner.

10. Controls and automations

  • Typed connection controls (abort, model, thinking, compact, teardown) are owner-authority lifecycle operations.
  • Conversational commands use exact-target per-message server decisions and may come from an authorized owner or delegate.
  • Automation runs are explicit owner-scoped reusable jobs surfaced separately from action-item acquisition.
  • None of these surfaces turns presence or an internal reservation record into a work router.

Troubleshooting

The runner is live but idle

That is normal. Invoke a work surface with named ids or send an authorized exact-target command. Idle capacity does not pull arbitrary backlog work.

The command was advisory

Check that Send targeted the exact connection and that the sender is currently authorized by command_authority and project membership/grants.

Reservation or claim failed

Read the returned reason. Another agent may hold the item, or a dependency, conflict, assignee, or lifecycle guard may reject it. Do not force through or substitute a different item silently.

Branch mismatch / repository not found

Align the local checkout, or use the explicit override only when you accept the risk.

Tests or protected paths failed

Record the failure and partial-work notes. Fix the request or repository condition, then invoke the named work again.

The item was implemented but is not done

Report the lifecycle returned by record_implementation. Verification and done authority remain separate from implementation.

Historical note

Older setup guides instructed runners to poll a staged backlog and fetch an unspecified next item. That architecture is historical and non-normative. Old labels may survive in screenshots, command names, database history, or plugin releases; current hosts require an explicit request and reserve the named work before claiming it.