Getting Started¶

Install¶

pippipxuvpoetry

pip install nspec

pipx install nspec

uv add --dev nspec

poetry add --group dev nspec

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
│   ├── commands/                      # Installed skills (slash commands)
│   ├── resources/                     # FR/IMPL templates
│   └── templates/                     # Template profiles (quick/standard/full/formal)
├── .claude/commands/                  # Symlinks to nspec skills
├── CLAUDE.md                          # AI assistant instructions
├── DEV-PROCESS.md                     # Development process guide
├── nspec.mk                          # Includable Makefile fragment
└── docs/
    ├── frs/active/                    # Feature requests
    ├── impls/active/                  # Implementation specs
    └── completed/{done,superseded,rejected}/

Verify the setup:

nspec doctor

This checks config, directories, validation, and MCP server health.

Set Up the MCP Server¶

Generate the correct .mcp.json for your stack:

nspec mcp-config

Add the output to your project's .mcp.json:

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

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`

Install Skills¶

nspec ships with slash commands for Claude Code. After nspec init, sync them to your project:

nspec skills sync

This creates symlinks in .claude/commands/ pointing to the installed skills. Available skills include /ngo (spec executor), /nloop (autonomous loop), /nbacklog (dashboard), and more. See the Skills Reference for the full list.

Create Your First Spec¶

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

This creates a matched FR + IMPL pair with auto-assigned IDs.

Let Claude Work¶

With the MCP server configured, Claude Code has full access to your backlog:

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

Validate Your Specs¶

nspec validate

Runs the 6-layer validation engine: format, dataset loading, existence (FR/IMPL pairing), dependencies, business logic, and ordering.

Launch the TUI¶

nspec tui

Browse your backlog interactively with vim-style keybindings, search, and real-time updates.