What is SpecLeft?

SpecLeft is a planning-first CLI and pytest plugin that makes developer intent visible before code is written. It helps teams keep specs and tests aligned without changing how they build software.

Core Philosophy

Modern software fails not because code is broken, but because intent was misaligned. This is particularly true in systems built with autonomous AI agents. SpecLeft shifts validation to the left-most point of the development lifecycle: the planning phase.

Autonomous agent-driven projects amplify common failure modes:

Ambiguous goals: “Make it better” or “refactor safely” is not a testable target.
Hidden assumptions: agents fill gaps with plausible defaults that may be incorrect.
Spec drift: plans, code, and tests diverge quickly as agents iterate.
Non-determinism: retries and tool calls create different outcomes for the “same” task.
Boundary mistakes: integrations (APIs, auth, data contracts) break when intent isn’t explicit.
Accountability gaps: it becomes unclear what was requested vs. what was produced.

TDD has limitations; where in reality, tests are often written after code, which is insufficient for agent-driven systems that need to show intent is clear for the code owners.

Writing tests after code means you are validating implementation rather than intent. SpecLeft flips this by generating test skeletons from feature specs, ensuring that what gets built aligns with what was planned.

SpecLeft addresses these challenges by making feature intent explicit, testable, and trackable from the start without the need for heavy overhead with BDD frameworks.

Why Spec Driven Development?

By defining feature specs alongside your code, you enable:

Visible coverage of intended behavior
Drift detection between spec and implementation
Self-documenting feature requirements into readable overviews
Collaborative planning between product, engineering, and QA
Early feedback loops before code is written

How it works

SpecLeft runs offline as a CLI in your local environment and CI pipeline. It turns specs into test skeletons and tracks implemented behavior vs. skipped intent.

SpecLeft is framework-agnostic and works with any Python codebase using pytest. It focuses on what to build rather than how to build it.

This tool never changes your development workflow. You can continue writing code and tests as you normally would. SpecLeft simply adds a layer of intent validation on top.

specleft plan --dry-run
specleft test skeleton --dry-run
specleft status

Quick start

pip install specleft
specleft plan
specleft test skeleton
specleft status