SpecTrace 0.4.1-preview.1

<p align="center"> <img src="https://raw.githubusercontent.com/amondejar/spec-trace/main/assets/icon.png" width="96" alt="SpecTrace"> </p>

SpecTrace

Spec-Driven Development traceability for .NET. Your Markdown specs become a typed catalog of requirements, and the C# compiler tells you what is not implemented, not tested, or out of date with the spec.

specs/orders.spec.md(28,1): warning ST0003: Requirement 'ORD-003' (Apply discount coupon) is approved
  but no type or member has [Implements("ORD-003")]

SpecTrace links spec → code → test at build time, in the IDE, in pull requests and for AI coding agents:

• Roslyn analyzer and source generator: no extra build step, warnings show up next to the others.
• Detects spec changes after review (spectrace.lock): when a requirement's text changes, the build names the code and tests to review.
• dotnet spectrace CLI: traceability report, test scaffolding, import from Spec Kit and OpenSpec.
• MCP server and Agent Skill so coding agents start from the spec and stop only when the build is clean.

How it works

1. Write specs as *.spec.md files with identified requirements (or import them from Spec Kit / OpenSpec):

   ## ORD-001: Create order
   Status: approved
   
   When the customer submits a cart with at least one line,
   the system shall create an order in state Pending.
   
   - AC-1: Given a cart with 2 lines, when it is submitted, then an order with 2 lines is created.
   - AC-2: Given an empty cart, when it is submitted, then the request is rejected.
   

2. The generator creates Requirements.ORD_001 and AcceptanceCriteria.ORD_001.AC_1.

3. Mark code and tests:

   [Implements(Requirements.ORD_001)]
   public Order Create(IReadOnlyList<OrderLine> cart) { ... }
   
   [Fact]
   [Verifies(Requirements.ORD_001, AcceptanceCriteria.ORD_001.AC_2)]
   public void Create_with_empty_cart_is_rejected() { ... }
   

4. dotnet build checks traceability; dotnet spectrace report prints the full matrix.

Packages

Getting started

dotnet new tool-manifest               # local tool for the repo: invoked as "dotnet spectrace"
dotnet tool install SpecTrace.Tool --prerelease
dotnet spectrace init                  # spectrace.json, specs/example.spec.md, the agent skill and .mcp.json
dotnet add src/MyApp package SpecTrace --prerelease
dotnet add tests/MyApp.Tests package SpecTrace --prerelease
dotnet build

If you prefer a global install (dotnet tool install -g SpecTrace.Tool --prerelease), the command is spectrace instead of dotnet spectrace, including in .mcp.json.

Optional MSBuild settings: SpecTraceSpecsDir, SpecTraceNamespace, SpecTraceRole (Implementation | Tests). Set severities in a .globalconfig (is_global = true) rather than .editorconfig, because coverage diagnostics are reported on the .md files.

Spec format

A requirement is a level 2–4 heading ID: Title, an optional status line, a statement (EARS recommended) and acceptance criteria - AC-n: ....

Diagnostics

Tests marked Skip or [Ignore] do not count as coverage.

Spec changes (spectrace.lock)

A spec that changes after it was implemented is the case that slips through most often: code and tests stay green but no longer do what the text says. SpecTrace stores in spectrace.lock a fingerprint of each requirement's statement and criteria at the time they were reviewed, and warns when they change:

dotnet spectrace lock                          # record the current version of every active requirement
dotnet spectrace lock --requirement ORD-001    # after reviewing one requirement
dotnet spectrace lock --check                  # in CI: fail if there are unreviewed changes

Commit spectrace.lock together with the review. It has one line per requirement, so diffs are readable and conflicts only touch the requirement that changed. Recording a review is a human decision: the skill and the MCP server ask agents not to run lock on their own.

In the IDE

Besides the code fixes listed above, on any [Implements] or [Verifies] (Ctrl+. in Visual Studio and VS Code, Alt+Enter in Rider):

• Use SpecTrace catalog constants: "ORD-001" → Requirements.ORD_001, "AC-1" → AcceptanceCriteria.ORD_001.AC_1.
• Generate tests for ORD-001 in MyApp.Tests: creates Specs/ORD_001_...Tests.cs in the test project with one test (marked Skip) per criterion that has no test yet.

