Metadata-Version: 2.4
Name: nspec
Version: 3.2.2
Summary: Feature request and implementation specification management tool
License: MIT
License-File: LICENSE
Keywords: requirements,specifications,project-management,validation,cli
Author: Novabuiltdevv
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Provides-Extra: completion
Provides-Extra: terminusdb
Provides-Extra: yaml
Requires-Dist: argcomplete (>=3.0,<4.0) ; extra == "completion"
Requires-Dist: mcp (>=1.0,<2.0)
Requires-Dist: pyyaml (>=6.0,<7.0) ; extra == "yaml"
Requires-Dist: terminusdb-client (>=10.2,<11.0) ; extra == "terminusdb"
Requires-Dist: textual (>=7.4,<8.0)
Project-URL: Documentation, https://novabuiltdevv.github.io/nspec/
Project-URL: Homepage, https://novabuiltdevv.github.io/nspec/
Project-URL: Repository, https://github.com/Novabuiltdevv/nspec
Description-Content-Type: text/markdown

# nspec

[![PyPI version](https://img.shields.io/pypi/v/nspec.svg)](https://pypi.org/project/nspec/)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/nspec.svg)](https://pypi.org/project/nspec/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://novabuiltdevv.github.io/nspec/)

> Specification-driven project management for AI-native development

**nspec** turns your backlog into structured markdown specs that AI coding assistants can read, execute, and update. It pairs every feature request (FR) with an implementation spec (IMPL), validates the entire graph, and exposes an MCP server so Claude Code (or any MCP-compatible agent) can autonomously pick up work, track tasks, and advance specs through their lifecycle.

## Install

```bash
pip install nspec
```

Also available via `pipx`, `uv`, and `poetry`. See the [Getting Started guide](https://novabuiltdevv.github.io/nspec/getting-started/).

## Quick Start

```bash
nspec init              # Scaffold project (auto-detects your stack)
nspec --mcp-config      # Generate MCP server config
nspec spec create --title "My feature" --priority P1
nspec validate          # Run 6-layer validation
nspec tui               # Interactive terminal UI
```

With the MCP server configured, Claude Code can autonomously work your backlog:

```
/ngo S001       — Start a work session on a spec
/nbacklog       — View the prioritized backlog
/nloop          — Autonomous mode: pick, execute, complete, repeat
```

## Features

- **FR/IMPL Pairing** — Every feature request gets a matching implementation spec with hierarchical tasks and acceptance criteria
- **6-Layer Validation** — Format, pairing, dependencies, business logic, and ordering checks
- **MCP Server** — stdio, SSE, and HTTP transports for AI assistant integration
- **Interactive TUI** — Sortable table, detail panel, vim keybindings, search, follow mode, live reload
- **Dependency Graph** — Circular reference detection, cross-epic ordering, priority inheritance
- **Multi-Agent Queue** — Parallel spec execution with atomic claim/release and lease-based recovery
- **Engineering Metrics** — Velocity, quality, DORA metrics, and activity heatmap
- **Code Review** — Automated review against spec criteria via configurable external agents

## Documentation

Full documentation: **[novabuiltdevv.github.io/nspec](https://novabuiltdevv.github.io/nspec/)**

- [Getting Started](https://novabuiltdevv.github.io/nspec/getting-started/) — Install, init, MCP setup
- [CLI Reference](https://novabuiltdevv.github.io/nspec/user-guide/cli/) — Full command docs
- [MCP Tools](https://novabuiltdevv.github.io/nspec/mcp/tools/) — Tool reference tables
- [Configuration](https://novabuiltdevv.github.io/nspec/user-guide/configuration/) — Config file, env vars
- [Contributing](https://novabuiltdevv.github.io/nspec/contributing/) — Dev setup, testing

## Development

```bash
poetry install
make test-quick    # Fast tests, fail-fast
make check         # Format + lint + typecheck
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Credits

Built with [Poetry](https://python-poetry.org/), [Textual](https://textual.textualize.io/), [Rich](https://rich.readthedocs.io/), and [MCP](https://modelcontextprotocol.io/).

