Workstreams and tasks

Plan spec work with numbered workstreams such as WS-3: group tasks and proposals toward one outcome, track their status and let agents update tasks.

What a workstream is

A workstream groups the tasks and proposals that serve one outcome. A proposal is a single change to the spec. A workstream is the reason several changes belong together: a feature, a migration, the cleanup of one context. It tells everyone what the team is working toward and how far along it is.

In Northwind Commerce, WS-3 Reserve stock at checkout collects everything needed so a Customer never pays for an item that cannot ship. That is three requirements across Orders and Billing, a decision, a change to the relationship between Orders and Fulfilment, and a new email in Notifications.

Workstreams belong to a project. Open Workstreams in the sidebar to see every workstream in the project, grouped by status.

Workstream fields

Field	What it holds	WS-3 example
Number	`WS-` plus the next free number in the project. Assigned on creation and never reused.	`WS-3`
Name	A short name for the outcome. You can change it at any time.	Reserve stock at checkout
Outcome	One sentence that says what done looks like.	A Customer never pays for an item that cannot be shipped.
Status	Planned, Active or Done.	Active
Tasks	The units of work, each with an owner and a status.	4 tasks, 2 of them done
Proposals	Linked proposals, shown with their current status.	Checkout reserves stock before payment (`spec/checkout-reserve`)
Contexts	Filled in from the linked tasks and proposals.	Orders, Billing, Fulfilment, Notifications

Renaming keeps the number

The number is the workstream's identity. If Northwind renames WS-3 to "Stock-safe checkout", it is still WS-3, its file keeps the name WS-3.md, and every mention of WS-3 in commit messages, pull requests and chat still points to the right place. Quote the number, not the name, when you refer to a workstream anywhere outside SpecsGraph.

Workstream statuses

Status	What it means
Planned	Agreed on, but nobody is working on it yet. You can already add tasks so the plan is visible.
Active	Work is under way. Active workstreams appear in `get_project_overview`, so agents see them when they start a session.
Done	The outcome is reached. The workstream stays readable with its tasks and proposals. Set it back to Active if more work turns up.

Members with the Editor role or above create workstreams and change their status. Agents work one level down, on tasks.

Tasks

A task is one unit of work inside a workstream. It has a title, an owner, a status (To do, In progress or Done) and optional links to the requirements and proposals it concerns. The owner is always a person, even when an agent does the work. Refer to a task by its workstream number and its title, as the prompt further down does.

Task	Owner	Status	Linked to
Specify stock reservation at checkout	Ana	Done	`ORD-12`, `ORD-13`, `spec/checkout-reserve`
Specify payment capture after reservation	Kofi	Done	`BIL-04`, `spec/checkout-reserve`
Add the stock reserved event to the Orders and Fulfilment relationship	Ana	In progress	Orders, Fulfilment
Specify the email sent when a reservation lapses	Mei	To do	Notifications

Keep a task about the size of one proposal. A task that needs three separate reviews is really three tasks, and splitting it shows progress more honestly.

Link proposals to a workstream

Link a proposal from its page in Reviews, or from the workstream itself. A task can also point at the proposal that delivers it. Linked proposals show their status on the workstream, so WS-3 shows spec/checkout-reserve as Published the moment its pull request is merged. The proposal statuses are the same everywhere in SpecsGraph.

Tip

Publishing does not close the task

A task can need more than one proposal, so SpecsGraph leaves its status alone. Move the task to Done yourself, or ask the agent that did the work to do it with update_task.

How agents work with tasks

Agents read workstreams with list_workstreams and get_workstream. With update_task they create a task in a workstream or change a task's status. Task changes take effect right away without a review, because they describe the plan rather than the spec. Each change is recorded with the agent and the person whose token it used. Agents cannot create workstreams or change a workstream's status.

PromptText

Read WS-3 and pick up the task "Specify the email sent when a reservation lapses".
Move it to In progress, draft the requirement in Notifications using the
glossary terms, and add a task for anything you find that is out of scope.

get_workstream returns the tasks and linked proposals of WS-3.
update_task moves the task to In progress, so the team can see someone has picked it up.
get_context and list_glossary_terms give the agent the Notifications context and the word Reservation.
propose_requirement opens a proposal with the new requirement and its scenarios, ready for review.
If the agent notices that SMS notifications need the same rule, update_task adds a To do task for it instead of widening the proposal.

What gets published

SpecsGraph writes each workstream to specsgraph/workstreams/WS-3.md in your repository. The file is updated in the commit SpecsGraph writes for any approved proposal linked to the workstream, so it shows the workstream as it stood at that revision. Task changes on their own do not create commits. For the live state, use the web app or get_workstream.

specsgraph/workstreams/WS-3.mdMarkdown

# WS-3 Reserve stock at checkout

Status: Active
Outcome: A Customer never pays for an item that cannot be shipped.
Contexts: Orders, Billing, Fulfilment, Notifications

## Tasks

- [x] Specify stock reservation at checkout (Ana; ORD-12, ORD-13)
- [x] Specify payment capture after reservation (Kofi; BIL-04)
- [ ] Add the stock reserved event to the Orders and Fulfilment relationship (Ana; in progress)
- [ ] Specify the email sent when a reservation lapses (Mei; to do)

## Proposals

- Checkout reserves stock before payment (spec/checkout-reserve)

## Decisions

- 0007 Reserve stock before payment

Anyone reading a pull request can open this file to see which piece of planned work a spec change belongs to, without signing in to SpecsGraph.

Next steps

Proposals and reviews: how the proposals in a workstream get reviewed and approved.
Working well with agents: hand agents tasks they can finish in one proposal.
MCP tool reference: the full list of read and write tools.
Spec files in your repository: where workstream files sit next to the rest of the spec.