Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 2 additions & 23 deletions AI_AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,27 +208,7 @@ At this point, your job is done until review.

Use this phrasing with users:

> β€œI’ve captured the intended behaviour so assumptions are explicit and can be enforced later in CI.”

---

## Enforcement Comes Later

SpecLeft supports policy enforcement, but **not by default**.

Enforcement is a *separate decision* that happens when:
- behaviour is agreed
- scenarios exist
- the team wants CI guarantees

Example (later):

```bash
specleft enforce specleft-policy.yml
```

Planning-first adoption is intentional.
Do not enforce prematurely.
> β€œI’ve captured the intended behaviour so assumptions are explicit and reviewable in CI.”

---

Expand All @@ -252,7 +232,6 @@ Proceed only if healthy.
- `specleft status --format json` β€” see implementation state
- `specleft next --format json` β€” find next scenario to implement
- `specleft coverage --format json` β€” coverage by feature
- `specleft enforce <policy.yml>` β€” enforce agreed intent in CI

Agents should treat JSON output as the **stable API**.

Expand All @@ -264,7 +243,7 @@ SpecLeft is designed to fail **loudly and explicitly**.

- Validation errors mean intent is unclear.
- Missing priority means intent is incomplete.
- Enforcement failures mean behaviour is not implemented.
- Test failures mean behaviour is not implemented.

Do not auto-fix intent without user approval.

Expand Down
23 changes: 1 addition & 22 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,26 +210,6 @@ Use this phrasing with users:

---

## Enforcement Comes Later

SpecLeft supports policy enforcement, but **not by default**.

Enforcement is a *separate decision* that happens when:
- behaviour is agreed
- scenarios exist
- the team wants CI guarantees

Example (later):

```bash
specleft enforce specleft-policy.yml
```

Planning-first adoption is intentional.
Do not enforce prematurely.

---

## Programmatic Use (Optional)

All SpecLeft commands support `--format json` for agent use.
Expand All @@ -250,7 +230,6 @@ Proceed only if healthy.
- `specleft status --format json` β€” see implementation state
- `specleft next --format json` β€” find next scenario to implement
- `specleft coverage --format json` β€” coverage by feature
- `specleft enforce <policy.yml>` β€” enforce agreed intent in CI

Agents should treat JSON output as the **stable API**.

Expand All @@ -262,7 +241,7 @@ SpecLeft is designed to fail **loudly and explicitly**.

- Validation errors mean intent is unclear.
- Missing priority means intent is incomplete.
- Enforcement failures mean behaviour is not implemented.
- Test failures mean behaviour is not implemented.

Do not auto-fix intent without user approval.

Expand Down
35 changes: 25 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,17 @@ Thank you for your interest in contributing to SpecLeft SDK! This document provi
pytest --version
```

## Developing with coding agents

1. Follow as much of the WORKFLOW.md as possible for development.
2. Features have to be tested manually to ensure they work as intended.

## Running Tests

### Run All Tests

```bash
pytest
make test
```

### Run Tests with Coverage
Expand Down Expand Up @@ -109,6 +114,14 @@ specleft_scenario = []

## Code Style Guidelines

### Linting Shortcut

Use Make commands to run lint
```bash
> make lint
> make lint-fix
```

### Formatting

We use **Black** for code formatting with default settings:
Expand Down Expand Up @@ -141,13 +154,7 @@ We use **MyPy** for static type checking:
mypy src/
```

### Linting Shortcut

Use Make commands to run lint
```bash
> make lint
> make lint-fix
```

### Code Style Summary

Expand Down Expand Up @@ -253,6 +260,11 @@ Examples:

## Testing Guidelines

### Manual Testing
- For new features, we strongly encourage manually testing the functionality to ensure it works as intended.
- We want to pass a human eye on what we build to ensure it meets the needs of users and agents.
- This way we will visually see how the CLI commands work, especially in terms of performance.

### Writing Tests

- Place tests in the `tests/` directory
Expand All @@ -261,7 +273,7 @@ Examples:
- Use descriptive test names that explain what is being tested
- Follow the Arrange-Act-Assert (AAA) pattern

### Test Example
### Behaviour Test Example

