speclock

Why another rules tool? Rules files are context. They can be forgotten, diluted, or overridden during a long coding session. SpecLock turns those rules into checks that run before edits, shell commands, and commits.

See the difference

CLAUDE.md:  Never modify the authentication system.

You:        Add social login to the login page.

Without SpecLock
Claude:     I'll update the auth flow and add an OAuth provider...

With SpecLock (strict mode)
SpecLock:   BLOCKED — conflicts with "Never modify the authentication system"
            Match: login → auth → authentication
            The action was denied before the files changed.

SpecLock uses semantic conflict detection rather than simple keyword matching. It catches indirect actions such as “clean up old patient data,” “streamline checkout,” or “temporarily disable MFA” when they violate an active constraint.

60-second setup

Run this from the project you want to protect:

npx speclock@latest protect          # reads existing AI rule files; advisory by default
npx speclock@latest doctor           # confirms rules, hooks, and integration

When the advisory output looks right, enable blocking:

npx speclock@latest protect --strict

No account is required. SpecLock runs locally by default, and advisory mode never blocks a change.

Install as a Claude Code plugin

Inside Claude Code, run:

/plugin marketplace add sgroy10/speclock
/plugin install speclock@speclock-marketplace

Then protect the current project once:

npx speclock@latest protect          # warnings only
npx speclock@latest protect --strict # block confirmed conflicts

The plugin automatically starts SpecLock's MCP server and checks Claude Code Write, Edit, and Bash actions before execution. It includes all 51 MCP tools and works alongside your existing CLAUDE.md.

Install on other coding agents

SpecLock is packaged for multiple agent ecosystems, but the enforcement level depends on what each host exposes:

Platform	Install/discovery path	Protection level
Claude Code	Native marketplace plugin above	Native pre-action checks for Write, Edit, and Bash
Gemini CLI	Install this repository as a Gemini extension	MCP-assisted checks plus project context
Cursor	Agent Plugin / Cursor marketplace package	MCP-assisted checks plus rules
Codex	Repository Codex plugin in plugins/speclock	MCP-assisted checks plus $speclock-guardrails skill
GitHub Copilot CLI	Add this repository as a plugin marketplace	MCP-assisted checks plus bundled plugin context
Cline	MCP server; curated marketplace submission in progress	MCP-assisted checks
Windsurf	speclock mcp install windsurf	MCP-assisted checks plus rules
Any Git client or CI	speclock protect	Commit/CI enforcement independent of the coding agent

MCP-assisted means the agent can call SpecLock before acting; it does not guarantee interception. Use speclock protect --strict and CI when a constraint must be enforced regardless of the client.

SpecLock has a different job from memory and skills: memory recalls context, skills provide procedures, and SpecLock verifies planned actions against explicit constraints. It reduces constraint drift; it cannot guarantee factual correctness or make a model hallucination-free.

Repository installs supported by current clients:

gemini extensions install https://github.com/sgroy10/speclock
copilot plugin marketplace add sgroy10/speclock
copilot plugin install speclock@speclock-marketplace

What you get

Capability	What it does
Pre-action checks	Reviews Claude Code writes, edits, and shell commands before they run
Semantic constraints	Detects synonyms, euphemisms, compound requests, and indirect violations
Git enforcement	Adds a second guard at commit time
Advisory and strict modes	Start with warnings; opt in to hard blocking when ready
Audit trail	Records decisions in a tamper-evident HMAC chain
MCP integration	Exposes 51 tools to Claude Code, Cursor, Codex, Windsurf, and Cline
Shareable save receipts	Shows what SpecLock prevented with speclock wins

Proven in the open

• 10,000+ npm downloads before the native Claude Code plugin release.
• 1,043 automated tests across 24 suites, including adversarial conflicts, false-positive cases, patch analysis, enforcement, auth, and compliance.
• MIT licensed and inspectable end to end.
• Local-first defaults with optional remote features clearly separated.

Commands you will use most

speclock protect                      # extract constraints and install project protection
speclock protect --strict             # enable hard enforcement
speclock doctor                       # verify the complete setup
speclock check "action description"   # preview whether an action conflicts
speclock add-lock "rule"              # add a constraint explicitly
speclock list-locks                    # inspect active constraints
speclock enforce hard|advisory         # switch enforcement mode
speclock mcp install <client>          # Claude Code, Cursor, Windsurf, Cline, or Codex
speclock wins                          # create a shareable save receipt

