spectre

spectre

Spectre — a deterministic spec-driven Claude Code plugin. Vision → Spec → Evaluate → Lock → Implement → Verify, with three-tier pre-lock review and per-project resource locking.

Table of Contents

• Background
• Install
• Usage
• API
• Tests
• Maintainers
• Contributing
• License

Background

Spectre is a Claude Code plugin that turns a vague idea into a locked, machine-verifiable specification, then drives the agent to execute it step by step. Every spec is a six-view family — one perspective for the implementing agent, plus one each for the human user, integrator, operator, product input, and product output — locked together with cross-view consistency checks and calibrated against a catalog of real-world exemplars (curl, gh, systemd-journal, prometheus, …).

Three review tiers (deterministic AST, structural coverage, optional adversarial LLM) run before lock; block-severity findings prevent it. After lock, /implement walks the spec one atomic step at a time, gating each on a verification command, halting on risky actions, and persisting state across sessions and reboots.

Where plain Claude Code lets you chat with the agent and hope it stays on-track, Spectre makes the spec the canonical artifact: every action ties back to a numbered step you can audit, every halt has a verification gate, and drift is detectable across reboots. For the design rationale, the five invariants, and the full state machine, see docs/ARCHITECTURE.md.

Install

Requires Python 3.11+ (PEP 604 / PEP 585 syntax). Stdlib only — no third-party imports in production code.

Via Claude Code marketplace (recommended):

/plugins
→ Browse Marketplaces
→ Add Marketplace: https://github.com/Joncik91/Spectre
→ Install: spectre

The repo ships its own .claude-plugin/marketplace.json, so the GitHub URL is also the marketplace URL.

Manual symlink (for local development):

git clone https://github.com/Joncik91/Spectre.git
ln -s "$PWD/Spectre" ~/.claude/plugins/spectre

Restart Claude Code. SessionStart fires bin/hydrate.py; with no active spec yet you'll see SIGNAL: No active spec. Run /vision to begin.

First-run setup — Tier 3 review (optional)

Tier 3 runs an adversarial LLM reviewer (deepseek-v4-flash) before lock — catches missing context, factual errors, and attacker-view concerns the deterministic Tiers 1+2 can't. It is opt-in; Tiers 1+2 always run for free.

The first /vision run probes for DEEPSEEK_API_KEY (env var → ~/.spectre/secrets.env → $SPECTRE_SECRETS_FILE) and writes ~/.spectre/reviewer.toml recording your choice. Cost is ~$0.01–0.05 per spec. Full setup flow including secrets file, personal-rules, templates, and template-patches: docs/API.md.

Usage

Minimum viable sequence:

# 1. Lock a spec from a free-form vision
/vision Build a real-time order sync between Shopify and our warehouse

# 2. Run the active spec step by step
/implement

# 3. Verify-only re-check (no execution, no state advance)
/implement check

You stay in the loop: clarifying questions during the interview, confirming the locked spec, approving each halt. Block findings prevent lock until fixed.

Additional modes

# Auto mode — walk consecutive low-tier steps without re-prompting
/implement auto

# Multi-track (parallel work in one project)
/implement payments       # acquires res-port-8080 for track "payments"
/implement notifications  # queues if "payments" hasn't released yet

The hydrator re-injects the active spec and per-track scratchpad on every session start — resume mid-mission across reboots and Claude restarts. Switch missions: run /vision again; prior history (ADRs, eval sidecar) stays on disk.

Six-view at a glance

Every locked spec since v1.0 carries this shape: