Skip to content

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.

Why nspec?

  • Structured specs — Feature requests and implementation plans in validated markdown, not sticky notes
  • MCP-native — 82 MCP tools let AI assistants read and update your backlog directly via the Model Context Protocol
  • 6-layer validation — Format, pairing, dependencies, business logic, and ordering checks catch problems before they ship
  • Interactive TUI — Browse, search, and navigate your backlog in the terminal with vim keybindings
  • Autonomous workflows — Claude Code can pick specs, complete tasks, run reviews, and advance the lifecycle end-to-end
  • Multi-agent swarm — Parallel spec execution with git worktree isolation and automatic lease recovery
  • GitHub issue integration — Import issues as specs, sync status back to GitHub on completion
  • Skills system — 29 slash commands for Claude Code covering spec creation, review, triage, and autonomous loops
  • Checkout & reservation — TTL-based spec leases prevent double-assignment across agents
  • Template profiles — Quick, standard, full, and formal ceremony levels for spec creation
  • Code review — Automated review against spec criteria via configurable external agents (Codex, Claude, Gemini)
  • Engineering metrics — Velocity, quality, DORA metrics, and activity heatmap

Quick Install

pip install nspec

nspec init          # Scaffold project
nspec mcp-config    # Generate MCP server config

How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Feature     │     │  Impl        │     │  Validation  │
│  Request     │────▶│  Spec        │────▶│  Engine      │
│  (FR-001)    │     │  (IMPL-001)  │     │  (6 layers)  │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       └────────────────────┴────────────────────┘
                            │
                    ┌───────▼───────┐
                    │  MCP Server   │
                    │  (84 tools)   │
                    └───────┬───────┘
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
  ┌───────▼───────┐ ┌──────▼──────┐ ┌────────▼────────┐
  │  AI Assistant │ │  Agent      │ │  GitHub Issues  │
  │  (Claude,     │ │  Swarm      │ │  Integration    │
  │   Codex, etc) │ │  (parallel) │ │  (import/sync)  │
  └───────┬───────┘ └─────────────┘ └─────────────────┘
          │
  ┌───────▼───────┐
  │  Skills       │
  │  (29 commands)│
  └───────────────┘

Next Steps