Core Concepts

SpecLeft is an intent-first CLI and pytest plugin. It makes expected behaviour explicit before code is written, then verifies that intent stays implemented as your code evolves — especially AI-written code.

SpecLeft is built around three principles:

• Intent is explicit — behaviour is declared in specs, not inferred from code
• Enforcement is deliberate — CI only blocks when you opt in
• Verification beats inference — SpecLeft checks completeness, not correctness

Everything else follows from these rules.

Intent vs. implementation

SpecLeft focuses on what a feature should do, not how you implement it.

Specs describe behaviour. Tests implement it.

That separation means:

• Specs are plain Markdown files committed to your repo
• Tests remain normal pytest tests
• Nothing changes unless you explicitly run a SpecLeft command

SpecLeft never rewrites code or alters behaviour automatically.

Feature specs

Specs live under .specleft/specs/ and describe expected behaviour at the feature and scenario level.

.specleft/specs/
└── authentication.md

These files are designed to be:

• easy to review in pull requests
• stable across refactors
• readable by humans and machines

They represent declared intent — nothing more, nothing less.

Skeleton tests

SpecLeft can generate test skeletons directly from feature specs. This scaffolding outlines the intended test structure.

Skeletons provide a starting point for implementation. Once created, SpecLeft does not alter them.

These tests are skipped by default until implemented:

@specleft(feature_id="authentication", scenario_id="successful-login", skip=True)
def test_successful_login():
    with specleft.step("Given a user has valid credentials"):
        pass # TODO: implement test step

This keeps CI green while making unimplemented behaviour visible and trackable.

Coverage is about intent

SpecLeft coverage is not code coverage.

It answers a different question:

“Which declared scenarios are implemented?”

You can inspect this with:

specleft status
specleft coverage

Coverage reflects intent completeness, not line execution.

Enforcement is opt-in

SpecLeft does not enforce anything by default.

Enforcement is a separate command, driven by a signed policy file:

specleft enforce

When enabled, enforcement checks:

• declared priorities
• implementation completeness
• policy rules you chose

CI only blocks when a declared requirement is unmet.

Agent-safe defaults

SpecLeft is designed to run safely in automated and agent-driven workflows:

• No file writes without confirmation or --force
• Deterministic output for identical inputs
• --format json available on all commands

See the Agent Contract for the full guarantees.