spec-probe

Check code against functional requirements in a spec (.md / .docx / .pdf). Use VS Code Copilot chat (/spec-cover, …) or the spec-probe CLI.

Workflow Overview

1. One-Time Setup

Step 1: Install & Skills

pip install spec-probe
spec-probe-skill --vscode

• Installs spec-probe and sets up Copilot skills in ~/.copilot/skills/.
• Initializes user directory and .venv under ~/.config/spec-probe/.
• Reload VS Code after running spec-probe-skill.

Optional for Linux: sudo apt install ripgrep (faster grep search).

Step 2: Authenticate & API Keys (.env)

GitHub Copilot Token

spec-probe-copilot-login

1. Open https://github.com/login/device in your browser.
2. Enter the 8-character code displayed in the terminal.
3. Token is saved automatically to COPILOT_GITHUB_TOKEN in ~/.config/spec-probe/.env.

Exacode API Key (Optional)

Used for auxiliary LLM jobs (enrich, translate, wiki, report).

1. Open http://exacode-chat.lge.com/key/ (or clear and re-create your key).
2. Copy Key 2 (EXACODE SWE API).
3. Add to ~/.config/spec-probe/.env:

   EXACODE_API_KEY="your_key_2_here"
   EXACODE_BASE_URL="http://exacode-chat.lge.com/v1"
   

(Details: Exacode for Copilot Chat)

Step 3: Configure Target Paths (config.yaml)

Edit ~/.config/spec-probe/config.yaml (use absolute paths):

input:
  module_path: /abs/path/to/your/app
  spec_path: /abs/path/to/spec.docx
  related_modules:
    # paths:
    #   - /abs/path/to/shared/service

Step 4: Index Code with Codegraph (Optional)

Accelerates symbol search and call-graph expansion across large C/C++ codebases:

spec-probe-codegraph

Reads module_path and related_modules.paths from config.yaml automatically. You can also specify paths directly: spec-probe-codegraph /path1 /path2. Tests and mocks are excluded automatically. Re-running syncs changes.

Step 5: Draft Domain Pack (Run once per module)

In VS Code Copilot chat:

/spec-pack

Scans your module code and draft a domain pack with keywords, architecture layers, and terminology under ~/.config/spec-probe/packs/.

Step 6: Parse Spec (Run once per spec)

In VS Code Copilot chat:

/spec-cover parse spec summary

Parses the requirements document into a structured catalog cached under ~/.config/spec-probe/reports/specs/ so subsequent verifications are fast.

2. Daily Workflow (VS Code Copilot Chat)

Once one-time setup is complete, use chat for regular verification:

Step 1: Verify Requirements (/spec-cover)

• Verify a specific requirement:

  /spec-cover verify FR-001
  

• Or verify by requirement text:

  /spec-cover check requirement: The module shall initialize within 500ms
  

• Or verify a section:

  /spec-cover verify section 3.2
  

(Note: In Copilot chat, typing naturally without /spec-cover like verify FR-001 also works via auto-intent matching, but /spec-cover ... is recommended for explicit routing).

Step 2: Export Report File

After verification completes in chat, type:

/spec-cover write report

Generates a full Markdown report under ~/.config/spec-probe/reports/verifications/ with clickable file links and evidence snippets.

Step 3: Audit Report (/spec-audit)

/spec-audit

Treats tool verdicts as hypotheses, validates evidence chains directly against source code, and confirms any actual implementation gaps.

CLI (optional)

spec-probe verify --module /abs/app --spec /abs/spec.md --fr FR-001
spec-probe check "The module shall …"
spec-probe parse --spec /abs/spec.md --summary

Paths default from ~/.config/spec-probe/config.yaml when omitted.