Tasks

A task is one tracked piece of work in a project: a bug to fix, a feature to build, a question to answer. It records why the work matters and how you'll know it's done, so whoever takes it on, a teammate or your agent, starts from the same understanding. The item then follows the work through to the check that it works.

You'll find a project's items under Build → Tasks in the project sidebar.

What a task holds

Every task has a type: Feature (something new), Improvement (making something better), Bug (fixing something broken), Investigation (producing findings or recommendations), or General (other work). General is the default: you can choose it and filter by it, but cards omit its badge. Beyond its title, a task can carry:

• Intent: why the work matters and the outcome it serves.
• Description: what to do.
• Acceptance criteria: a list of lines that say how you'll know the work is done. Each line is checked on its own (see Check acceptance criteria line by line).
• How to check: testing steps and where to find the change, so someone can try it.
• A priority (Low, Medium, High or Critical), a due date, tags, assignees and the goals it serves.

Each item is in one of these states:

Where tasks come from

There's no create button on the Tasks page. Items come from the places where work actually gets agreed or done:

• Dev, in a session. When a conversation settles some work, Dev proposes tasks and creates them once you say so, or straight away if you ask it to. Each item links back to the session it came from. See Sessions.
• Your agent. Pi, Claude Code or Antigravity CLI can record items too, when you ask it to or when it finds work that needs tracking.
• Commits that landed without an item. When a commit reaches a tracked branch without a link to an item, DevSpec reads the change and writes an item for it, marked Auto-tracked. These arrive as Implemented, because the work already happened, and wait for someone to check that the write-up is right. Reading each commit is charged to your organization's balance. See Commit tracking.
• Follow-ups. Spin off on a manual follow-up step and naming replacement work when you choose Not what I wanted create new items. Move to follow-up on a brief's child keeps the same item and moves it out of the brief.

To see where an item came from on the Tasks page, use the Requested by and Origin filters.

Reviewed Contributors propose new work for a Maintainer to accept. Contributors can organize work and record progress, but changes to what an agreed item asks for—its title, description, intent or acceptance criteria—need approval. The current specification stays in force while a proposal waits. Accepting a proposal makes the work available; it does not start an agent.

Briefs group related work

A brief is a parent item whose children are the work, such as a feature split into steps. Dev or your agent creates a brief when work breaks into parts. On the Tasks page a brief carries a Brief badge and a progress count, and its page lists Tasks in this brief.

You never verify a brief directly. It completes through its children and any acceptance criteria on the brief itself. Once its criteria are settled and every child is Done, Deferred or Dismissed, the brief follows on its own.

• If at least one child was delivered (Done), the brief is Done.
• Otherwise, if any child was parked, the brief is Deferred.
• Otherwise the brief is Dismissed.

Reopen a child and its brief reopens with it. If you decide you don't want the feature at all, the brief's page still offers Not what I wanted.

Find items on the Tasks page

The Tasks page opens on Open items. The Status menu groups every state with its count:

• All
• Needs you: Needs attention, for items waiting on a person. An item lands here when it's blocked, an agent's run on it failed, a check on its verification failed, or a required follow-up step is still open.
• In flight: Open, In progress, Implemented
• Settled: Done, Deferred, Dismissed

The other filters narrow the list further:

• Assignee: Me, Unassigned, Anyone (the default) or a named person.
• Requested by: the person who asked for the item, or how it was created: Someone asked, Nobody asked, An agent decided, A background job or Not recorded.
• Type: Feature, Improvement, Bug, Investigation or General.
• Origin: Planned first, or Written up from a commit for auto-tracked items.
• Created: from Any time to Last 90 days.
• Signals: Any signal, a group (Needs action, Lifecycle state) or one flag.
• Unblocked only: hides items that are waiting on other open items.

The search box ("Search items, or describe what you're looking for…") searches the whole project, and matches what you mean as well as the words you type. You can group the list By topic and sort it by priority, creation date, last activity, due date or, on the later states, when items were implemented or verified.

To select several items at once, turn on Hand off. Selection exists to hand work to an agent, so there are no bulk edits. See Hand items to an agent.

