Work items and delivery

From an agreed task to tracked work#

When a person marks a task Ready, it gets its work items: the steps of delivering it, in a small dependency graph. With the default flow, T-12 gets:

T-12.1 Implement            (implement)
T-12.2 Deploy to staging    (deploy, staging)      after T-12.1
T-12.3 Verify on staging    (verify, staging)      after T-12.2

The signals your tools already send finish the work: a merged pull request completes the implement item, a deployment reported by CI completes the deploy item, and a person records the verify result. Nobody has to move a card.

An item is To do, Doing, Done or Dropped. Items are numbered per task, such as T-12.3, and are never deleted: Drop is the way out, and Restore brings an item back. An item can carry a tracker key (a Jira sub-task, for example), its pull request and an assignee: a person, a team, or both.

The flow template#

Project settings, then Execution, then Flow template sets the steps every task gets at Ready (Admin only). There are two lists:

• Each list holds up to 12 steps. A step can wait only on steps listed before it, so a template never loops.
• A step can name its team, its person and, for deploy, verify and uat, its environment. Pick the verifying team here.
• An empty list creates no items, for a project that tracks delivery elsewhere.
• A plan an agent stages can name the task's work items instead (proposal_plan with workItems); they replace the template for that task.
• A Draft task shows the steps it will get. A task readied before work items existed offers Add items from template.

Ready and blocked#

An item is ready when it is To do, nothing blocks it and nobody holds it. It is blocked while:

• an item it comes after is not Done or Dropped;
• an open blocking question, a person's or an agent's, is on one of its artefacts in the task's workstream;
• an open blocking question is on the item itself.

The task page lists the items under the scope, in dependency order, with Ready or Blocked and the reasons. An Admin can Unblock an item with a reason; it lasts until the item is reopened.

Claims#

• Claim takes a ready item and moves it to Doing. A person's claim holds until they release it.
• Agents claim implement, docs, regression and other items with work_item_claim. Their claim lasts 2 hours; work_item_update with heartbeat keeps it, and a claim that lapses goes back to To do for someone else. Deploy, verify and uat items are refused to agents.
• Release gives an item back. An Editor can release anyone's claim.
• When the task's agreement moves after an item went to Doing, the item says "Spec changed since started".

Pull requests complete implement items#

Name the item in the pull request title or branch, such as T-12.1 Reserve stock or t-12.1-reserve-stock. When it merges into a watched branch, the item is Done and its pull request is recorded.

• What counts. T-12.1 names that item. T-12 or the task's tracker key, such as KAN-43, names the task's only open implement item; with several open, nothing completes and the task page asks you to mark the right one. In the body, only lines that start with closes, fixes, resolves or implements count.
• Which items. Implement and docs items, To do or Doing, even when blocked: the merge happened. A merge from before an item was reopened does not count.
• Which repositories. A project watches its spec repository on its base branch, plus up to 20 code repositories listed in Project settings, then Execution, then Code repositories, each on its default branch or the branch you set. They can come from any Git connection of the organisation.

GitHub sends pull request events through the SpecsGraph GitHub App, so the installation must include the code repositories. For GitLab, an Admin generates a webhook secret in Settings, then Integrations, on the GitLab connection, then adds the URL and secret under the repository's or group's Settings, then Webhooks, with Merge request events and SSL verification on.

CI deployments#

CI reports each deployment with a deploy token, a project credential that starts with sgd_. An Admin creates it in Project settings, then Execution, then Deploy tokens; the secret is shown once, with the CI step below.

• A project has at most 5 active deploy tokens. Expiry is 90 days, 1 year (the default) or none.
• A deploy token belongs to the project, not to the person who made it: it keeps working when that person leaves.
• It does one thing, report deployments. Any other request with it is refused, and the MCP server does not accept it.
• To rotate, create a second token, update CI, and revoke the first once its last use stops moving.

# After a successful deploy to staging. SPECSGRAPH_DEPLOY_TOKEN holds the sgd_ token.
ENVIRONMENT=staging
SHA=$(git rev-parse HEAD)
RANGE=$(git rev-parse -q --verify "refs/tags/deployed/$ENVIRONMENT" >/dev/null && echo "deployed/$ENVIRONMENT..$SHA" || echo "$SHA")
KEYS=$(git log --format='%s%n%b' "$RANGE" | grep -oE '\b([A-Z][A-Z0-9_]*-[0-9]+|T-[0-9]+(\.[0-9]+)?)\b' | sort -u | jq -R . | jq -sc .)
curl -fsS -X POST "https://app.specsgraph.io/api/deployments" \
  -H "Authorization: Bearer $SPECSGRAPH_DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ENVIRONMENT-$SHA" \
  -d "{\"environment\":\"$ENVIRONMENT\",\"sha\":\"$SHA\",\"keys\":$KEYS}"
git tag -f "deployed/$ENVIRONMENT" "$SHA" && git push -f origin "refs/tags/deployed/$ENVIRONMENT"

The step keeps the last deployed commit in a tag, deployed/<environment>, collects the task keys (T-12, T-12.2, KAN-43) from the commit messages since then and posts them. The deploy items of the named tasks whose environment matches, or have none, are Done if they are ready; verify becomes ready and its people are told. A deploy item that is still blocked stays open: a deployment made before the code merged did not carry it. Unknown keys are ignored.

Deploying a commit that ran in that environment before, other than the newest, is a rollback. Verify and uat items verified on a later build are flagged Rolled back and their verifiers are told; they stay Done. Deploying the verified build again clears the flag.

Verify and uat results#

A verify or uat item finishes with a person's result, from the task page or My work. The assignee, a member of the assignee team or an Editor records it; a uat assignee may be a Viewer.

A result needs the item not blocked: a verify whose deploy is not done cannot pass or fail. Reopening a done item by hand reopens that item alone.

The Jira mirror#

In Project settings, then Execution, then Work source, an Admin chooses SpecsGraph (the default) or Jira. With Jira, verify and uat items take their state from the Jira issue their tracker key names, so QA keeps working in Jira:

• An issue in a done status makes the item Done. Any other status on a done item sends it back to To do, in a new round.
• SpecsGraph reads the issue status every 10 minutes, or at once with Sync now. It never writes to Jira.
• Mirrored items take no result in SpecsGraph. An item without a tracker key asks you to link a Jira issue.
• Connect Jira Cloud with the site address, an account email and an API token. The token is stored encrypted and never shown again.

Delivered#

A task is Delivered once it is Done and every item is Done or Dropped. A Done task without items is Delivered too. Task rows show Delivered or "2 of 3 done", the workstream overview counts delivered tasks, and the Tasks page filters Not delivered.

• Items outlive their workstream. Completing a workstream lists the tasks not yet delivered and completes anyway.
• Abandoning a task drops its open items, clears their claims and makes their threads read-only.

Threads on work items#

Each item row opens its own threads: comments and questions about that item. A blocking question there blocks only that item. A question with nobody named asks the item's assignee, the person or else the team. Agents ask with thread_ask and item.

My work#

My work in the project sidebar lists the open items assigned to you or a team of yours, or claimed by you, in three sections: Ready, Doing and Blocked, with the reasons. The sidebar counts your ready items. Rows offer Claim, the result of a verify or uat item, and the task. Toggle All projects to see every project of the organisation.

Next steps#

• Build status→What is built on Main, per artefact, from these work items and deployments.
• Roadmap→Milestones that order the work, and the Up next list that feeds agents.
• MCP tool reference→The work item tools agents use.