nspec 1.1.1
Feature request and implementation specification management tool
License: MIT
Requires Python: <4.0,>=3.11
Keywords: requirements, specifications, project-management, validation, cli

# 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

```bash
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

```bash
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:

```bash
nspec --mcp-config
```

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

```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

```bash
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:

- `/go S001` — Start a work session on a spec
- `/backlog` — View the prioritized backlog
- `/loop` — 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:
```bash
nspec-mcp
```

**SSE** — For web clients, Docker, or remote access:
```bash
nspec-mcp --sse        # Listens on http://localhost:8080/sse
```

**HTTP** — Streamable HTTP transport:
```bash
nspec-mcp --http       # Listens on http://localhost:8080/mcp
```

### Docker

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

```bash
# 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:

```json
{
  "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`:

```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)
```markdown
# 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)
```markdown
# 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:

```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:

```bash
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

```bash
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](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/).