What's on an item's page

Click an item's title to open its page. From top to bottom it shows:

• The header: type, status, any flags, an Item ID button that copies the item's ID, and the ⋯ menu with actions such as Defer (park for later), Dismiss and Mark as implemented.
• Verification, once the item is implemented: its status and your verdict buttons.
• Manual follow-up steps, when there are any.
• Intent, Description, How to check and Acceptance criteria.
• Properties: created, last edited, due date, tags, Assignees and Human-only.
• Goals, with Link goal to connect the item to a goal. See Goals.
• Relationships to other items.
• Ask your agent, on done items: a prepared request for your agent to test, explain, debug or review the work on your machine.
• Linked activity: the Affected files, Commits, Pull requests and Deployments tied to the item.
• Tester notes, and the Activity history of changes, comments and verdicts.

Everyone on the project can read an item's page and comment on it. Use Discuss to open a session about the item and talk it through with your team or Dev.

Link related items

In the Relationships section of an item's page, press Link item, pick another item, and choose how they relate:

• Blocks: this item has to be finished before the other can start. An agent won't take an item while an item blocking it is unfinished, and the blocker has to reach Done or Dismissed; Implemented isn't enough. Filter these out with Unblocked only.
• Caused by: this item exists because of the other one, such as a bug introduced by earlier work. Each item keeps its own verification; verifying the fix does not sign off the earlier item.
• Related to: the items bear on each other. Nothing else changes.
• Supersedes: this item replaces the other one, and the other one closes. If it never shipped, it's dismissed. If its work shipped, it closes as done and superseded, never dismissed. If the other item has shipped and this one hasn't yet, the other reads Will be superseded until this one ships. The dialog says which of these will happen before you confirm. A Contributor's choice goes to a Maintainer to accept, and nothing changes until they do.

Dev and agents add relationships too, for example when they split work into steps that have to happen in order. You can also ask Dev or your agent to record that one item supersedes another.

A Duplicate of… is different: both records describe the same outcome. Preserve useful detail in the item you keep, then close the duplicate without claiming either was tested. Not a duplicate records that they are different and keeps both. Use Supersedes when newer work replaces an earlier approach, not merely when two records repeat it.

How an item reaches Done

An implemented item can reach Done once required follow-up steps, decision approvals, delivery and any open intent-review concerns are resolved:

1. Someone presses Verify, in the item's Verification section.
2. Automatically, once every acceptance criterion is settled by evidence: each line has a recorded result, any line that needs a person has been confirmed by a person, and no check on the item failed.

An item with no acceptance criteria can reach Done only through Verify.

Agents never mark work done: they stop at Implemented and record what they did. If you did the work yourself, choose Mark as implemented in the item's ⋯ menu and describe what you did. The item then waits to be checked like any other.

When an item reaches Done, its creator is notified if someone else verified it, and its Changelog entry, which appeared when it shipped, is marked Verified. A done item's Verification section says what settled it, and Re-open undoes a verification.

Record a verdict: Verify, Found a problem or Not what I wanted

The Verification section on an implemented item asks "does it work as intended?" and offers three verdicts:

• Verify ("Confirm this works and mark it done"): the item moves to Done, and its creator is notified. Undo, beside the verified stamp, returns the item to awaiting verification.
• Found a problem: describe what went wrong, paste a screenshot if it helps, then press Send back. A note is required. See What happens when you send work back.
• Not what I wanted: for work that's fine but that you don't want any more. Nothing is recorded as a failure. Give the title of the replacement work, which DevSpec creates as a new item, or say what changed, then press Supersede (or Supersede & create replacement). The item closes as superseded, and nothing claims anybody verified it.

Verify is unavailable while the item has a required follow-up step open. The Verification section then reads "Resolve the required follow-up(s) below, then you can verify." Resolve the steps under Manual follow-up steps first. See Manual follow-up steps.

Your verdict applies only to the item you checked. An item linked through Caused by still needs its own verification.

What happens when you send work back

