Metadata-Version: 2.4
Name: nspec
Version: 3.19.0
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: falkordb
Provides-Extra: terminusdb
Provides-Extra: yaml
Requires-Dist: argcomplete (>=3.0,<4.0) ; extra == "completion"
Requires-Dist: cryptography (>=48.0.1)
Requires-Dist: falkordb (>=1.0,<2.0) ; extra == "falkordb"
Requires-Dist: idna (>=3.15)
Requires-Dist: jinja2 (>=3.1,<4.0)
Requires-Dist: jsonschema (>=4.20,<5.0)
Requires-Dist: mcp (>=1.0,<2.0)
Requires-Dist: pyjwt (>=2.13.0)
Requires-Dist: pymdown-extensions (>=11.0.0)
Requires-Dist: python-multipart (>=0.0.31)
Requires-Dist: pyyaml (>=6.0,<7.0) ; extra == "yaml"
Requires-Dist: starlette (>=1.3.1)
Requires-Dist: terminusdb-client (>=10.2,<11.0) ; extra == "terminusdb"
Requires-Dist: textual (>=7.4,<8.0)
Requires-Dist: urllib3 (>=2.7.0)
Project-URL: Documentation, https://novabuilt.dev/nspec/
Project-URL: Homepage, https://novabuilt.dev/blog/getting-started-with-nspec/
Project-URL: Repository, https://github.com/Novabuiltdevv/nspec-issues
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://novabuilt.dev/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, run reviews, and advance specs through their lifecycle.

## Install

```bash
pip install nspec
```

Also available via `pipx`, `uv`, and `poetry`. See the [Getting Started guide](https://novabuilt.dev/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, review, complete, repeat
```

At loop entry, `/nloop` seeds itself once with epic-wide **FR intent** via a
loop-entry `seed_context` step (the `epic_fr_context` tool): it reads every member
spec's Goal/Scope/Acceptance Criteria — regardless of state, so even un-started specs
contribute — and grounds the whole run in what the epic *intends*, the FR-side complement
to `epic_context`'s per-spec *delivered* outcomes.

## 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** — 89 tools over stdio, SSE, and HTTP transports for AI assistant integration
- **Interactive TUI** — Sortable table, detail panel, vim keybindings, search, follow mode, live reload, and in-terminal dependency-graph visualization (expand upstream/downstream, jump between linked specs)
- **Dependency Graph** — Circular reference detection, cross-epic ordering, priority inheritance
- **Skills System** — 29 slash commands for Claude Code (spec creation, review, triage, autonomous loops) plus Codex prompt templates
- **Multi-Agent Queue** — Parallel spec execution with git-worktree isolation, atomic claim/release, and lease-based recovery
- **Checkout & Reservation** — TTL-based spec leases prevent double-assignment across agents
- **GitHub Issue Integration** — Import issues as specs and sync status back to GitHub on completion
- **Code Review** — Automated review against spec criteria via configurable external agents (Codex, Gemini)
- **Engineering Metrics** — Velocity, quality, DORA metrics, and activity heatmap

### Priority Model

- **Epic priorities are global and unique.** Epics rank against each other in one
  contiguous order (P1, P2, P3, …). Changing an epic's priority cascade-inserts it —
  the others shift up or down to keep every slot unique.
- **Spec priorities (P0–P3) are scoped to their epic.** A spec's priority only orders it
  against its siblings *within the same epic* — it is contained there and has no meaning
  across epics. Two specs may share a priority; ties break deterministically by spec ID.
  IDs are `S`/`E` + a zero-padded number (`S001`); the 3-digit space is a floor, not a cap —
  once it fills, IDs widen to four digits (`S1000`–`S9999`) automatically, and the allocator
  fails loud rather than ever reusing an ID.
  Changing a spec's priority bumps its epic siblings to make room (best-effort: because
  the P0–P3 range is smaller than the number of specs an epic can hold, siblings pile up
  at the floor priority once the range is exhausted rather than overflowing past it).
- **Dependency order is the default sort, and it ignores P-numbers.** The TUI's default
  `sort:dependency` orders specs by a topological sort of their `deps`, not by priority.
  A spec with no dependency edges to its siblings is an *orphan* and falls to the end of
  its epic, ordered only by its (often default) priority. To make the dependency graph
  authoritative, enable the optional gate `[validation] enforce_epic_dependency_chain =
  true`: validation then fails unless every epic's active specs form one connected
  dependency chain (branches are fine; disconnected islands and orphans are not). Wire
  specs together with `add_dep` to satisfy it.

### Epic FR contract

Every epic carries a PRD-style contract so a reader can tell what it is for and when it is
done without reverse-engineering it from child specs. `create_spec(is_epic=True)` scaffolds
the FR from a dedicated **epic template** (`src/nspec/resources/templates/epic/fr.md`) with
these sections: **Goal**, **Why It Matters**, **Scope** (In / Out), **Definition of
Complete**, **Child Specs**, and **Acceptance Criteria**. Definition-of-Complete items are
plain bullets describing the epic's end-state; only Acceptance Criteria are tracked
checkboxes, so per-epic progress accounting is unchanged. A project can override the
template by dropping its own copy at `.novabuilt.dev/nspec/templates/epic/fr.md`, which
wins over the builtin.

### Epic-level review

`/nreview-epic <epic>` batch-reviews every child spec of an epic. It **reuses the
single-spec review machinery** rather than re-implementing it: for each child it runs the
same chain `/ngo` and `/nreview` use — `review_spec` (mints the review prompt file) →
`execute_agent` (dispatches to the external review agent, Codex/Gemini) →
`write_review_verdict` (persists the verdict + a Review History row into the child's IMPL).
So an epic review leaves the same durable per-spec audit trail a single-spec review does —
not an ephemeral console table. It **does not advance any spec's lifecycle status** (it
records verdicts only) and has **no self-review path** — the external agent always reviews,
never the implementing agent. `--converge` wraps the per-spec chain in an iteration loop
that surfaces cross-cutting themes (issues spanning 2+ specs) and drives atomic multi-file
fixes until the epic's specs stop churning.

### Running without reviews

Projects with no reviewable build artifact — an infrastructure repo whose
changes are converged state rather than a diff — can turn reviews off honestly:

```toml
[review]
enabled = false
waive_reason = "infrastructure repo — no reviewable build artifact yet"
```

Completions then record a signed `WAIVED — <reason>` verdict instead of an
approval, so the audit trail says plainly that review was waived and why.
`waive_reason` is required: disabling reviews without one fails at config load.
A waiver excuses the *review*, not the work — acceptance criteria and tasks must
still be complete — and no agent can produce a `WAIVED` verdict, so it can't be
used to rubber-stamp. Delete the two lines to re-enable.

### Reviewer model & effort

Review runs on the **top available model at moderate reasoning effort** —
`[review.codex]` defaults to `gpt-5.6-sol` at `effort = "medium"`,
`[review.claude]` to `opus` at `high`. The two knobs are not interchangeable:
model tier bounds whether a finding is judged correctly, while `effort` buys
depth of exploration within that ceiling. So `effort` is the dial to turn when
review cost or latency matters — lower it rather than downgrading `model`.
Cheap models remain the default for the non-judgement paths (`[handoff]`,
`[docs]`), where summarization is extraction rather than judgement.

Model ids retire without a CLI version bump and fail at *call* time, not
config-load time, so a stale value looks like a reviewer hang rather than a
config error — probe a new id before setting it. Rationale, role-by-role
policy, and the verified legality matrix:
[`docs/design/agent-model-selection.md`](docs/design/agent-model-selection.md).

### Where review artifacts land

Everything nspec generates while working a spec lives under **one root**,
`work/specs/<spec-id>/`, indexed by that spec's `manifest.json`:

```
work/specs/S314/
  manifest.json   prompts/   review/   output/   logs/
```

`review/` holds the curated verdict and its JSON sidecar; `output/` holds the raw
agent transcript; `prompts/` the review prompt; `logs/` the per-agent execution
logs. One directory therefore archives, hands off, or cleans up a spec's whole
evidence trail. Spec-less agent output goes to `work/logs/`.

> **Upgrading:** curated review artifacts used to be written to a second
> top-level root, `work/agent-output/<id>/`, which duplicated each round and left
> the curated copy out of the manifest. Nothing reads or writes that path now.
> Existing `work/agent-output/` trees are left inert — gitignored scratch, never
> migrated, safe to delete by hand. There is no compatibility shim.

## Documentation

Full documentation: **[novabuilt.dev/nspec](https://novabuilt.dev/nspec/)**

- [Getting Started](https://novabuilt.dev/nspec/getting-started/) — Install, init, MCP setup
- [CLI Reference](https://novabuilt.dev/nspec/user-guide/cli/) — Full command docs
- [Terminal UI](https://novabuilt.dev/nspec/user-guide/tui/) — Interactive backlog browser & dependency visualization
- [MCP Tools](https://novabuilt.dev/nspec/mcp/tools/) — Tool reference tables
- [Skills Reference](https://novabuilt.dev/nspec/user-guide/skills/) — Slash commands for Claude Code
- [Configuration](https://novabuilt.dev/nspec/user-guide/configuration/) — Config file, env vars
- [Contributing](https://novabuilt.dev/nspec/contributing/) — Dev setup, testing

## Development

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

**Type-aware verify:** `/ngo`'s verify step runs the command appropriate to what a
spec changes — `make test-quick` for code, `mkdocs build --strict` for docs — instead
of always running the full test suite. A spec selects its profile with a
`verify_profile: docs` annotation in its FR (unannotated specs are `code`); projects
add or override profiles under `[verify.profiles]` in `config.toml`, or per-run via an
`NSPEC_VERIFY_<PROFILE>` env var (env > config > built-in default). Resolution fails
closed: an unknown profile falls back to the code command, so verification is never
silently skipped.

## 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/).

