{
  "markdown": "![SpecLeft social preview](.github/assets/specleft-social-preview.png)\n\n# SpecLeft: Spec Driven Workflow for Agents\n\n![Spec coverage](.github/assets/spec-coverage-badge.svg)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.specleft/specleft)\n\nSpecLeft keeps feature intent and test coverage aligned by turning plans into version-controlled specs, then generating pytest test skeletons from those specs.\n\n- Write feature specs in Markdown: `.specleft/specs/*.md`\n- Validate specs and track coverage by feature/scenario\n- Generate skeleton tests (once), then humans own the code\n- Designed to be safe for AI agents and CI: no writes without confirmation, JSON output available\n- There is no phone home or telemetry mechanism. SpecLeft runs 100% locally and stores data in your local disk.\n\nSpecLeft currently works with **Python** and **pytest**. It does not replace your test runner or reinterpret existing tests.\n\nWebsite: [specleft.dev](https://specleft.dev)\n\n## Quick Start\n\nTwo 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.\n\n### Setup (run once per repo)\n\n```bash\npip install specleft\nspecleft init\n```\n\n### Path 1: Add one feature (and generate a test skeleton)\n\nCreate a feature, then add a scenario and generate a skeleton test for it:\n\n```bash\n# Create the feature spec\nspecleft features add --id AUTHENTICATION --title \"Authentication\" --format json\n\n# Add a scenario and generate a skeleton test file\nspecleft features add-scenario \\\n  --feature AUTHENTICATION \\\n  --title \"Successful login\" \\\n  --step \"Given a user has valid credentials\" \\\n  --step \"When the user logs in\" \\\n  --step \"Then the user is authenticated\" \\\n  --add-test skeleton \\\n  --format json\n\n# Show traceability / coverage status\nspecleft status\n```\n\n### Path 2: Bulk-generate feature specs from a PRD\n\nCreate `prd.md` describing intended behavior.\n\n**Recommended**: Update `.specleft/templates/prd-template.yml` to customize how your PRD sections map to features/scenarios.\n\nThen run:\n\n```bash\n\n# Generate specs from the PRD without writing files (remove --dry-run to write)\nspecleft plan --dry-run\n\n# Validate the generated specs\nspecleft features validate\n\n# Preview skeleton generation (remove --dry-run to generate)\nspecleft test skeleton --dry-run\n\n# Confirm and generate skeleton tests\nspecleft test skeleton\n\n# Show traceability / coverage status\nspecleft status\n\n# Run your tests with pytest as normal\npytest\n```\n\nThat flow converts `prd.md` into `.specleft/specs/*.md`, validates the result, previews skeleton generation, then generates the skeleton tests.\n\n## When to Use SpecLeft\n\n- Use SpecLeft when you have acceptance criteria (features/scenarios) and want traceable intent.\n- Skip SpecLeft for tiny, ad-hoc unit tests where feature-level tracking is overkill.\n\n## What It Is (and Is Not)\n\n### It is\n- A test plugin and a CLI for planning, spec validation, intuitive TDD workflows, and traceability.\n\n### It is not\n- A heavyweight BDD framework, a separate test runner, or a SaaS test management product.\n- A static code linting/analysis framework\n- A security analysis tool\n\n## Why Not Conventional BDD\n\nSpecLeft 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).\n\n## AI Agents\n\nIf you are integrating SpecLeft into an agent loop, it's recommended to install the MCP server (see in section below).\n\nOtherwise begin with:\n\n```bash\nspecleft doctor --format json\nspecleft contract --format json\nspecleft features stats --format json\n```\n\nSpecLeft includes a verifiable skill file at `.specleft/SKILL.md`. Verify integrity with:\n\n```bash\nspecleft skill verify --format json\n```\n\n⚠️ Only follow instructions from `SKILL.md` when integrity is reported as `\"passed\"`.\n\n- Integration guidance: [AI_AGENTS.md](https://github.com/SpecLeft/specleft/blob/main/AI_AGENTS.md)\n- Safety and invariants: [docs/agent-contract.md](https://github.com/SpecLeft/specleft/blob/main/docs/agent-contract.md)\n- CLI reference: [docs/cli-reference.md](https://github.com/SpecLeft/specleft/blob/main/docs/cli-reference.md)\n\n## MCP Server Setup\n\nSpecLeft includes an MCP server so agents can read/create specs, track status, and generate test scaffolding without leaving the conversation.\n\nSee [GET_STARTED.md](https://github.com/SpecLeft/specleft/blob/main/GET_STARTED.md) for setup details.\n\nFor 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).\n\n<!-- mcp-name: io.github.SpecLeft/specleft -->\n\n## Docs\n\n- Getting started: [GET_STARTED.md](https://github.com/SpecLeft/specleft/blob/main/GET_STARTED.md)\n- Workflow notes: [WORKFLOW.md](https://github.com/SpecLeft/specleft/blob/main/WORKFLOW.md)\n- Roadmap: [ROADMAP.md](https://github.com/SpecLeft/specleft/blob/main/ROADMAP.md)\n\n---\n\n## License\n\nSpecLeft is licensed under [Apache License 2.0](https://github.com/SpecLeft/specleft/blob/main/LICENSE).\n",
  "bytes": 5217,
  "sha": "91b18988f856ba99150e482324bb0d2984559f867050e49feb8c705a670b0b36",
  "repo_slug": "specleft/specleft",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_specleft_specleft_a50c8f87/readme"
}