When you choose Found a problem and press Send back, the item returns to In progress with your note attached, and its attempt count goes up. Your note appears under Previous attempts on the item's page.

DevSpec doesn't start the next attempt by itself. When you're ready, hand the item to your agent the usual way: from Hand off on the Tasks page, from the item's Agent command, or by asking the agent directly. When the agent takes the item, it receives your note and the earlier attempts, and when it has implemented the fix the item waits to be checked again.

The item also shows the Verification failed flag and sits under Needs attention on the Tasks page until it's reworked. See Hand items to an agent.

Who can verify work

Recording a verdict (Verify, Found a problem or Not what I wanted) needs the Contributor or Maintainer role on the project. Viewers can read and comment on items, but can't record verdicts.

A Maintainer can narrow this to named people on the project's Members page, under Who can verify. Switch people on to restrict verification to them. With nobody switched on, people whose project role allows verification can verify completed work. The list applies wherever a verdict can be recorded: on the item's page, to Dev in a session, and to connected agents. Someone who isn't on the list and tries to verify is told "You are not authorized to verify items in this project".

The list doesn't change how an item reaches Done automatically. That still follows the evidence recorded against the item's acceptance criteria.

Project settings are available on desktop only. See Organizations, members and roles.

Check acceptance criteria line by line

On an item's page, Acceptance criteria lists each line with its state. A checked line shows what was done and what came back. A line that's still outstanding says why, for example:

• "Nobody has checked this yet"
• "Needs a person to judge"
• "Checked and did not pass"
• "Backed by a code read rather than an observation"
• "Reworded since it was checked"

Your agent checks the lines it can when it records its work. A line that needs a person waits for you: press Confirm on the line, optionally describe what you saw, then press Confirm this line. From a line's ⋯ menu you can choose Mark as needing a person (with a reason) when a line can't be settled by a tool, or Treat as mechanical to undo that.

Confirming the last outstanding line can take an item to Done without anyone pressing Verify. That's the automatic path described in How an item reaches Done.

Check whether the work met its intent

Intent review asks whether the implementation delivers the outcome the item was created for, alongside the line-by-line acceptance criteria.

• Concern raised means something needs resolving before the item can finish. Use Resolve this concern and explain how it was addressed.
• No concern means the intent review found no issue; it is not verification by itself.
• Under Suggested criteria, Add to checklist adds a missing check. The new criterion still needs evidence. Declining a suggestion records your reason.

This is separate from Decision review, which asks whether the work would undo someone else's decision. See When work would undo a decision.

Manual follow-up steps

Some work needs a person after the code lands: applying a migration in production, rotating a secret, switching on a setting. Agents record these as manual follow-up steps, and they appear under Manual follow-up steps on the item's page.

A step marked Required blocks Verify until it's resolved. While one is open, the item shows the Follow-up required flag and sits under Needs attention, and its Verification section says "Resolve the required follow-up(s) below, then you can verify." with a Jump to steps link. Notes never block anything.

Resolve a required step with one of:

• I've done this: you did it.
• Not needed: it doesn't apply, with an optional reason.
• Spin off: turn it into its own linked task.
• Make a note: keep it on the item as a note, with your reason, so it stops blocking.

The section's header counts what's left ("2 required steps to resolve before verifying") and reads "No required steps blocking: ready to verify" once they're all resolved.

Flags on an item and what to do about them

Flags are the small chips on an item's card and page that say something needs a look. Filter for them with Signals → Any signal on the Tasks page.

Defer, dismiss, reopen or move an item

Change what happens to an item from the ⋯ menu on its card or page:

• Defer (park for later) keeps the item and moves it to Deferred. Resume brings it back to Open. A deferred child stops holding its brief open. Work that's already Implemented or Done can't be deferred: it's been delivered, so reopen it first if it needs to go back on the list.
• Dismiss records that the item won't be done. Work that's already Implemented or Done can't be dismissed outright, because that would erase the record that it happened. Use Dismiss (reopens first), which reopens it with a reason and then dismisses it.
• Reopen, on a Done or Dismissed item, asks for a reason, Implementation incomplete or broken or New follow-up scope, and a note of at least 20 characters. The item returns to Open.
• Move to follow-up is for children of a brief. It takes the child out of the brief as a standalone follow-up item, linked back to the brief. The brief stays intact and completes if that was its last unresolved child. Park it as deferred is ticked by default, which keeps the new item off the active list until you resume it.

