Move a requirement through workflow stages

This page shows you how to move a requirement between stages, what blocks a move, and how stage changes reach connected tools.

Prerequisites

• A requirement in a project you are a member of. Any project member can change a stage; there is no role gate on transitions.

The stages in the web app

A workflow stage is where a requirement sits in the delivery flow. The web app has four:

The board shows one column per stage, and the requirement page shows a stage pill with a Set status menu. A project can define custom board columns; each column is tagged with one of the four stages, so dropping a card into a column moves the requirement to that column's stage.

Three older stored values, approved, qa_review, and ready_for_dev, still exist from earlier stage models; background enrichment and the Jira and Linear default mappings still write ready_for_dev. The web app displays all three as Backlog.

Allowed moves

From the Set status menu you can move:

• Forward to any later stage (Backlog → In Dev, In Review, or Done; In Dev → In Review or Done; In Review → Done).
• Backward only along these paths: In Dev → Backlog, In Review → In Dev, Done → In Dev.

Anything else is greyed out in the menu and rejected by the server. Dragging a card into another board column applies the same rules and shows a rejected move as an error above the board.

What happens on each move

To In Review or Done. Every acceptance criterion must be marked complete. Otherwise the menu greys the option out and the server answers with a message starting N acceptance criteria not completed. A requirement with no criteria passes. Moving to In Review also warns when any test case is still in draft status ("N test case(s) not executed"); the menu shows the warning with Proceed anyway and Cancel. Moving to Done additionally sets the legacy status to verified.

To In Dev. Assignees are optional. Spectrace embeds the requirement for semantic search and, if no tests have been generated yet, starts Gherkin test generation from the acceptance criteria.

To Backlog. Spectrace clears both assignees and resets the test-case status to not_generated; existing test cases stay.

Every move. Spectrace writes a revision entry; moves to In Dev, In Review, or Done mark it as a baseline labelled Development Baseline, QA Baseline, or Release Baseline in the Versions card, while a move to Backlog writes a plain revision with no baseline label. Spectrace also records the transition for cycle-time analytics, pushes the new stage to the linked Linear, Jira, or GitHub issue when the requirement came from one, and posts to Slack channels that have status-change notifications on. See Import requirements for the stage mappings and Slack, Jira and Linear for notifications.

Other ways to move a requirement

• VS Code extension. Starting work promotes a Backlog requirement to In Dev and stamps the start time; Mark Complete (or Create PR & Submit for Review when GitHub is connected) moves it to In Review once every acceptance criterion and every subtask is done. See VS Code extension.
• Issue trackers. A status change in Linear, Jira, or GitHub Issues moves the requirement according to the project's status mapping.

The MCP server uses five stages

The MCP server's spectrace_requirements_transition tool has its own state machine, and it is not the same as the web app's:

Allowed moves: draft → qa_review; qa_review → in_development or draft; in_development → qa_verification or qa_review; qa_verification → done or in_development; done → in_development. When an agent moves a requirement to in_development and nobody is assigned, the tool assigns the calling user. It does not check acceptance-criteria completion.

Two consequences follow. spectrace_requirements_transition cannot move a requirement straight from draft to in_development; it passes through qa_review, which the web app shows as Backlog. (spectrace_requirements_update accepts any stage directly, with no state-machine check.) And the web app cannot set qa_review at all. Both are true today. See Tool reference.

Approvals

Spectrace has an approval model in the database: approval rules on a project (trigger stage, optional target stage, who may approve — a role, a specific user, or any team member — and options such as self-approval and a required comment) and approval requests with status pending, approved, rejected, expired, or skipped.

What is reachable today:

• MCP. spectrace_approvals_request opens requests for the active rules that match a transition; when no rule applies it returns created=0 and the move is unrestricted. spectrace_approvals_grant records approved or rejected with a comment (required when the rule demands one) and, when the decision is approved and no request for that transition is still pending, sets the requirement's stage. It checks project access and blocks self-approval unless the rule allows it; it does not check the approver's role.
• Web app. Nothing. There is no screen to create approval rules, stage changes from the Set status menu do not create or check approval requests, and /approvals redirects to /projects.

What done looks like

After a move, the stage pill and the board column update, the Versions card shows a new version (labelled Development Baseline, QA Baseline, or Release Baseline for moves to In Dev, In Review, or Done), and a linked tracker issue changes status. If the move fails, the picker shows the server message: an acceptance-criteria count you have to clear, or Invalid transition: Cannot move from "In Review" to "Backlog" for a backward move that is not on the list. A drag that trips the draft-tests warning is not saved and shows no message, but the card stays in the new column on screen until you reload; use Set status and choose Proceed anyway instead.

Related

• Write acceptance criteria
• Contributors and assignment
• Import requirements
• Roles and permissions
• Tool reference