Core concepts
The terms every other page assumes — organization, product, project, requirement, reference number, acceptance criterion, workflow stage, and verification.
This page defines the terms the rest of the documentation uses, and says where each one lives in the product.
Organization, product, project
Spectrace has a three-level hierarchy. An organization holds people, billing, and integrations. A product groups related projects and carries a vision and domain. A project holds requirements. A GitHub repository maps to at most one project; PR verification routes each repository to the project it is mapped to.
Spectrace creates a personal organization for your account the first time you need one, with you as owner. Every project created in the web app belongs to exactly one product; the new-project wizard refuses to continue without one. Projects that Spectrace creates from a Linear team, a Jira project, or a GitHub repository with open issues have no product.
Each project has a key: up to four letters in the wizard (stored upper-case, for example SSS), or a value derived from the project name if you leave it blank. The key is what makes reference numbers readable.
Requirement
A requirement is one unit of intended behaviour: a title, rich-text content, a type (functional, non_functional, technical, ui_ux, security, performance, integration, or bug_fix), a priority (low to critical), an optional user story, and a list of acceptance criteria. It lives in exactly one project.
Requirements enter Spectrace in several ways: the import wizard (paste text, upload documents, or fetch URLs, then AI extracts candidates for you to review), the Quick add modal (title plus optional AI generation of the details), inbound sync from Linear, Jira, or GitHub Issues, the VS Code extension, the Slack app, and the MCP tools an AI agent calls. Whichever way it arrives, a requirement records who created it, its version, and — for AI-generated content — the model, the agent, and a hash of the prompt template that produced it.
Reference number
Every requirement gets a reference number (called a ref throughout the app) when it is inserted: the project key in lower case, a hyphen, and a per-project sequence padded to three digits, such as sss-042 or tfa-007. Numbers past 999 grow to four digits. The database assigns the ref, so two people creating requirements at once cannot collide.
The ref is the requirement's public handle. It is the last segment of the requirement URL (/projects/<project>/requirements/sss-042), the argument to the Slack /spectrace status <ref> command, and the token Spectrace looks for in a pull request's branch name, title, and description to decide which requirement to verify against. Matching is case-insensitive and tolerant of missing zero padding: SSS-42 and sss-042 are the same ref.
Branch names, commit messages, and pull requests created before the format changed may still carry the retired RIP-SSS-042 form. URLs and PR matching accept it.
Acceptance criterion
An acceptance criterion (AC) is one checkable statement attached to a requirement: an id, a description, a completed flag, and optionally a category (happy_path, validation, edge_case, error_handling, security, compliance) and compliance references (ASVS, CWE, OWASP Top 10, SSDF). Criteria are stored on the requirement itself, not in a separate table.
Criteria do three jobs. They are what PR verification grades — the verdict is a status per criterion, and the pull-request comment reports those statuses rather than a percentage. They gate the workflow — the web app refuses to move a requirement to In Review or Done while any criterion is unchecked. And they are the input to test-case generation — Spectrace generates Gherkin test cases from criteria and declines when there are none.
You tick a criterion by hand on the requirement page, from the VS Code extension, or through the MCP tools. Verification does not tick criteria for you.
Workflow stage
A workflow stage is where a requirement sits in delivery. The web app uses four stages, shown with these labels:
| Stored value | Label in the app | Meaning |
|---|---|---|
draft | Backlog | Written, not yet picked up |
in_development | In Dev | Someone is implementing it |
qa_verification | In Review | Implementation done, being checked |
done | Done | Verified and closed |
Any project member can move a requirement forward; assignment is optional. Moving to In Dev triggers embedding of the requirement for related-code lookup and, if none have been generated yet, test-case generation. Moving to In Review or Done requires every acceptance criterion to be checked. Merging a pull request that was verified against the requirement moves it to Done automatically.
The MCP server exposes a fifth stage. Its spectrace_requirements_transition tool walks draft → qa_review → in_development → qa_verification → done, where qa_review means the AI-generated test cases are under review, and it does not enforce the acceptance-criteria gate. The web app cannot set qa_review and displays any requirement in it under Backlog. Both behaviours are current; if your team mixes agents and the web app, decide which model you follow.
The database also holds two legacy values, approved and ready_for_dev, which the app displays as Backlog. Requirements created by inbound sync from Linear, Jira, or GitHub Issues land in ready_for_dev once AI enrichment finishes.
Verification
A verification (in full, a PR verification) is one run of Spectrace's check of a pull request against one requirement. It records the pull request, the commit checked, the requirement and its version at the time, and one result per acceptance criterion: satisfied, partial, not_found (the diff does not touch this criterion — the normal answer for a focused change), contradicted (the diff breaks something the criterion requires), or unclear. Each result carries the model's evidence — file and line ranges — and its reasoning.
A run starts when a pull request opens, reopens, or receives a push on a repository mapped through the GitHub App, when you press Re-verify on the requirement page, or when an AI agent calls spectrace_pr_verifications_create in inline mode with a diff. For webhook and Re-verify runs, the outcome lands as a comment and a check run named Spectrace verification on the pull request, and on the requirement page under the PR verification tab. An inline run from an AI agent is stored and shown on the requirement page but posts nothing to GitHub. Verification never edits an earlier comment: every run posts a new one.
There is no accuracy figure for the verifier anywhere in Spectrace, and no page in these docs quotes one.
Traceability link
A traceability link is a stored edge between two artefacts: a requirement or test case on one side, and a code file path, test case, GitHub pull request, or Linear issue on the other, with a link type of implements, verified_by, or related_to. The links you see most often connect a requirement to a code file, created when the VS Code extension notices you editing a file while a requirement is active, or when an agent calls spectrace_requirements_link_file.
PR verification reads these links. When a pull request names a requirement explicitly, Spectrace also looks up which requirements the changed files are linked to; if they agree, the comment says Confirmed by file traceability, and if they point elsewhere, the comment adds a Possible drift line naming the other requirement. When a pull request names nothing, the strongest file link becomes the fallback match.
Requirement-to-requirement dependencies are a separate field on the requirement, not traceability links.
Roles
Roles exist at two levels.
Organization roles are owner, admin, and member. Owner and admin can install the GitHub App and map repositories to projects. Members work in the projects they belong to. The MCP server derives an API key's permissions from the key owner's organization role; only owner and admin can delete requirements or grant approvals through it.
Project roles are owner, admin, qa, developer (the default), and viewer. Owner and admin can update project settings, and mapping a repository requires owner or admin at both levels — organization and project. Viewers have read access and cannot create requirements.
Roles do not gate workflow transitions in the web app; any project member with access can move a requirement.
Related
- Quick start — put these terms to work on a first project.
- Acceptance criteria — categories, compliance references, and the gates that read them.
- Workflow stages and approvals — transitions, gates, and what approvals do today.
- Linking a PR to a requirement — the ref match and the traceability fallback in detail.
- Glossary — one-line definitions for quick lookup.