A Blocked item is waiting on something outside DevSpec. Ask Dev in a session to block an item and it records the reason for you. The item's page shows the reason and any items it's waiting on, and Unblock returns it to Open when the wait is over.

For work that has to be done by a person and never by an agent, turn on Human-only in the item's Properties ("Off-platform work: never handed to agents").

Assign people to an item

Add or remove people under Assignees in an item's Properties. Assigning is for planning and visibility:

• It doesn't notify the person you assign.
• It doesn't send the item to their agent.
• Once an item has assignees, only an assignee's agent can take it on. Unassigned items can be taken by any agent that someone asks to work them.
• On an item's due date, its assignees get a notification in the bell. If nobody is assigned, the item's creator gets it.

Use the Assignee filter on the Tasks page to see Me, Unassigned or one person's items.

Hand items to an agent

A task is a record. Nothing goes to an agent until a person sends it:

• On the Tasks page, turn on Hand off, tick the items (or press Pick a parallel set to select items that can safely run at the same time), then choose Send to agent to post them to one of your connected agents, or Agent command to copy a command for your agent's terminal.
• On an item, use Agent command (the terminal icon), then Send to an agent or Or copy a command.
• Ask your agent in its own terminal, or message it in a session, naming the items.

The agent takes the items one at a time, in order, works on its own branch, and stops at Implemented with a record of what it did. Sending items needs the Contributor or Maintainer role. See Connect your agent and Working with your agents.

When work would undo a decision

An item can show Waiting for …’s OK when its work would undo an existing decision. Open the question to read the decision, the proposed change and who can answer. The agent may build the work on its own branch, but must not merge it into the tracking branch until it has the required OK.

The person who can decide can choose Go ahead, No with a reason, or This doesn’t undo the decision. You can give your answer through Dev or your agent too. A waiting item cannot reach Done by verification, evidence or supersession until the approval and landing requirements are met. See Review.

Try an approach as an experiment

On an open item, choose Try it as an experiment, or ask Dev or your agent to make it one. You can do this for your own work; a Maintainer can do it for any item. Reviewed Contributors can start experiments without waiting for ordinary work approval.

The item is labeled Experiment and is built on its own branch. When you are ready, choose Ask to land it. Its owner or a Maintainer can give the OK; a Reviewed Contributor's experiment needs a Maintainer. Any other decisions the work would undo also need their OK.

Once approved, the agent can land the work. The item keeps Started as an experiment in its history. A no leaves it on its branch so you can change it, drop it or discuss another approach.

How commits link to an item

When a commit message contains [devspec:<id>] with an item's ID, DevSpec links that commit to the item, and it appears under Linked activity → Commits on the item's page. The short form of the ID (its first 8 characters) works too. Your agent adds the tag for you. If you commit by hand, copy the ID with the Item ID button on the item's page:

Fix the login redirect on mobile [devspec:<id>]

A tagged commit is never written up as a separate item. A commit that reaches a tracked branch without a tag becomes an Auto-tracked item instead. See Commit tracking.

Who can change tasks

What you can do with tasks depends on your role on the project:

• Viewer: reads everything and comments on items. A Viewer can't create, edit, assign, verify or change the state of an item.
• Reviewed Contributor: proposes new work and changes to agreed work for a Maintainer to accept. Can start an experiment on its own branch.
• Contributor: adds work directly and coordinates it: links, assignees, comments, progress and evidence. Changes to an item's agreed title, description, intent or acceptance criteria become proposals, as does superseding another item. Verification follows the project's permissions and verifier list.
• Maintainer: manages work and accepts or declines proposals in Review. Protected decisions still need the appropriate person's OK before work that would undo them lands.

Organization Owners and Admins are Maintainers on every project. See Organizations, members and roles and Who can verify work.