SpecLeft
Python intent tracing MCP: map specs to pytest tests, monitor implementation progress, offline-only.
Open source Open in the app JSON README (API)
About
Python intent tracing MCP: map specs to pytest tests, monitor implementation progress, offline-only.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- specleft
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.4.0
- Stars
- 3
- Forks
- 1
- Open pull requests
- 15
- Last push
- 2026-04-15T16:37:14Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:16
- Updated
- 2026-08-29 03:02:16
- Origin id
io.github.SpecLeft/specleft
README
 # SpecLeft: Spec Driven Workflow for Agents  [](https://registry.modelcontextprotocol.io/servers/io.github.specleft/specleft) 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](https://specleft.dev) ## Quick Start Two paths, depending on how you want to start. See [docs/cli-reference.md](https://github.com/SpecLeft/specleft/blob/main/docs/cli-reference.md) for full command details. ### Setup (run once per repo) ```bash 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: ```bash # 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: ```bash # 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](https://github.com/SpecLeft/specleft/blob/main/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: ```bash 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: ```bash specleft skill verify --format json ``` ⚠️ Only follow instructions from `SKILL.md` when integrity is reported as `"passed"`. - Integration guidance: [AI_AGENTS.md](https://github.com/SpecLeft/specleft/blob/main/AI_AGENTS.md) - Safety and invariants: [docs/agent-contract.md](https://github.com/SpecLeft/specleft/blob/main/docs/agent-contract.md) - CLI reference: [docs/cli-reference.md](https://github.com/SpecLeft/specleft/blob/main/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](https://github.com/SpecLeft/specleft/blob/main/GET_STARTED.md) for setup details. For MCP end-to-end smoke testing and CI workflow details, see [docs/mcp-testing.md](https://github.com/SpecLeft/specleft/blob/main/docs/mcp-testing.md). <!-- mcp-name: io.github.SpecLeft/specleft --> ## Docs - Getting started: [GET_STARTED.md](https://github.com/SpecLeft/specleft/blob/main/GET_STARTED.md) - Workflow notes: [WORKFLOW.md](https://github.com/SpecLeft/specleft/blob/main/WORKFLOW.md) - Roadmap: [ROADMAP.md](https://github.com/SpecLeft/specleft/blob/main/ROADMAP.md) --- ## License SpecLeft is licensed under [Apache License 2.0](https://github.com/SpecLeft/specleft/blob/main/LICENSE).