nspec 2.3.0

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, and advance specs through their lifecycle.

Getting Started

1. Install

pip install nspec[mcp]

Other options: pipx install nspec[mcp], uv add --dev nspec[mcp], poetry add --group dev nspec[mcp].

2. Initialize your project

nspec init

This auto-detects your stack (Python/Node/Rust/Go, package manager, CI platform) and creates:

project-root/
├── .novabuilt.dev/nspec/config.toml   # Configuration
├── .claude/commands/                   # Claude Code skills (go, loop, backlog, etc.)
├── nspec.mk                           # Includable Makefile fragment
└── docs/
    ├── frs/active/TEMPLATE.md         # Feature request template
    ├── impls/active/TEMPLATE.md       # Implementation template
    └── completed/{done,superseded,rejected}/

3. Set up the MCP server

Generate the correct .mcp.json for your stack:

nspec --mcp-config

This outputs a ready-to-paste config block. Add it to your project's .mcp.json:

{
  "mcpServers": {
    "nspec": {
      "command": "nspec-mcp",
      "args": []
    }
  }
}

For managed environments, the command adapts to your stack:

Stack	Command
pip / pipx	nspec-mcp
poetry	poetry run nspec-mcp
uv	uv run nspec-mcp
hatch	hatch run nspec-mcp
Node (npm/yarn/pnpm)	npx nspec-mcp

4. Create your first spec

nspec spec create --title "User authentication" --priority P1

This creates a matched FR + IMPL pair with auto-assigned IDs. From here, Claude Code can pick it up via the MCP tools.

5. Let Claude work

With the MCP server configured, Claude Code has full access to your backlog. Use the installed skills:

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

Or interact naturally — Claude can call next_spec to find work, task_complete to check off tasks, and advance to move specs through their lifecycle.

MCP Server

The MCP server is the primary integration point for AI assistants. Instead of parsing CLI output, the assistant calls structured tools that return typed data.

Transport Options

stdio (default) — Direct pipe, best for local Claude Code:

nspec-mcp

SSE — For web clients, Docker, or remote access:

nspec-mcp --sse        # Listens on http://localhost:8080/sse

HTTP — Streamable HTTP transport:

nspec-mcp --http       # Listens on http://localhost:8080/mcp

Docker

Run the MCP server in Docker with volume-mounted docs:

# Build and start
scripts/mcp-docker.sh start

# With auto-reload on code changes
scripts/mcp-docker.sh watch

# Other commands: stop, restart, logs, status

Configure Claude Code to connect via URL:

{
  "mcpServers": {
    "nspec": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Environment variables: NSPEC_MCP_PORT (default: 8080), NSPEC_MCP_TRANSPORT (sse|http).

Fuzzy ID Resolution

All MCP tools accept flexible ID formats:

• Full prefixed: S022, E007
• Case-insensitive: s022, e7
• Bare numbers: 22, 7, 007 — resolved against known specs on disk

Ambiguous bare numbers (where both S### and E### exist) raise an error asking for the full ID.

Available Tools

Query tools (read-only):

Tool	Description
epics	List all epics with progress percentages
show	Full spec details (FR + IMPL combined)
next_spec	Highest-priority unblocked spec
get_epic	Currently active epic ID
validate	Run 6-layer validation engine
session_start	Initialize work session (pending tasks, blockers, suggested action)
blocked_specs	Specs with blocked tasks or paused status

Mutation tools (modify spec files):

Tool	Description
task_complete	Mark IMPL task done (runs test gate first)
criteria_complete	Mark acceptance criterion done (runs test gate first)
activate	Set spec to Active, persist as current
advance	Move spec to next status (Planning → Active → Testing → Ready)
complete	Archive spec to completed/done
create_spec	Create new FR+IMPL pair with auto-assigned ID
set_priority	Change priority (cascades to dependents)
add_dep / remove_dep	Manage dependencies
task_block / task_unblock	Mark tasks as blocked with reason
park	Pause a spec
codex_review	Run Codex code review against spec criteria

Session tools (cross-session state):

Tool	Description
session_save	Persist session state for handoff
session_resume	Load saved session state
session_clear	Delete session state

Test Gate

task_complete and criteria_complete run make test-quick before marking items done. Pass run_tests=false to skip.

Sequential Task Enforcement

Tasks must be completed in order. Subtasks must be finished before their parent. The MCP server validates this on every task_complete call.

Features

Core Specification Management

• FR/IMPL Pairing — Every feature request gets a matching implementation spec. Orphans are detected automatically.
• Architecture Decision Records — ADRs (FR-900-999 range) with DRAFT/PROPOSED/ACCEPTED/DEPRECATED/SUPERSEDED lifecycle.
• Hierarchical Tasks — Nested task trees with [ ] pending, [x] done, [~] obsolete, and [->XXX] delegated markers.
• Acceptance Criteria — Categorized criteria (Functional, Performance, Quality, Documentation) with progress tracking.
• Spec CRUD — Create, delete, complete, supersede, and reject specs from the CLI with optional --git-add.

6-Layer Validation Engine

1. Format — Markdown structure, required fields, ID format, priority/status/LOE regex.
2. Dataset Loading — Parse all FR and IMPL documents with fail-fast error reporting.
3. Existence — FR/IMPL pairing, orphan detection, mixed-location detection.
4. Dependency — Graph validation, circular reference detection, dangling dependency cleanup.
5. Business Logic — Priority inheritance (child <= parent), status consistency, LOE totals, completion parity.
6. Ordering — Dependency-based document ordering with cross-epic resolution.

Dependency & Epic Management

• Dependency Graph — Add, remove, and visualize dependencies between specs.
• Circular Reference Detection — Prevents invalid dependency cycles.
• Epic Hierarchy — Specs grouped under epics. Epic membership enforced via config.
• Priority Inheritance — Child specs cannot exceed parent epic priority.
• Cross-Epic Ordering — DAO layer resolves ordering across epic boundaries.

Engineering Metrics & Analytics

• Velocity — Commits, LOC, active days, specs completed per period.
• Quality — Test coverage, lint issues, cyclomatic complexity, maintainability index.
• DORA Metrics — Spec velocity tier, quality gate pass rate, change failure rate.
• Activity Heatmap — GitHub-style commit calendar in the TUI.

Interactive Terminal UI

• Spec Table — Multi-column sortable display with epic filtering.
• Detail Panel — Full spec metadata, tasks, and criteria.
• Vim Keybindings — j/k navigation, command modal.
• Real-time Search — Filter with /, navigate matches with n/p.
• Validation Error Screen — Navigate errors with full context.
• Follow Mode — Auto-tracks the currently active spec.
• Live Reload — Watches docs directory and refreshes on changes.

Codex Code Review

• Automated code review via codex_review MCP tool.
• Reviews diff against FR acceptance criteria and IMPL task list.
• Returns APPROVED or NEEDS_WORK verdict written to the IMPL.
• Required before complete() can archive a spec.

Configuration

All nspec configuration lives in .novabuilt.dev/nspec/config.toml:

[paths]
feature_requests = "frs/active"        # FR directory (relative to docs root)
implementation = "impls/active"        # IMPL directory
completed = "completed"                # Archive directory
completed_done = "done"                # Subdirectory for completed specs
completed_superseded = "superseded"    # Subdirectory for superseded specs
completed_rejected = "rejected"        # Subdirectory for rejected specs

[defaults]
epic = "001"                           # Default epic for new specs

[validation]
enforce_epic_grouping = false          # Require all specs in an epic

[review]
model = "gpt-5.2"                      # Codex review model
reasoning_effort = "high"              # low, medium, high
timeout = 600                          # Review timeout in seconds

Priority Order

1. CLI arguments — --docs-root, --epic, etc.
2. Environment variables — NSPEC_FR_DIR, NSPEC_IMPL_DIR, NSPEC_COMPLETED_DIR
3. Config file — .novabuilt.dev/nspec/config.toml
4. Built-in defaults

CLI Reference

Project Setup

Command	Description
nspec init	Scaffold nspec project (auto-detects stack)
nspec init --ci github	Scaffold with GitHub Actions CI
nspec init --force	Overwrite existing files
nspec --mcp-config	Generate MCP server config for your stack

Validation & Output

Command	Description
nspec validate	Run all 6 validation layers
nspec validate criteria --id ID	Validate acceptance criteria for a spec
nspec generate	Generate NSPEC.md and NSPEC_COMPLETED.md
nspec dashboard	Generate + show engineering metrics
nspec stats	Velocity, quality, and DORA metrics
nspec statusline	Compact status for editor integration
nspec tui	Open interactive terminal UI

Spec Management (nspec spec)

Command	Description
nspec spec create --title "T" [--priority P1] [--epic ID]	Create FR+IMPL pair
nspec spec delete --id ID [--force]	Delete FR+IMPL files
nspec spec complete --id ID	Archive to completed/done
nspec spec supersede --id ID	Archive to completed/superseded
nspec spec reject --id ID	Archive to completed/rejected
nspec spec finalize --id ID	Show spec completion status
nspec spec progress [--id ID]	Task and acceptance criteria progress
nspec spec deps --id ID	List direct dependencies
nspec spec context --id ID	LLM-friendly YAML context for an epic

Dependencies (nspec dep)

Command	Description
nspec dep add --to ID --dep DEP	Add dependency
nspec dep remove --to ID --dep DEP	Remove dependency
nspec dep move --to EPIC --dep ID	Move spec to epic

Tasks & Properties (nspec task)

Command	Description
nspec task check --id ID --task-id 1.1	Mark task complete
nspec task criteria --id ID --criteria-id AC-F1	Mark criterion complete
nspec task set-priority --id ID --priority P0	Change spec priority
nspec task set-loe --id ID --loe "3d"	Set level of effort
nspec task next-status --id ID	Advance IMPL to next status
nspec task set-status --id ID --fr-status N --impl-status N	Set status codes directly

Session Management (nspec session)

Command	Description
nspec session start --id ID	Initialize work session
nspec session log --id ID --note "text"	Append execution notes
nspec session handoff --id ID	Generate session handoff summary
nspec session sync --id ID [--force]	Sync spec state across files
nspec session files [--since-commit REF]	List modified files

Architecture Decision Records (nspec adr)

Command	Description
nspec adr create --title "Decision"	Create ADR (FR-900-999 range)
nspec adr list	List all ADRs with status

Document Formats

FR (Feature Request)

# FR-001: Feature Title

**Priority:** P0
**Status:** Proposed
deps: [002, 003]

## Overview
Feature description...

## Acceptance Criteria
- [ ] AC-F1: First criterion
- [x] AC-F2: Second criterion (completed)
- [~] AC-F3: Third criterion (obsolete)

IMPL (Implementation)

# IMPL-001: Feature Title

**Status:** Active
**LOE:** 3d

## Tasks
- [ ] 1. First task
- [x] 2. Second task (completed)
  - [ ] 2.1. Subtask
  - [->S220] 2.2. Delegated to spec S220

Status Codes

FR Status	IMPL Status
Proposed	Planning
In Design	Active
Active	Testing
Completed	Ready
Rejected	Paused
Superseded	Hold
Deferred

Priority Levels

Stories	Epics
P0 Critical	E0 Critical
P1 High	E1 High
P2 Medium	E2 Medium
P3 Low	E3 Low

Makefile Integration

Add the generated fragment to your project Makefile:

include nspec.mk

Provides: nspec.validate, nspec.generate, nspec.dashboard, nspec.tui, nspec.stats, nspec.check.

The NSPEC variable is auto-configured for your stack (e.g., poetry run nspec, npx nspec, uv run nspec).

CI/CD Integration

nspec init generates CI configuration when it detects your platform:

nspec init --ci github      # .github/workflows/nspec.yml
nspec init --ci gitlab       # .gitlab-ci.yml

All CI templates validate specifications and generate NSPEC.md on every push/PR.

Development

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

License

MIT License - see LICENSE for details.

Credits

Built with Poetry, Textual, Rich, and MCP.