Full reference: npx speclock@latest help

New in v5.8.0

• Portable Agent Plugin packaging for Cursor-compatible discovery.
• Gemini CLI extension packaging with MCP startup and constraint context.
• Codex plugin with a $speclock-guardrails skill and pinned MCP server.
• GitHub Copilot CLI compatibility through the repository marketplace.
• Explicit per-platform enforcement labels: native hook, MCP-assisted, or Git/CI.

The Problem

AI coding tools have memory now. Claude Code has CLAUDE.md. Cursor has .cursorrules. Mem0 exists.

But memory without enforcement is useless.

Your AI remembers you use PostgreSQL — then switches to MongoDB because it "seemed better." Your AI remembers your auth setup — then rewrites it while "fixing" a bug. You said "never touch the payment logic" 3 sessions ago — the AI doesn't care.

Remembering is not respecting. No existing tool stops the AI from breaking what you locked.

How It Works

You set constraints. SpecLock enforces them — across sessions, across tools, across teams.

speclock lock "Never modify auth files"           → auto-guards src/auth/*.ts
speclock lock "Database must stay PostgreSQL"      → catches "migrate to MongoDB"
speclock lock "Never delete patient records"       → catches "clean up old data"
speclock lock "Don't touch the payment flow"       → catches "streamline checkout"

The semantic engine doesn't do keyword matching. It understands:

• "clean up old data" = deletion (euphemism detection)
• "streamline checkout" = modify payment flow (synonym + concept mapping)
• "temporarily disable logging" = disable logging (temporal evasion detection)
• "Update UI and also drop the users table" = hidden violation (compound splitter)

And it knows what's safe:

• "Enable audit logging" when the lock says "Never disable audit logging" → no conflict (intent alignment)

Quick Start by Platform

Bolt.new / Aider / Any npm Platform

npx speclock setup --goal "Build my app" --template nextjs

Creates SPECLOCK.md, injects rules into package.json, generates .speclock/context/latest.md. The AI reads these automatically.

Claude Code

Install the plugin using the commands above. For MCP-only setup without the plugin hooks, add this to .mcp.json:

{
  "mcpServers": {
    "speclock": {
      "command": "npx",
      "args": ["--yes", "speclock@5.8.0", "serve", "--project", "."]
    }
  }
}

Cursor / Windsurf / Cline

Same config — add to .cursor/mcp.json or equivalent.

Lovable (No Install)

1. Go to Settings → Connectors → New MCP server
2. Enter URL: https://speclock-mcp-production.up.railway.app/mcp
3. Paste project instructions into Knowledge

---

Why SpecLock Over Alternatives?

	Claude Memory	Mem0	.cursorrules	SpecLock
Remembers context	Yes	Yes	Manual	Yes
Blocks the AI from breaking things	No	No	No	Yes
Semantic conflict detection	No	No	No	Yes — covered by adversarial tests
Tamper-proof audit trail	No	No	No	HMAC-SHA256 chain
Hard enforcement (AI cannot proceed)	No	No	No	Yes
SOC 2 / HIPAA compliance exports	No	No	No	Yes
Encrypted storage (AES-256-GCM)	No	No	No	Yes
RBAC + API key auth	No	No	No	4 roles
Policy-as-Code DSL	No	No	No	YAML rules
Works on Bolt.new, Lovable, etc.	No	No	No	Yes

Other tools remember. SpecLock enforces.

---

Semantic Engine

Not keyword matching — semantic analysis with an optional Gemini Flash hybrid for grey-zone and cross-domain cases. The repository includes adversarial, false-positive, question-framing, patch-gateway, and diff-analysis test suites.

Under the hood: 65+ synonym groups · 80+ euphemism mappings · domain concept maps (fintech, e-commerce, IoT, healthcare, SaaS, payments, gaming, telecom, government) · intent classifier · compound sentence splitter · temporal evasion detector · verb tense normalization · UI cosmetic detection · safe-intent patterns · passive voice parsing — all in pure JavaScript. Gemini Flash hybrid for grey-zone cases ($0.01/1000 checks).

---

Hard Enforcement

Two modes:

Advisory (default):  AI gets a warning, decides what to do
Hard mode:           AI is BLOCKED — MCP returns isError, AI cannot proceed

speclock enforce hard   # Enable hard mode — violations above threshold are blocked

• Configurable threshold — default 70%. Only HIGH confidence conflicts block.
• Override with reason — speclock override <lockId> "JIRA-1234: approved by CTO" (logged to audit trail)
• Auto-escalation — lock overridden 3+ times → auto-flags for review

---

Enterprise Security

API Key Auth + RBAC

speclock auth create-key --role developer --name "CI Bot"
# → sk_speclock_a1b2c3... (shown once, stored as SHA-256 hash)

Role	Read	Write Locks	Override	Admin
viewer	Yes	—	—	—
developer	Yes	—	With reason	—
architect	Yes	Yes	Yes	—
admin	Yes	Yes	Yes	Yes

AES-256-GCM Encryption

export SPECLOCK_ENCRYPTION_KEY="your-secret"
speclock encrypt   # Encrypts brain.json + events.log at rest

PBKDF2 key derivation (100K iterations). Authenticated encryption. HIPAA 2026 compliant.

HMAC Audit Chain

Every event gets an HMAC-SHA256 hash chained to the previous event. Modify anything — the chain breaks.

$ speclock audit-verify

✓ Audit chain VALID — 247 events, 0 broken links, no tampering detected.

Compliance Exports

speclock export --format soc2    # SOC 2 Type II report (JSON)
speclock export --format hipaa   # HIPAA PHI protection report
speclock export --format csv     # All events for auditor spreadsheets

---

Policy-as-Code

Declarative YAML rules for organization-wide enforcement:

# .speclock/policy.yml
rules:
  - name: "HIPAA PHI Protection"
    match:
      files: ["**/patient/**", "**/medical/**"]
      actions: [delete, modify, export]
    enforce: block
    severity: critical

  - name: "No direct DB mutations"
    match:
      files: ["**/models/**"]
      actions: [delete]
    enforce: warn
    severity: high

Import and export policies between projects. Share constraint templates across your organization.

---

REST API v2

Real-time constraint checking, patch review, and autonomous systems:

# Patch Gateway (v5.1)
POST /api/v2/gateway/review        { description, files, useLLM }

# AI Patch Firewall (v5.2)
POST /api/v2/gateway/review-diff   { description, files, diff, options }
POST /api/v2/gateway/parse-diff    { diff }

# Typed constraint checking
POST /api/v2/check-typed    { metric, value, entity }
POST /api/v2/check-batch    { checks: [...] }

# SSE streaming (real-time violations)
GET  /api/v2/stream

# Spec Compiler
POST /api/v2/compiler/compile  { text, autoApply }

# Code Graph
GET  /api/v2/graph/blast-radius?file=src/core/memory.js
GET  /api/v2/graph/lock-map
POST /api/v2/graph/build

---

51 MCP Tools

Tool	What it does
speclock_init	Initialize SpecLock in project
speclock_get_context	Full context pack (the key tool)
speclock_set_goal	Set project goal
speclock_add_lock	Add constraint + auto-guard files
speclock_remove_lock	Soft-delete a lock
speclock_add_decision	Record architectural decision
speclock_add_note	Add pinned note
speclock_set_deploy_facts	Record deploy config

Tool	What it does
speclock_check_conflict	Semantic conflict check against all locks
speclock_set_enforcement	Switch advisory/hard mode
speclock_override_lock	Override with reason (audit logged)
speclock_override_history	View override audit trail
speclock_semantic_audit	Analyze git diff against locks
speclock_detect_drift	Scan for constraint violations
speclock_audit	Audit staged files pre-commit

Tool	What it does
speclock_session_briefing	Start session + full briefing
speclock_session_summary	End session + record summary
speclock_log_change	Log a change with files
speclock_get_changes	Recent tracked changes
speclock_get_events	Full event log (filterable)
speclock_checkpoint	Git tag for rollback
speclock_repo_status	Branch, commit, diff summary

Tool	What it does
speclock_suggest_locks	AI-powered lock suggestions
speclock_health	Health score + multi-agent timeline
speclock_apply_template	Apply constraint template
speclock_report	Violation stats + most tested locks

Tool	What it does
speclock_verify_audit	Verify HMAC chain integrity
speclock_export_compliance	SOC 2 / HIPAA / CSV reports
speclock_policy_evaluate	Evaluate policy rules
speclock_policy_manage	CRUD for policy rules
speclock_telemetry	Opt-in usage analytics

Tool	What it does
speclock_add_typed_lock	Add typed constraint (numerical/range/state/temporal)
speclock_check_typed	Check proposed values against typed constraints
speclock_list_typed_locks	List all typed constraints
speclock_update_threshold	Update typed lock thresholds

Tool	What it does
speclock_compile_spec	Compile natural language into structured constraints
speclock_build_graph	Build/refresh code dependency graph
speclock_blast_radius	Calculate blast radius of file changes
speclock_map_locks	Map locks to actual code files

Tool	What it does
speclock_review_patch	ALLOW/WARN/BLOCK verdict for proposed changes
speclock_review_patch_diff	Diff-native review with signal scoring + unified verdict
speclock_parse_diff	Parse unified diff into structured changes (debug/inspect)

Tool	What it does
speclock_sync_rules	Sync constraints to Cursor, Claude, Copilot, Windsurf, Gemini, Aider, AGENTS.md
speclock_list_sync_formats	List all available sync formats
speclock_replay	Replay a session's activity — what AI tried and what was caught
speclock_list_sessions	List available sessions for replay
speclock_drift_score	0-100 project integrity metric — how much AI deviated from intent
speclock_coverage	Lock Coverage Audit — find unprotected code areas
speclock_strengthen	Grade locks and suggest stronger versions

---

CLI

# Setup
speclock setup --goal "Build my app" --template nextjs

# Constraints
speclock lock "Never modify auth files" --tags auth,security
speclock lock remove <id>
speclock check "Add social login"              # Test before doing

# Enforcement
speclock enforce hard                          # Block violations
speclock override <lockId> "JIRA-1234"         # Override with reason

# Audit & Compliance
speclock audit-verify                          # Verify HMAC chain
speclock export --format soc2                  # Compliance report
speclock audit-semantic                        # Semantic pre-commit

# Git
speclock hook install                          # Pre-commit hook
speclock audit                                 # Audit staged files

# Templates
speclock template apply safe-defaults          # Vibe coding seatbelt (5 locks)
speclock template apply solo-founder           # Indie builder essentials (3 locks)
speclock template apply hipaa                  # HIPAA healthcare (8 locks)
speclock template apply api-stability          # API contract protection (6 locks)
speclock template apply nextjs                 # Next.js constraints
speclock template apply security-hardened      # Security hardening

# Sync to AI tools
speclock sync --all                            # Sync to ALL tools
speclock sync --format cursor                  # Cursor only
speclock sync --format claude                  # Claude Code only
speclock sync --preview windsurf               # Preview without writing

# Incident Replay
speclock replay                                # Replay last session
speclock replay --list                         # List sessions
speclock replay --session <id>                 # Replay specific session

# Project Health
speclock drift                                 # Drift Score (0-100)
speclock drift --days 7                        # Last 7 days only
speclock coverage                              # Lock Coverage Audit
speclock strengthen                            # Grade and improve locks

# Share & Stats
speclock wins                                  # Shareable "Save Receipt" (screenshot it!)
speclock wrapped                               # All-time + monthly recap (alias: recap)
speclock stats                                 # Your local usage dashboard
speclock badge                                 # Print README badges (6 variants + live badge)

# Auth
speclock auth create-key --role developer
speclock auth rotate-key <keyId>

# Policy
speclock policy init                           # Create policy.yml
speclock policy evaluate --files "src/auth/*"  # Test against rules

Full command reference: npx speclock help

---

Auto-Guard

When you lock something, SpecLock finds related files and injects a warning the AI sees when it opens them:

speclock lock "Never modify auth files"
→ Auto-guarded 2 files:
  🔒 src/components/Auth.tsx
  🔒 src/contexts/AuthContext.tsx

The AI opens the file and sees:

// ============================================================
// SPECLOCK-GUARD — DO NOT MODIFY THIS FILE
// LOCKED: Never modify auth files
// ONLY "unlock" or "remove the lock" is permission to edit.
// ============================================================

---

Architecture