```python
def test_specleft_decorator_stores_metadata():
Expand All @@ -279,16 +291,19 @@ def test_specleft_decorator_stores_metadata():

### Test Coverage

- Aim for at least 80% code coverage
- Aim for at least 90% code coverage
- All public APIs should have tests
- Include tests for edge cases and error conditions

### Feature Coverage

- Always verify that spec coverage is 100% with `specleft status`

## Documentation

- Update the README.md for user-facing changes
- Add docstrings to all public functions and classes
- Include examples in docstrings where helpful
- Update PROGRESS.md when completing implementation phases

## Questions?

Expand Down
1 change: 0 additions & 1 deletion GET_STARTED.md
Original file line number Diff line number Diff line change
Expand Up @@ -365,7 +365,6 @@ This creates `.specleft/specs/example-feature.md` with a sample structure β€” us

- Add priorities to scenarios (`priority: critical`, `high`, `medium`, `low`)
- Use `specleft next` to find the next scenario to implement
- Set up CI enforcement with `specleft enforce`
- See [AI_AGENTS.md](AI_AGENTS.md) for AI coding agent workflows

---
Expand Down
20 changes: 14 additions & 6 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -1,9 +1,17 @@
SpecLeft Dual Licensing Notice
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

SpecLeft is dual-licensed.
Copyright (c) 2026 SpecLeft Contributors

Open Source (Apache 2.0):
See LICENSE-OPEN
Licensed under the Apache License, Version 2.0 (the β€œLicense”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Commercial License:
See LICENSE-COMMERCIAL
http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an β€œAS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
22 changes: 0 additions & 22 deletions LICENSE-COMMERCIAL

This file was deleted.

17 changes: 0 additions & 17 deletions LICENSE-OPEN

This file was deleted.

15 changes: 0 additions & 15 deletions NOTICE.md

This file was deleted.

34 changes: 13 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
![SpecLeft social preview](.github/assets/specleft-social-preview.png)

# SpecLeft: Planning-First Workflow for pytest
# SpecLeft: Spec Driven Workflow for Agents

![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)
Expand All @@ -13,7 +13,7 @@ SpecLeft keeps feature intent and test coverage aligned by turning plans into ve
- 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.
SpecLeft currently works with **Python** and **pytest**. It does not replace your test runner or reinterpret existing tests.

Website: [specleft.dev](https://specleft.dev)

Expand Down Expand Up @@ -88,16 +88,23 @@ That flow converts `prd.md` into `.specleft/specs/*.md`, validates the result, p

## 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.
### 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, start here:
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
Expand Down Expand Up @@ -127,12 +134,6 @@ For MCP end-to-end smoke testing and CI workflow details, see [docs/mcp-testing.

<!-- 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)
Expand All @@ -143,13 +144,4 @@ Learn more: [specleft.dev/enforce](https://specleft.dev/enforce)

## 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.
SpecLeft is licensed under [Apache License 2.0](https://github.com/SpecLeft/specleft/blob/main/LICENSE).
22 changes: 6 additions & 16 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# SpecLeft Roadmap

## Current (v0.2.0 - Foundation)
## Current (v0.4.0 - Foundation)
- βœ… Spec-defined test decoration
- βœ… Step-by-step test tracing
- βœ… Skeleton test generation from JSON specs
Expand All @@ -12,24 +12,14 @@
- πŸ“– **Agent Guide** - Provide clarity and guidance for agents to know how to best proceed in scenarios such as: refactoring, cleanup, regression bugs, features and scenarios.
- πŸ”„ **Async test handling** - Async tests are now supported with @specleft decorator and step context manager
- πŸ§ͺ **Test Stubs** - Create empty test containers as an alternate to test skeletons.

## Planned (v0.3.0 - MCP Server)
- πŸ‘Ύ **MCP Server** - A SpecLeft MCP server to smoother integration with AI agents.
- ✍️ **Agent Skills** - Integrated agent skills for more autonomous planning and test generation.


## Future (v0.4.0 and beyond)
- 🌐 **Assisted Discovery** β€” Discover existing functionality from brownfield projects and turn them in to feature definitions.
- πŸ“‘ **Agent-Owner Contract** - An organisation / project specific ruleset, which is machine verifable.
- 🎯 **Test Plan Orchestration** β€” Manage, chain and orchestrate test execution based on dependencies, priorities, and conditional logic. Build dynamic test workflows.
- πŸ€– **AI-Generated Tests** β€” Let SpecLeft generate test implementations from your feature specs using LLMs. Reduce boilerplate even further.
- ✍️ **Agent Skills** - Integrated agent skills for more autonomous planning and test generation.
- πŸ”— **CI/CD Integration** β€” Native integrations with GitHub Actions, GitLab CI, Jenkins, and other CI platforms for seamless reporting and result tracking.
- πŸ”Œ **3rd Party Plugin for Syncing Features** - Sync feature specifications with external platforms like Jira and Azure DevOps to maintain alignment between requirements and automated tests.
- πŸ”” **Notifications** - Get real-time updates on test execution and results via Slack, Microsoft Teams, Discord, and other messaging platforms.
- πŸ“Š **Drift Intelligence** β€” Aggregate and correlate test results across multiple runs, environments, and branches. Track trends, identify flaky tests, and spot patterns drifting behaviour.
- πŸ“ˆ **Enhanced Reporting** β€” Interactive dashboards with drill-down capabilities, failure analysis, and historical trends. Ideal for compliance reporting.
- 🎚️ **SpecLeft CLI Filters** β€” First-class test selection via `--specleft-tag/priority/feature/scenario` flags and pytest config defaults.
## Future (v0.5.0 and beyond)
- 🎚️ **SpecLeft CLI Filters**Β β€” First-class test selection viaΒ `--specleft-tag/priority/feature/scenario`Β flags and pytest config defaults.
- πŸ€–Β **AI-Generated Tests**Β β€” Let SpecLeft generate test implementations from your feature specs using LLMs. SpecLeft provides richer context and understanding for more robust behaviour testing capability. Reduce boilerplate even further.

## Community & Contributions

Have ideas? Found a use case we should support? Open an issue or start a discussionβ€”we'd love to hear from you!
Have ideas? Found a use case we should support? Open an issue or start a discussion β€” it'd be great to hear from you!
Loading
Loading