In pull requests (GitHub Actions)

permissions:
  contents: read
  pull-requests: write

jobs:
  spectrace:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: amondejar/spec-trace@v0.4.1
        with:
          root: .              # folder containing spectrace.json
          fail-on-gaps: false  # true to block the PR when there are gaps
          fail-on-drift: true  # block when the spec changed and nobody reviewed code and tests

The Action annotates gaps on the PR files, adds the report to the job summary and keeps one comment with the full matrix, updated on every push. It exposes the outputs gaps (requirements with gaps) and drift (requirements whose spec changed without review). For other CI systems: dotnet spectrace report --fail-on-gaps --fail-on-drift (Markdown) or --format json.

For AI coding agents

Skill

dotnet spectrace init installs .claude/skills/spectrace/SKILL.md (Agent Skills format; use --skills-dir to place it where your agent reads skills). The skill tells the agent to start from the spec, load the requirement before implementing, read the existing code instead of guessing types, and not to consider the work done while ST diagnostics remain.

MCP server

dotnet spectrace mcp starts a Model Context Protocol server over stdio, with no external dependencies:

Paths are confined to the repository and the spec folder; get_code never reads bin, obj, .git, configuration or secrets. The server implements the initialize handshake (protocol revisions 2024-11-05 to 2025-11-25); clients that prefer revision 2026-07-28 fall back to it automatically.

dotnet spectrace init creates .mcp.json (Claude Code and other clients that read it). For VS Code, .vscode/mcp.json:

{
  "servers": {
    "spectrace": { "type": "stdio", "command": "dotnet", "args": ["spectrace", "mcp"] }
  }
}

Microsoft Agent Framework demo

samples/AgentDemo is an Agent Framework agent that connects to this MCP server, studies a requirement and proposes the missing code and tests. It works with any OpenAI-compatible endpoint (OpenAI, Ollama, LM Studio, Claude's compatibility endpoint…).

Import from Spec Kit and OpenSpec

dotnet spectrace import speckit specs/              # each specs/NNN-feature/spec.md → spectrace.spec.md next to it
dotnet spectrace import openspec openspec/          # each openspec/specs/<cap>/spec.md → specs/<cap>.spec.md

The prefix comes from the feature folder (001-photo-albums → PA1) or the capability (auth → AUTH) and can be set with --prefix. Re-importing is safe: IDs (matched by title in OpenSpec), statuses you changed and criteria you added by hand to requirements without criteria are kept. --dry-run shows what would happen. Examples in samples/Import.

Repository layout

src/SpecTrace.Abstractions   attributes (netstandard2.0)
src/SpecTrace.Analyzers      spec parser, generator, analyzer, build/*.props|targets (netstandard2.0)
src/SpecTrace.CodeFixes      IDE code fixes and refactorings (netstandard2.0)
src/SpecTrace.Package        packs analyzer + code fixes as the "SpecTrace" package
src/SpecTrace.Tool           dotnet spectrace CLI and MCP server (net8.0, RollForward Major)
tests/SpecTrace.Tests        tests for parser, generator, analyzer, code fixes, MCP, importers and lock
docs/rules                   one page per diagnostic
action.yml                   GitHub Action for pull requests
samples/Orders               full example with intentional gaps (ORD-003 not implemented, ORD-002 AC-2 untested)
                             and one unreviewed change (ORD-001 AC-2 changed after spectrace.lock)
samples/Import               Spec Kit and OpenSpec example specs to try the importers
samples/AgentDemo            Microsoft Agent Framework agent using the MCP server

Development

dotnet test tests/SpecTrace.Tests
dotnet build samples/Orders/tests/Orders.Tests     # shows ST0003, ST0005 and ST0011
dotnet run --project src/SpecTrace.Tool -- report --root samples/Orders
dotnet pack src/SpecTrace.Abstractions -c Release -o artifacts
dotnet pack src/SpecTrace.Package -c Release -o artifacts     # the "SpecTrace" package
dotnet pack src/SpecTrace.Tool -c Release -o artifacts

Releases are published to nuget.org from GitHub Actions with Trusted Publishing when a v* tag is pushed (.github/workflows/release.yml).

License

MIT