Metadata-Version: 2.4
Name: specleft
Version: 0.1.1
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: PolyForm Shield License 1.0.0
        <https://polyformproject.org/licenses/shield/1.0.0>
        
        ## Acceptance
        In order to get any license under these terms, you must agree
        to them as both strict obligations and conditions to all
        your licenses.
        
        ## Copyright License
        Copyright (c) 2026 SpecLeft Authors
        
        The licensor grants you a copyright license for the
        software to do everything you might do with the software
        that would otherwise infringe the licensor's copyright
        in it for any permitted purpose. However, you may
        only distribute the software according to [Distribution
        License](#distribution-license) and make changes or new works
        based on the software according to [Changes and New Works
        License](#changes-and-new-works-license).
        
        ## Distribution License
        The licensor grants you an additional copyright license
        to distribute copies of the software. Your license
        to distribute covers distributing the software with
        changes and new works permitted by [Changes and New Works
        License](#changes-and-new-works-license).
        
        ## Notices
        You must ensure that anyone who gets a copy of any part of
        the software from you also gets a copy of these terms or the
        URL for them above, as well as copies of any plain-text lines
        beginning with `Required Notice:` that the licensor provided
        with the software. For example:
        
        > Required Notice: Copyright SpecLeft Authors
        
        ## Changes and New Works License
        The licensor grants you an additional copyright license to
        make changes and new works based on the software for any
        permitted purpose.
        
        ## Patent License
        The licensor grants you a patent license for the software that
        covers patent claims the licensor can license, or becomes able
        to license, that you would infringe by using the software.
        
        ## Noncompete
        Any purpose is a permitted purpose, except for providing any
        product that competes with the software or any product the
        licensor or any of its affiliates provides using the software.
        
        ## Competition
        Goods and services compete even when they provide functionality
        through different kinds of interfaces or for different technical
        platforms. Applications can compete with services, libraries
        with plugins, frameworks with development tools, and so on,
        even if they're written in different programming languages
        or for different computer architectures. Goods and services
        compete even when provided free of charge. If you market a
        product as a practical substitute for the software or another
        product, it definitely competes.
        
        ## New Products
        If you are using the software to provide a product that does
        not compete, but the licensor or any of its affiliates brings
        your product into competition by providing a new version of
        the software or another product using the software, you may
        continue using versions of the software available under these
        terms beforehand to provide your competing product, but not
        any later versions.
        
        ## Discontinued Products
        You may begin using the software to compete with a product
        or service that the licensor or any of its affiliates has
        stopped providing, unless the licensor includes a plain-text
        line beginning with `Licensor Line of Business:` with the
        software that mentions that line of business.
        
        ## Sales of Business
        If the licensor or any of its affiliates sells a line of
        business developing the software or using the software to
        provide a product, the buyer can also enforce the Noncompete
        section for that product.
        
        ## Fair Use
        You may have "fair use" rights for the software under the
        law. These terms do not limit them.
        
        ## No Other Rights
        These terms do not allow you to sublicense or transfer any of
        your licenses to anyone else, or prevent the licensor from
        granting licenses to anyone else. These terms do not imply
        any other licenses.
        
        ## Patent Defense
        If you make any written claim that the software infringes or
        contributes to infringement of any patent, your patent license
        for the software granted under these terms ends immediately. If
        your company makes such a claim, your patent license ends
        immediately for work on behalf of your company.
        
        ## Violations
        The first time you are notified in writing that you have
        violated any of these terms, or done anything with the software
        not covered by your licenses, your licenses can nonetheless
        continue if you come into full compliance with these terms,
        and take practical steps to correct past violations, within
        32 days of receiving notice. Otherwise, all your licenses
        end immediately.
        
        ## No Liability
        ***As far as the law allows, the software comes as is, without
        any warranty or condition, and the licensor will not be liable
        to you for any damages arising out of these terms or the use
        or nature of the software, under any kind of legal claim.***
        
        ## Additional Restrictions
        In addition to the terms above, you may not sell, license, or
        commercially distribute SpecLeft Artefacts.
        
        "SpecLeft Artefacts" means any rules, policies, enforcement
        configurations, scenario/spec bundles, or other machine-readable
        or structured content that is primarily intended to be used with,
        interpreted by, enforced by, or executed via the software
        (including its CLI, plugins, or validators), whether distributed
        alone or as part of a bundle.
        
        ## Definitions
        The licensor is the individual or entity offering these terms,
        and the software is the software the licensor makes available
        under these terms. You refers to the individual or entity
        agreeing to these terms.
        
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
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
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: black==24.10.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 (`features/*.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 features/
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.


## 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 features/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:
# features/feature-auth.md

# 6. Example: feature specification (single file per feature)
cat > features/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 **source-available** and licensed under the **PolyForm Shield License 1.0.0** with additional restrictions.

### ✅ You are free to
- Use SpecLeft for personal, educational, or internal company use
- Run it locally, in CI/CD, or as part of automated workflows
- Fork the repository and modify it for your own needs
- Use SpecLeft with AI agents to build and test software products

### 🚫 You may not
- Sell SpecLeft itself
- Offer SpecLeft as a hosted or managed service
- Build or sell a product that directly competes with SpecLeft

### 🤝 Why this license exists
This license is intended to:
- Keep SpecLeft free for personal, educational, and internal use
- Enable AI-assisted software development
- Protect the project from direct commercial competition

These restrictions are defined by the PolyForm Shield License.

### 📄 Full license text
See the full license in the [`LICENSE`](./LICENSE) file or at:
https://polyformproject.org/licenses/shield/1.0.0/

### Quick rule of thumb
> If you’re using SpecLeft **to build software**, you’re fine.

> If you’re using SpecLeft **to sell SpecLeft**, you need permission.
