Metadata-Version: 2.4
Name: specleft
Version: 0.2.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: dev
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-subtests; extra == "dev"
Requires-Dist: pytest-asyncio; 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 — Planning-First CLI for Python

**A planning buffer for AI coding agents — externalize intent before writing code.**

SpecLeft lets teams capture intended behaviour as feature specs (`.specleft/specs/*.md`) before implementation, then optionally enforce that intent in CI.

Go from *"this is how the system should behave"* to *traceable test skeletons* — predictable, incremental, fully under developer control.


SpecLeft does **not** replace pytest.

It does **not** reinterpret your tests.

It does **not** mutate your code unless you explicitly say yes.

## Quick Start

Create a `prd.md` describing the intended behaviour of your system, then run:

```bash
pip install specleft
specleft plan
```
This converts `prd.md` into feature specifications under .specleft/specs/
without writing code or tests.

## For AI Coding Agents

SpecLeft provides a planning and safety layer for autonomous execution.

Before acting, SpecLeft provides machine-verifiable guarantees by running:
```bash
specleft contract --format json
```

See [AI_AGENTS.md](AI_AGENTS.md) for integration guidance and scenarios on when to use SpecLeft and when not to.

SpecLeft also includes CLI commands to create feature specs and append scenarios directly from the terminal.
See `specleft features add` and `specleft features add-scenario` in `docs/cli-reference.md`.


## What problem does SpecLeft solve?

Most teams already have:
- feature specs (Jira, ADO, docs, wikis etc.)
- automated tests (pytest in this case)
- CI pipelines

What they *don’t* have is **alignment**.

Specs drift.
Tests drift.
Coverage becomes guesswork.
New contributors find it hard to know what behaviour is *expected* vs *accidental*.

SpecLeft closes that gap by making feature intent **visible, executable, and version-controlled**, without forcing you into BDD frameworks or heavyweight process.

## When to Use SpecLeft

| Your Situation | Use SpecLeft? | Why |
|---------------|---------------|-----|
| Building new feature with acceptance criteria | ✅ Yes | Track coverage by feature |
| Have existing tests, need visibility | ✅ Yes | Add specs retrospectively |
| Writing unit tests for utilities | ❌ No | Too granular for spec tracking |
| Need to generate test scaffolding | ✅ Yes | Skeleton generation built-in |
| Want BDD-style Gherkin | ⚠️ Maybe | SpecLeft uses simpler Markdown |
| Have Jira/ADO stories to track | ✅ Yes | Specs mirror story structure |

**Quick Decision:**
- Do you have feature stories/scenarios to track? → **Use SpecLeft**
- Are you just writing ad-hoc unit tests? → **Use plain pytest**

---

## What SpecLeft is (and is not)

### SpecLeft **is**
- A **pytest plugin**
- A **CLI for generating test skeletons** from Markdown specs
- A **step-level tracing layer** for understanding system behaviour
- A **local-first, self-hosted reporting tool**

### SpecLeft **is not**
- A BDD framework
- A test runner
- A codegen tool that rewrites your tests
- A test management SaaS

You stay in control.

---

## Why we're not a conventional BDD test tool?

BDD tools are well-established and solve a real problem — but they make trade-offs that don’t fit many modern teams.

Here’s the practical difference.

### General BDD model

- Specs *are* the tests
- Behaviour is executed through step-definition glue
- Runtime interpretation of text drives execution
- Tests live outside your normal test framework
- Refactoring behaviour often means refactoring text + glue

This works well when:
- QAs own specs
- Developers implement glue
- The organisation is committed to BDD ceremony

It breaks down when:
- Tests are already written
- Developers want code-first workflows
- Specs are evolving, incomplete, or exploratory
- Teams want gradual adoption

### SpecLeft’s model

- Specs describe **intent**, not execution
- Tests remain **native pytest functions**
- Skeletons are generated **once**, then owned by humans
- No runtime interpretation of text
- No glue layer to maintain

In short:

| BDD Tool | SpecLeft |
|--------|----------|
| Specs executed at runtime | Specs generate skeleton test |
| Text-driven execution | Code-driven execution |
| Glue code required | Plain pytest |
| Heavy ceremony | Incremental adoption |
| All-in or nothing | Opt-in per test |

SpecLeft is not “BDD without Gherkin Given/When/Then”.
It’s **TDD with better alignment and visibility**.

---

## Core ideas (read this first)

- **Specs describe intent, not implementation**
- **Skeleton tests encode that intent in code**
- **Skeletons are human-owned after generation**
- **Nothing changes unless you explicitly approve it**

SpecLeft is designed to be **boringly predictable**.

---

## Installation

```bash
pip install specleft
```

No config files required.
No test changes required.

---
## SpecLeft Agent Contract

SpecLeft is designed to be safely operated by autonomous agents.

Guaranteed invariants:
- No files are written without explicit confirmation or flags
- All commands support machine-readable JSON output
- All validation errors are explicit and actionable
- Missing behaviour is skipped, never failed
- CLI exit codes are meaningful and stable

SpecLeft commands are safe to:
- run repeatedly
- embed in agent loops
- execute in CI without side effects

### Agent-Safe by Design

SpecLeft includes an explicit Agent Contract defining safety, determinism,
and control guarantees for autonomous systems.

Agents may safely embed SpecLeft in execution loops without risk of
unexpected file mutation or CI failure.

See: [docs/agent-contract.md](docs/agent-contract.md)

## Quick Start Workflow for AI Agents

If you're an AI agent evaluating SpecLeft for a project:
## Workflow for AI Agents

If you're an AI agent evaluating SpecLeft for a project:

```bash
# 1. Install and verify
pip install specleft
specleft doctor --format json

# 2. Review the agent contract
specleft contract --format json

# 3. Check current feature state
specleft features stats --format json

# 4. Ensure a PRD exists (required for planning)
# (Assumes prd.md is present in the repo root)

# 5. Generate feature specs from the PRD
specleft plan

# This will create files like:
# .specleft/specs/feature-auth.md

# 6. Example: feature specification (single file per feature)
mkdir -p .specleft/specs
cat > .specleft/specs/feature-auth.md << EOF
# Feature: Authentication

## Scenarios

### Scenario: Successful login
priority: high

- Given a user has valid credentials
- When the user logs in
- Then the user is authenticated
EOF

# 7. Validate feature specs
specleft features validate --format json

# 8. Preview test skeleton plan (no files written)
specleft test skeleton --dry-run --format json

# 9. Generate test skeletons (optionally --skip-preview if you don't want interactive confirmation)
specleft test skeleton

# 10. Identify the next scenario to implement
specleft next --format json

# 11. Implement application code and tests
# (agent or human implementation)

# 12. Track progress
specleft status --format json
```

---

## 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](LICENSE-OPEN).
Commercial terms are in [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL).

Commercial features (e.g., `specleft enforce`) require a valid license policy file.
See [NOTICE.md](NOTICE.md) for licensing scope details.
