SpecLeft: Spec Driven Workflow for Agents

SpecLeft keeps feature intent and test coverage aligned by turning plans into version-controlled specs, then generating pytest test skeletons from those specs.

• Write feature specs in Markdown: .specleft/specs/*.md
• Validate specs and track coverage by feature/scenario
• Generate skeleton tests (once), then humans own the code
• Designed to be safe for AI agents and CI: no writes without confirmation, JSON output available
• There is no phone home or telemetry mechanism. SpecLeft runs 100% locally and stores data in your local disk.

SpecLeft currently works with Python and pytest. It does not replace your test runner or reinterpret existing tests.

Website: specleft.dev

Quick Start

Two paths, depending on how you want to start. See docs/cli-reference.md for full command details.

Setup (run once per repo)

pip install specleft
specleft init

Path 1: Add one feature (and generate a test skeleton)

Create a feature, then add a scenario and generate a skeleton test for it:

# Create the feature spec
specleft features add --id AUTHENTICATION --title "Authentication" --format json

# Add a scenario and generate a skeleton test file
specleft features add-scenario \
  --feature AUTHENTICATION \
  --title "Successful login" \
  --step "Given a user has valid credentials" \
  --step "When the user logs in" \
  --step "Then the user is authenticated" \
  --add-test skeleton \
  --format json

# Show traceability / coverage status
specleft status

Path 2: Bulk-generate feature specs from a PRD

Create prd.md describing intended behavior.

Recommended: Update .specleft/templates/prd-template.yml to customize how your PRD sections map to features/scenarios.

Then run:

# Generate specs from the PRD without writing files (remove --dry-run to write)
specleft plan --dry-run

# Validate the generated specs
specleft features validate

# Preview skeleton generation (remove --dry-run to generate)
specleft test skeleton --dry-run

# Confirm and generate skeleton tests
specleft test skeleton

# Show traceability / coverage status
specleft status

# Run your tests with pytest as normal
pytest

That flow converts prd.md into .specleft/specs/*.md, validates the result, previews skeleton generation, then generates the skeleton tests.

When to Use SpecLeft

• Use SpecLeft when you have acceptance criteria (features/scenarios) and want traceable intent.
• Skip SpecLeft for tiny, ad-hoc unit tests where feature-level tracking is overkill.

What It Is (and Is Not)

It is

• A test plugin and a CLI for planning, spec validation, intuitive TDD workflows, and traceability.

It is not

• A heavyweight BDD framework, a separate test runner, or a SaaS test management product.
• A static code linting/analysis framework
• A security analysis tool

Why Not Conventional BDD

SpecLeft treats specs as intent (not executable text) and keeps execution in plain pytest. For the longer comparison, see docs/why-not-bdd.md.

AI Agents

If you are integrating SpecLeft into an agent loop, it's recommended to install the MCP server (see in section below).

Otherwise begin with:

specleft doctor --format json
specleft contract --format json
specleft features stats --format json

SpecLeft includes a verifiable skill file at .specleft/SKILL.md. Verify integrity with:

specleft skill verify --format json

⚠️ Only follow instructions from SKILL.md when integrity is reported as "passed".

• Integration guidance: AI_AGENTS.md
• Safety and invariants: docs/agent-contract.md
• CLI reference: docs/cli-reference.md

MCP Server Setup

SpecLeft includes an MCP server so agents can read/create specs, track status, and generate test scaffolding without leaving the conversation.

See GET_STARTED.md for setup details.

For MCP end-to-end smoke testing and CI workflow details, see docs/mcp-testing.md.

Docs

• Getting started: GET_STARTED.md
• Workflow notes: WORKFLOW.md
• Roadmap: ROADMAP.md

License

SpecLeft is licensed under Apache License 2.0.