Adding Supersigil to an Existing Project

The Quickstart walks through a greenfield setup. This guide covers the more common case: you have working code, existing tests, and want to start connecting them to verifiable specs without disrupting what already works.

Strategy

Start small. Pick one module you understand well, write a single requirements spec for it, and wire up the evidence you already have. Once that loop feels natural, expand to more modules.

1. Initialize Supersigil

   From your repository root:

   supersigil init

   This creates supersigil.toml and installs agent skills. See the Quickstart for install options and the CLI reference for all init flags.

2. Pick one module and write a requirements spec

   Choose a module that already has tests. Scaffold a requirements doc:

   supersigil new requirements auth

   Edit the generated file to describe the behavior that already exists. Start with status: draft so verification stays relaxed while you iterate:

   specs/auth/auth.req.md

   ---
   supersigil:
     id: auth/req
     type: requirements
     status: draft
   title: "Authentication"
   ---
   
   ```supersigil-xml
   <AcceptanceCriteria>
     <Criterion id="valid-creds">
       WHEN a user submits valid credentials
       THE SYSTEM SHALL issue a session token.
     </Criterion>
   
     <Criterion id="invalid-creds">
       WHEN a user submits invalid credentials
       THE SYSTEM SHALL return a 401 response.
     </Criterion>
   </AcceptanceCriteria>
   
   <TrackedFiles paths="src/auth/**/*.rs, tests/auth/**/*.rs" />
   ```

   Write criteria for behavior that is already implemented and tested. You are documenting reality, not specifying new work.

3. Annotate your existing tests

   Add annotations to the tests that prove each criterion.

   Rust

   Use the verifies attribute macro from the supersigil_rust crate. Native support is enabled by default.

   cargo add supersigil-rust

   tests/auth/login_test.rs

   use supersigil_rust::verifies;
   
   #[verifies("auth/req#valid-creds")]
   #[test]
   fn login_returns_session_token() {
     // your existing test
   }

   JS/TS (Vitest)

   Enable the JavaScript/TypeScript ecosystem plugin in supersigil.toml. Then use the verifies helper from the @supersigil/vitest package.

   pnpm install --save-dev @supersigil/vitest

   supersigil.toml

   paths = ["specs/**/*.md"]
   tests = ["tests/**/*.test.ts"]
   
   [ecosystem]
   plugins = ["rust", "js"]

   tests/auth/login.test.ts

   import { verifies } from '@supersigil/vitest'
   import { test, expect } from 'vitest'
   
   test('login with valid credentials', verifies('auth/req#valid-creds'), () => {
     // your existing test
   })

   The annotations are no-ops at runtime. They just mark the test as evidence.

4. Run verify and confirm it passes

   supersigil verify

   Since the spec is in draft, configurable findings (like uncovered criteria) are downgraded. But broken refs and structural errors still surface. Fix any that appear.

5. Promote to approved when ready

   Once you are confident in the evidence mapping, change the status:

   status: approved

   Run verify again. Now Supersigil enforces coverage — any criterion without evidence becomes a warning or error (depending on your config).

Expanding gradually

Once the first module works:

• Add more modules one at a time. Each spec is independent. There is no requirement to cover the whole codebase at once.
• Use TrackedFiles early. Even before criteria have full evidence, tracked files give you drift detection. You will know when code changes and a spec might need review.
• Use supersigil status to see coverage across all specs at a glance.
• Keep new specs in draft until evidence is wired up. This prevents verify from blocking CI on work-in-progress specs.
• Let AI agents handle the next module. The agent skills installed by supersigil init include an ss-retroactive-specification skill designed for exactly this case — an agent reads existing code and tests, writes the spec, and wires up evidence. Point it at a module and let it follow the same loop you just did manually.

Tip

For non-Rust projects, you can use <VerifiedBy strategy="tag" tag="auth:valid-creds" /> in your criteria and add // supersigil: auth:valid-creds comments in test files instead. See Evidence Sources for all options.

CI integration

Once you have a few specs with solid evidence, add verification to CI. A simple approach:

.github/workflows/specs.yml

- name: Verify specs
  run: supersigil verify

Use supersigil verify --since main in pull request checks to scope verification to changed specs. See the CI Verification guide for the full setup.