Skip to content

Tasks and publishing

A task is the set of changes of a workstream that ship together: scoped, agreed when a person marks it Ready, published to Main and Git, then Done.

Lifecycle

Tasks are numbered per project, such as T-4.

Task lifecycleText
Draft --Ready (a person)--> Ready --Publish--> In progress --lands--> Done
Draft | Ready | In progress --Abandon--> Abandoned

Publishing moves a Ready task to In progress, and the landing of its newest attempt at its current agreement moves it to Done, recorded as done by the publisher. Start and Mark done remain, and do nothing when the task is already there.

Scope

A task scopes changes of its workstream, and an artefact is in at most one open task of the workstream. Scope is a person's act: from Changes (Add to task) or the task page.

  • Current task. When you edit an artefact directly and it is in no open task, it joins your current task, a Draft task of this workstream. If it is in another open task, you are told which one.
  • Draft tasks follow edits. Editing an artefact a Draft task scopes moves the task to your latest version.
  • Update T-4 moves every scoped artefact whose version moved on to the latest, in one agreement change.
  • Plans become tasks. A plan an agent staged becomes a task when a person accepts the plan as a group; see Proposals, plans and review.

Ready and the agreement

Marking a task Ready records its agreement: the version of every scoped artefact. Changing the scope later, or re-scoping an edited artefact, changes the agreement, and an earlier publish becomes Outdated. Ready needs at least one scoped change.

  • Ready is a person's act. Agents propose plans instead.
  • A blocking question from a person on a scoped artefact, still open in the workstream, refuses Ready (and Publish) with the list of questions. An Admin can override with a reason, which is recorded.
  • With the Ready rule Not the accepter, the person who accepted a change the task carries cannot mark it Ready. Ask for Ready notifies the Editors.

Publishing

Publish is allowed from Ready or In progress. It refuses a conflict in the scope, an artefact another task holds in a pull request awaiting merge, and references to artefacts neither on Main nor in the task. Then it goes one of three ways:

Repository setupWhat publishing does
No repositoryThe task lands at once (Published without git).
Direct commitA commit on the base branch, then the task lands.
Pull requestA branch and a pull request; the task lands when the pull request merges. SpecsGraph asks the provider every five minutes, or at once with Check now. Publishing again replaces the waiting attempt.

A scope Main already has entirely lands at once as a no-op, without touching Git. Branches and pull requests covers names, failures and blocked publishes.

Tracker keys

A task, and a workstream, can carry the key of its story, such as KAN-43. The key links to your tracker through the project's link template and names what the publish writes to Git:

WhereT-4 Reserve stock with KAN-43
Branchspec/shop/KAN-43-t-4-reserve-stock
Commitspec(KAN-43): T-4 Reserve stock
Pull requestKAN-43 spec: T-4 Reserve stock

The key can also address the task in the app, the API and MCP: task_get with task KAN-43.

Abandoning

Abandon a task that will not ship. Its changes stay in the workstream and return to Changes as unrouted; nothing is reverted. Its open pull request is closed and its branch deleted. A pull request merged before that still lands, so Git and Main never disagree.

The task page

The task page lists the scoped changes with their diff and whether each is stale or in conflict, the publication state with its message, and the actions the task allows now. The tasks list shows each task's publication state and key.

Note

What agents do with tasks

Agents open tasks with task_open, read them with task_get and say when they think the scope is complete. Scoping, marking Ready, publishing and marking Done are a person's acts.

Next steps