Specter QuickStart | Hanalyx Docs

Get from zero to a working spec pipeline in under 5 minutes.

1. Install

Fastest path — VS Code extension: search Specter SDD in the Extensions panel, install, then run Specter: Add CLI to Shell PATH from the command palette once. The extension auto-downloads the CLI binary for your OS and architecture.

CLI-only, macOS / Linux:

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac
VERSION=$(curl -sL https://api.github.com/repos/Hanalyx/specter/releases/latest | grep '"tag_name"' | head -n1 | cut -d'"' -f4 | sed 's/^v//')
curl -LO "https://github.com/Hanalyx/specter/releases/download/v${VERSION}/specter_${VERSION}_${OS}_${ARCH}.tar.gz"
tar xzf "specter_${VERSION}_${OS}_${ARCH}.tar.gz" && sudo mv specter /usr/local/bin/
specter --version

CLI-only, Windows (PowerShell):

$v = (Invoke-RestMethod https://api.github.com/repos/Hanalyx/specter/releases/latest).tag_name -replace '^v',''
Invoke-WebRequest -Uri "https://github.com/Hanalyx/specter/releases/download/v${v}/specter_${v}_windows_amd64.zip" -OutFile specter.zip
Expand-Archive specter.zip -DestinationPath "$env:USERPROFILE\.specter\bin"
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:USERPROFILE\.specter\bin", "User")

For .deb, .rpm, and other install methods see the Specter README.

2. Bootstrap specs from your code

Point Specter at your source directory — it generates draft specs automatically:

specter reverse src/        # TypeScript / JavaScript
specter reverse app/        # Python / Django / FastAPI
specter reverse ./          # Go

This creates a specs/ directory with one .spec.yaml per file group.

Already have specs? Specter uses its own schema (see Schema Reference). Run specter reverse --dry-run --json src/ to preview what it generates, then decide whether to migrate your existing specs or start fresh.

3. Initialize the workspace

specter init

Creates specter.yaml — the manifest that tells Specter (and the VS Code extension) where your specs and tests live.

4. Review one spec

Open any generated spec in VS Code. It will look like this:

spec:
  id: user-create
  version: "1.0.0"
  status: draft
  tier: 2
  context:
    system: User service
  objective:
    summary: "Create a new user account"
  constraints:
    - id: C-01
      description: "POST /users accepts email and password"
  acceptance_criteria:
    - id: AC-01
      description: ""        # ← empty, needs your intent
      gap: true              # ← human review needed

The gap: true flag lives on individual acceptance criteria that the reverse compiler extracted structurally but couldn't infer intent for. Until those gaps are filled, the AC counts as uncovered (specter sync will fail on it), which is what forces the triage.

Pass this prompt to your AI assistant:

Here is a draft spec generated by Specter's reverse compiler:

[paste the spec]

Please:
1. Fill in all empty acceptance_criteria descriptions with clear, testable behavior
2. Add any constraints that are obviously missing based on the context
3. Remove the `gap: true` flag once all gaps are filled
4. Keep all existing IDs (C-01, AC-01, etc.) unchanged
5. Use MUST/MUST NOT language for constraints per RFC 2119

5. Annotate one test

Add two comment lines to an existing test:

// @spec user-create
// @ac AC-01
test('creates user and returns 201', async () => { ... });

# @spec user-create
# @ac AC-01
def test_create_user_returns_201(): ...

// @spec user-create
// @ac AC-01
func TestCreateUser_Returns201(t *testing.T) { ... }

Source comments are enough for specter coverage. For specter coverage --strict, also expose user-create/AC-01 in the test title or print @spec and @ac during the test before running specter ingest.

6. Check your coverage

specter coverage

Spec ID        Tier  ACs  Covered  Coverage  Status
user-create    T2    3    1        33%       FAIL   ← below T2's 80% threshold
  uncovered: AC-02, AC-03

A tier-2 spec needs 80% coverage to pass; tier-1 needs 100%; tier-3 needs 50%. Each @ac annotation you add moves the percentage up. Once user-create hits 80%+, status flips to PASS and specter sync can succeed.

7. Run the full pipeline

specter sync

PASS parse:    1 spec parsed
PASS resolve:  no dependency issues
PASS check:    0 errors
PASS coverage: thresholds met

All checks passed.

Add this to CI and you're protected.

What's next?

Getting Started — full walkthrough from zero specs to 100% coverage, with AI prompts for every step and VS Code workspace guide
CLI Reference — every command and flag
AI Prompts — ready-to-use prompts for the full SDD loop
FAQ — "Do I need to migrate my existing specs?"