How work flows through DevSpec

DevSpec follows one loop: you talk a change through in a session, it becomes tasks with acceptance criteria, a person hands those items to an agent, the agent builds and pushes the change, your host deploys it, and someone checks it works. Because every step is recorded in the same project, the agent works from the whole discussion rather than a one-line ticket, and nobody has to chase what shipped.

This page explains each stage: who does it, and where you see it in the app.

The loop at a glance

Stages 1 and 2 need only a project. Stages 3 and 4 need an agent connected and a repository for it to work in. Stage 5 needs a deployment target; without one, finished work is ready to check as soon as your agent records it.

Dev never edits code, commits, pushes or starts an agent. Your agent never marks work done. Those limits are what keep a person in charge of what gets built and what counts as finished.

Talk the change through in a session

Work starts in a session, a conversation room inside the project where your team, Dev and your agents can all take part. Type or speak, and bring in whoever the decision needs.

Dev reads your code, searches the project's tasks, memories and past sessions, checks your database schema and logs when those are connected, and looks things up on the web. It gives you its own view, including trade-offs you may not have considered, so the plan is grounded in how your code works today.

Deciding here rather than in a chat app matters later. The whole conversation stays with the project, so when an agent starts the work it can read why the change is wanted, what was considered and what was ruled out, not only what to build. Decisions worth keeping beyond the conversation can be recorded as memories, which every later session and agent can find.

See Sessions and Dev, your assistant in sessions.

Record the work as tasks with acceptance criteria

When the room agrees what to build, ask Dev to write it up. Dev proposes the tasks and waits until you tell it to create them. An agent in the room can record items too.

Each task carries:

• an intent: why the work matters
• a description: what to do
• acceptance criteria: how you'll know it's done

Related items are grouped under a brief, which completes when its items do. The criteria are what the agent works towards and what the check at the end is measured against, so it's worth reading them before you hand the work over.

New items appear in the session's Work tab, linked back to the conversation they came from, and on the project's Tasks page. See Tasks.

Hand the work to an agent

A person always decides when work starts. Nothing is sent to an agent because it's connected or idle: an agent works only on the items someone asks it to. Dev can't hand work over either; it points you to the options below.

You can hand items over in four ways:

• From one item: choose Agent command (the terminal icon), then Send to an agent and pick an agent. DevSpec opens a session and delivers the request there. Or use Or copy a command and paste it into your agent's terminal.
• Several at once: on Tasks, choose Hand off, tick the items (or use Pick a parallel set to select items that can safely run side by side), then Send to agent.
• In a session: bring the agent into the room, pick it in Send to and ask it to work on the items.
• In your agent's terminal: ask it to work on the items by name.

The agent marks the items it takes so other agents skip them. On the item you'll see Reserved while it waits and Working once the agent has started. If an agent goes offline after starting an item, use Release claim on the item so another agent can take it.

New agents default to Only you, and you can open an agent to Anyone on the project or Chosen people so teammates can talk to your agent and bring it into their sessions while it's idle. See Working with your agents.

How your agent builds and pushes the change

Your agent (Pi, Claude Code or Antigravity CLI) runs on your machine. For each item, it:

1. reads the item, its criteria and the conversation it came from
2. works in its own copy of the repository on a new branch, so your checkout is untouched
3. commits with the item's tag, [devspec:<id>], so DevSpec can link each commit to its item
4. pushes, following the project's settings
5. records what it did and the evidence for each criterion, then stops at Implemented

The Agents page shows which agents are connected and what each is holding under Work in flight.

What happens to the branch

Project settings → Agent rules controls what the agent does with its branch (Maintainers edit these):

• Auto-push (on by default): push the work branch after committing.
• Auto-merge (on by default): merge the work branch into the repository's tracking branch and push.
• Branch prefix (work/task- by default), Commit message prefix, Protected paths (files agents must not change) and Agent execution rules (the checks and conventions agents follow).

Each repository's Tracking branch is set in Project settings → Repositories, and it's pre-filled with the repository's default branch. So out of the box, agent work merges straight into your default branch. If your host deploys that branch automatically, the change goes live with no one reviewing it first.

To review each change before it lands, turn off Auto-merge: the agent pushes its work branch, and you merge it through your usual review. A separate staging branch lets you try changes before promoting them to production.

When a change needs someone's OK

New work is checked against decisions the project has already made. If it would undo someone else's protected decision, the item shows whose OK it needs. Your agent can build and push it on its own branch while you discuss it, but must not merge it into the tracking branch.

