nspec 3.15.3

Feature request and implementation specification management tool

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

pip install nspec

Also available via pipx, uv, and poetry. See the Getting Started guide.

Quick Start

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

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

Documentation

Full documentation: novabuilt.dev/nspec

• Getting Started — Install, init, MCP setup
• CLI Reference — Full command docs
• Terminal UI — Interactive backlog browser & dependency visualization
• MCP Tools — Tool reference tables
• Skills Reference — Slash commands for Claude Code
• Configuration — Config file, env vars
• Contributing — Dev setup, testing

Development

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

License

MIT License - see LICENSE for details.

Credits

Built with Poetry, Textual, Rich, and MCP.