speculator

In an agentic world, the craft that used to live in the developer's head needs to live in the specification.

Agents can reason, decompose, and build — but they can't fill gaps from decades of domain intuition. The spec is where intent transfers from human to agent. We built Speculator because a great spec means the agent barely needs to improvise.

📖 Read the full manifesto: Quality In, Quality Out →

📝 Read the series: The Tax Nobody's Measuring · The Specification Tax

Speculator

A Claude Code plugin that enforces a 7-stage quality pipeline (4 required + 3 opt-in gates) on agentic development workflows with LLM-as-judge spec scoring, git worktree isolation, and in-repo evidence artifacts. Spec + Evaluator = Speculator.

Speculator is being built toward an explicit goal: an anti-dark-code pipeline — a workflow that won't ship code unless intent, behavior, and comprehension can all be evidenced. Today it covers spec quality (Gate 1), eval intent (Gate 2a), code quality (Gate 2), eval quality (Gate 2b), comprehension (Gate 2c, experimental), code review (Gate 3), and evidence packaging (Gate 4). Gate 2c closes the last gap between "tests pass" and "any human or agent could explain what shipped" — its calibration corpus is the remaining open work. See ROADMAP.md.

Prerequisites

• Claude Code — required runtime (the plugin exposes slash commands inside Claude Code)
• beads CLI — git-backed issue tracking for traceability (npm install -g beads-cli)
• git (2.20+) — worktree support for feature isolation

Installation

# Add the marketplace (one-time)
claude plugin marketplace add DMokong/claude-plugins

# Install the plugin
claude plugin install speculator@dmokong-plugins --scope project

# Bootstrap your project
/spec doctor --init

/spec doctor --init will create a default .claude/sdlc.local.md config and verify prerequisites. The pre-commit gate hook ships with the plugin and registers automatically — no setup step needed.

Quick Start

Step by step

/spec doctor              # verify environment is healthy
/spec start               # create spec + worktree + beads epic

Now brainstorm before you spec. Use Claude's brainstorming skill to explore intent, clarify requirements, and design your approach — before committing anything to the spec. The brainstorm is where ambiguity dies and intent crystallizes.

# brainstorm your feature (Superpowers skill)
# → explores intent, asks clarifying questions, proposes approaches with trade-offs
# → produces a design-approved plan ready to be formalized

/spec create              # Speculator turns your brainstormed plan into a formal spec.md
/spec score               # Gate 1: automated spec quality scoring
/spec implement           # create plan + beads stories + execute
/spec review              # Gate 3: code review
/spec close               # Gate 4: evidence package + deliver to main (merge or PR)

One command

Give /spec run a brainstormed plan and it handles everything — creates the spec, scores it, improves it, implements it, reviews it, and merges it:

/spec run     # autonomous: create → score → improve → implement → review → merge

This is designed to scale across multiple agents. Each agent gets a brainstormed plan, runs /spec run in its own worktree, and delivers a quality-gated feature independently.

Both /spec and /sdlc prefixes work — they're equivalent.

Example: A Feature From Start to Finish

Here's what it actually looks like to build a feature with Speculator.

1. Start and brainstorm

You: /spec start

Speculator: What feature are you building?

You: Add a webhook notification system for order events

Speculator: Created:
  ✅ Spec: docs/specs/webhook-notifications/spec.md
  ✅ Worktree: .claude/worktrees/webhook-notifications/
  ✅ Epic: beads-a3f "Webhook notification system"

  Switched to worktree. Brainstorm your design, then run /spec create.

Now brainstorm. This is where the real work happens — before a single line of spec is written:

You: I want to add webhooks for order events. Let's brainstorm.

Claude: [explores intent] What's the main use case — are these for internal
        microservices, external integrations, or both?

You: External integrations. Third-party apps need to react to order changes.

Claude: [clarifying questions] A few things to nail down:
        • Which order events? Created, updated, cancelled, fulfilled?
        • Retry semantics — how many retries, what backoff?
        • Security — do we need payload signing?
        • Rate limiting per consumer?