spectracebeta

Quick start

From a new account to a verified pull request — sign up, create a project, add a requirement with criteria, install the GitHub App, open a PR.

This page takes you from a new Spectrace account to a pull request that carries a Spectrace verification comment and check run.

Prerequisites

  • A GitHub account. To install the GitHub App on a GitHub organization you must be an owner of that organization; on a personal account, the account must be yours.
  • Owner or admin role in your Spectrace organization. Spectrace creates a personal organization for you on first use, and you are its owner.
  • A repository whose pull requests change code files (for example .ts, .py, .go). The verifier reads only code files from the diff, so a docs-only pull request gives it nothing to grade.

Steps

  1. Sign up

    Open /signup. Choose Continue with Google, Continue with GitHub, or enter a work email and a password of at least 8 characters with an upper-case letter, a lower-case letter, and a number.

    The email path sends a verification link; open it before you continue. Google and GitHub sign-ins need no verification email.

  2. Create a product

    Every project belongs to exactly one product, so create the product first. Open Products → New product (/products/new), enter a Product name, and press Create product. Key, domain, description, and vision are optional.

  3. Create a project

    Open Projects → New Project (/projects/new). The wizard has four steps: Basics, Context, Team, and GitHub.

    On Basics, pick the product, enter a project name, and set the Short key — two to four letters that Spectrace upper-cases as you type. This key becomes the prefix of every requirement reference in the project: a project keyed SSS numbers its requirements sss-001, sss-002, and so on (lower-case key, a hyphen, and a three-digit sequence). If you leave the key blank, Spectrace derives one from the project name.

    Context and Team each have a Skip for now button. On GitHub, choose Finish without linking: this step connects a repository through your personal GitHub login, which is not what routes pull requests to verification. The GitHub App mapping later on this page does that.

    The free plan allows two projects per organization.

  4. Add a requirement

    On the project page, open the Add requirement menu in the top bar. It offers two paths:

    • Import requirements opens the import wizard at /projects/<project>/requirements/import. Choose Paste text, Documents (.pdf, .docx, .md/.markdown, .xls/.xlsx, .csv, .txt; up to 10 files, 50 MB each), or URL (up to 5 URLs), then walk through Clarify → Extract → Review → Create. Extracted requirements arrive with acceptance criteria drafted; on Review, untick anything you do not want and press Continue →.
    • Quick add opens a modal with a title, an optional description, a priority, and Generate in background toggles for User story, Acceptance criteria, Subtasks, and Tests. Turn on Acceptance criteria so the requirement gets criteria without you writing them, then press Create · generate 1 (the button counts the toggles you turned on).

    New requirements land in the Backlog column.

  5. Confirm the requirement has acceptance criteria

    Open the requirement (/projects/<project>/requirements/<ref>, for example /projects/my-project/requirements/sss-001). The Acceptance criteria card lists each criterion; Add criterion appends one by hand.

    Verification grades the diff against these criteria one by one, so a requirement with no criteria produces no useful verdict. Copy the reference shown on the page — you need it for the branch name.

  6. Install the GitHub App and map the repository

    Open Settings → Integrations (/settings?tab=integrations). Only an organization owner or admin sees the install controls.

    1. In the GitHub section, press Connect GitHub if your account is not connected yet. This binds your Spectrace user to a GitHub identity; the App install checks that identity.
    2. In the GitHub App block, press Install Spectrace. GitHub asks which account to install on and which repositories to grant. Pick the repository from the prerequisites.
    3. GitHub returns you to Settings with the message GitHub App connected. Map each repository to a project below. The block now lists every repository the installation covers with a select per row. Change the row for your repository from Not mapped to your project.

    Unmapped repositories are ignored. A repository maps to at most one project.

  7. Open a pull request that carries the reference

    Create a branch whose last path segment starts with the reference, or put the reference in the PR title:

    bash
    git checkout -b feat/sss-001-short-description
# ...commit your change...
git push -u origin feat/sss-001-short-description

    Then open the pull request on GitHub. Spectrace matches the reference case-insensitively, so SSS-001, sss-001, and sss-1 all resolve to the same requirement. Spectrace looks in the branch name first, then the title, then the description, and stops at the first one that names exactly one requirement in the mapped project.

  8. Read the result

    Spectrace runs verification as a background job. When it finishes, GitHub shows two things on the pull request:

    • A comment from the Spectrace App whose heading is a mark, the reference in code, and the requirement title — for example ◐ sss-001 — Users can reset their password. The second line counts criteria — for example All 3 criteria met., 1 of 3 met, 1 in progress., This diff covers 0 of 3 criteria., or 1 of 3 criteria met, 1 contradicted. Below it, Done and Outstanding lists name individual criteria, with a link into the diff at the verified commit for each met criterion the verifier could point at code for.
    • A check run named Spectrace verification. It concludes success when every criterion is satisfied, failure when the diff contradicts a criterion, and neutral otherwise. GitHub treats neutral as passing, so a required Spectrace check blocks a merge only on a contradicted criterion.

    In Spectrace, the same result appears on the requirement page under the PR verification tab, which appears once the requirement has at least one pull request or is in In Review or Done. Every new push to the branch runs verification again and posts a fresh comment; editing the title or description alone does not trigger a run.

    When the pull request merges, Spectrace moves the requirement to Done.

What done looks like

You are done when the pull request shows the Spectrace verification check and a comment headed with the requirement's reference and title, and the requirement page's PR verification tab lists the same run.

If instead the comment reads Spectrace — no requirement linked, Spectrace found no reference it could resolve. The comment names the project it searched and lists where to put the reference: the branch name (feat/abc-123-short-description), the PR title, or the PR description. The check run concludes neutral with the title No linked requirement and does not block. Add the reference to the branch name or title and push a new commit; the next push runs the match again.

Two other unmatched forms exist. Spectrace — which requirement? means one place named several requirements and nothing singled one out — keep only the primary reference in the branch or title. A comment saying the PR looks like it references a ref but no requirement with that reference exists in the project means the ref is not in the mapped project — check the project key and the mapping in Settings.

If nothing appears at all, the repository is probably not mapped, or the installation is not claimed by your Spectrace organization. Return to Settings → Integrations and check the mapping table; the Refresh button re-reads the installation from GitHub.