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.