Metadata-Version: 2.4
Name: specleft
Version: 0.3.0
Summary: A planning-first CLI for AI coding agents to externalize intent before writing code, with optional CI enforcement for Python projects.
Author-email: SpecLeft <richard@specleft.dev>
License: SpecLeft Dual Licensing Notice
        
        SpecLeft is dual-licensed.
        
        Open Source (Apache 2.0):
        	See LICENSE-OPEN
        
        Commercial License:
        	See LICENSE-COMMERCIAL
        
Project-URL: Homepage, https://github.com/SpecLeft/specleft
Project-URL: Issues, https://github.com/SpecLeft/specleft/issues
Project-URL: Documentation, https://github.com/SpecLeft/specleft/tree/main/docs
Project-URL: Repository, https://github.com/SpecLeft/specleft
Keywords: ai,agents,testing,bdd,behaviour,behavior,specification,intent,claude,gemini,gpt,copilot,autonomous,verification,plan,pytest,plugin,ci,feature-specs,sdd
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Environment :: Console
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-COMMERCIAL
License-File: LICENSE-OPEN
License-File: NOTICE.md
Requires-Dist: pytest>=7.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: python-slugify>=8.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: cryptography>=41.0.0
Provides-Extra: mcp
Requires-Dist: fastmcp<3; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-subtests; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: tiktoken; extra == "dev"
Requires-Dist: black==26.1.0; extra == "dev"
Requires-Dist: ruff==0.8.3; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

![SpecLeft social preview](.github/assets/specleft-social-preview.png)

# SpecLeft: Planning-First Workflow for pytest

![Spec coverage](.github/assets/spec-coverage-badge.svg)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](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 works with 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 pytest plugin plus a CLI for planning, spec validation, intuitive TDD workflows, and traceability.
- It is not a BDD framework, a separate test runner, or a SaaS test management product.

## 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, start here:

```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 -->

## CI Enforcement Early Access

Want to enforce feature coverage and policy checks in CI with `specleft enforce`? Join Early Access to get setup guidance and rollout support.

Learn more: [specleft.dev/enforce](https://specleft.dev/enforce)

## 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 **dual-licensed**:

- **Open Core (Apache 2.0)** for the core engine and non-commercial modules
- **Commercial License** for enforcement, signing, and license logic

Open-source terms are in [LICENSE-OPEN](https://github.com/SpecLeft/specleft/blob/main/LICENSE-OPEN).
Commercial terms are in [LICENSE-COMMERCIAL](https://github.com/SpecLeft/specleft/blob/main/LICENSE-COMMERCIAL).

Commercial features (e.g., `specleft enforce`) require a valid license policy file.
See [NOTICE.md](https://github.com/SpecLeft/specleft/blob/main/NOTICE.md) for licensing scope details.