Open the linked question to see the decision and the work that would change it. The person who can decide can let it go ahead, say no with a reason, or explain that it does not undo the decision. You can also ask Dev or your agent to record your answer in conversation.

An Experiment lets you try an approach on its own branch before asking for it to land. Neither an experiment nor work waiting for an OK reaches Done until the approvals are in place and it has landed. See Review.

How deploys are linked back to your items

Connect your host under Project settings → Integrations → Deployment targets. DevSpec supports Vercel and Coolify. Each deployment target belongs to one repository and follows its tracking branch.

When your host deploys, it notifies DevSpec, and DevSpec links the deploy to the tasks it contains using the commit tags. You see every deploy on the Delivery page. When a deploy that contains an item succeeds:

• the item's assignees (or, if it has none, the person who created it) can be notified that it's live and ready to verify; each person turns this on under Deployments → Successes in Settings → Notifications
• the item shows the successful deploy in its Linked activity, live and ready to check
• if the agent never recorded its work, the successful deploy moves the item to Implemented anyway

For Coolify without an API token, DevSpec works out which commit was deployed from the branch on GitHub at deploy time. For the exact commit, add your Coolify instance's base URL and an API token with read access to the target. Vercel sends deploy notifications only on its Pro and Enterprise plans.

See Delivery and Commit tracking.

When a deploy fails

DevSpec doesn't retry or roll back deploys; your host stays in charge of that. What DevSpec does is make the failure visible and help you hand it back:

• The failed deploy shows on the Delivery page with its linked items.
• When the latest deploy on a target has failed, the project Overview lists it under Needs attention as Deployment failed, with the commit message.
• When the target has an API token that can read build logs, DevSpec attaches an excerpt of the log to the linked item's activity. Without one, the item notes that the build logs were unavailable, and you check your host directly.

To get it fixed, open the failed deploy on Delivery. For a linked item, its Agent command offers Fix build, which you can send to an agent or copy. For a deploy that isn't linked to any item, choose Copy fix-build prompt and paste it into your agent. Once a later deploy succeeds, the item is ready to test again.

Repositories without a hosted deploy

Not every repository ships to a host. A library, a command-line tool or anything you release by hand has no deploy for DevSpec to watch, and that's fine.

Each repository has a Delivery signal setting on its card in Project settings → Repositories:

• Hosted deployment: a deploy to your host marks the work live. This is the one DevSpec tracks automatically, through a deployment target.
• I deploy or release manually: you ship by hand.
• No external delivery signal: the repository has no ship or release step.

In a project with no deployment target, finished work is ready to check as soon as the agent records it. In a project that has a deployment target, an implemented item's page says when the last deploy went out, so nobody checks work that hasn't shipped yet.

Check the work

Implemented work waits under Implemented on the Tasks page. Open an item and its page has everything the check needs: what changed, its acceptance criteria, How to check steps, and where its deploys landed.

When you've tried it, record a verdict in the item's Verification section:

• Verify marks the item done.
• Found a problem asks what went wrong; submit your note with Send back. The note is saved on the item, which returns to available work with an attempt count. Nothing is sent to an agent until someone hands the item over again: its Agent command then offers Fix this, which points the agent at your feedback.

See Record a verdict.

By default, people whose project role allows verification can verify work. To limit who can, open the project's Members page and set Who can verify. The same rule applies wherever a verdict can be recorded: on the item's page, to Dev in a session and to your agents. See Who can verify work.

How an item reaches Done

An implemented item with any required approvals, delivery and follow-up steps complete reaches Done in one of two ways:

• Someone verifies it, with Verify on the item.
• The evidence settles it. When every acceptance criterion has been checked and the result recorded, by your agent or by Dev running the check, the item moves to Done by itself.

Your agent records its work and evidence, but it never marks work done. A brief is never verified directly: it completes when its items do. If an item was verified by mistake, Undo next to its verified stamp takes it back. Shipped items appear on the Changelog page, marked Verified once they are done, and opening one shows its commits and notes. See Changelog.

What the loop costs

Your agent's model usage is billed by its own provider, under your own subscription or API key, not by DevSpec.

DevSpec charges your organization's prepaid balance, in dollars, for the work it does in the loop: Dev's replies in sessions (these count toward each person's personal allowance, if one is set), and the background work of indexing your code and reading your commits and deploys. Posting to a session room is free, a Dev reply you stop isn't charged, and the first full index of your organization's first repository is free. See Billing, usage and limits.