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.

Both nspec init and nspec skills sync also auto-install the statusline — they write the statusline script and sync it to your agent directories (e.g. .claude/), so the live spec/epic/progress indicator appears in Claude Code with no extra setup.

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.

The `/nloop` lifecycle¶

/nloop <epic> runs the backlog autonomously: it picks the highest-priority unblocked spec, executes it end-to-end via /ngo (author → implement → verify → external review → archive), then loops to the next spec. It keeps going until the epic drains — it never stops to ask "should I continue?".

When the epic has no more workable specs, /nloop runs the epic-finalize gate at exit (default batch-branch mode): it pushes the branch, opens or updates a single PR for the epic, watches CI and fixes failures until the checks are green, then asks you to merge. The loop makes the PR mergeable but never merges it itself — the final merge is always a human decision.

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.