Skip to content

Development Setup

Prerequisites

Install

git clone https://github.com/Novabuiltdevv/nspec.git
cd nspec
poetry install --with dev

Make Targets

Code Quality

make format          # Auto-format with ruff
make lint            # Lint with ruff
make typecheck       # Type check with pyright
make deadcode        # Dead code detection with vulture

Testing

make test-quick      # Fast tests, fail-fast
make test-cov        # Tests + coverage HTML report
make test            # Full suite
make test-e2e        # E2E lifecycle tests
make test-mutation   # Mutation testing (parallel)

Quality Analysis

make qa              # Run all static analysis → work/quality/data.json
make qa-snapshot     # Save current baseline before changes
make qa-diff         # Show quality delta (regressions fail)

Quality Gate

make check           # format-check + lint + typecheck
make all             # check + test + validate

Running the TUI

make tui             # Build, install, and launch TUI

Project Structure

src/nspec/
  cli.py                  CLI entry point
  cli_commands.py          Click command definitions
  cli_handlers/            Handler modules (crud, integrations, reporting, workflow)
  config.py                Config loading
  mcp_server.py            MCP server bootstrap
  git_ops.py               Git operations
  watchdog.py              Claude Code stall detector
  velocity.py              Engineering metrics

  domain/                  Core domain types
    datasets.py            FR/IMPL data loading
    tasks.py               Task parsing/tracking
    statuses.py            Status codes and transitions
    ids.py                 ID parsing and resolution
    lifecycle_hints.py     next_steps hint generation
    loe.py                 Level of effort estimation
    ordering.py            Spec ordering logic

  dao/                     Data access layer
    protocols.py           DAO protocol definitions
    factory.py             DAO factory
    registry.py            DAO registry

  interfaces/mcp/          MCP tool implementations
    _query.py              Query & discovery tools
    _mutation.py           Mutation tools (activate, advance, etc.)
    _checkout.py           Checkout & reservation tools
    _audit.py              Audit & observability tools

  analysis/                Analysis tools
    context_audit.py       CLAUDE.md context budget analysis
    coverage_audit.py      Coverage audit
    dep_graph.py           Dependency graph analysis

  integrations/            External integrations
    github.py              GitHub issue sync
    linear.py              Linear integration

  validation/              Validation engine
    validator.py           6-layer validation orchestrator
    checkers.py            Individual validation checkers

  workflow/                Workflow orchestration
    review.py              Review dispatch
    review_workflow.py     Review lifecycle
    refine.py              FR/IMPL refinement
    branches.py            Branch management

  tui/                     Terminal UI
    app.py                 Main TUI application
    accordion.py           Next-gen accordion view (ngtui)
    detail_screen.py       Detail view
    report_screen.py       Engineering metrics dashboard
    table.py               Spec table widget
    filters.py             Filter state management
    command_modal.py       Command modal (:)
    nspec.tcss             Central stylesheet

  skills/
    claude/                Claude Code slash commands (29)
    codex/                 Codex prompt templates (4)

tests/
  test_*.py                Unit tests (pytest)
  conftest.py              Shared fixtures

Commit Format

feat(tui): Add search highlighting
fix(validator): Handle empty FR files
test(tui): Add Playwright terminal tests for detail view
chore: Update dependencies

Key Rules

  1. Test gate — Never commit with failing make test-quick
  2. Theme-only styling — No hardcoded colors in Python; all colors in tui/nspec.tcss
  3. Fail fast — No silent failures, no fallback values masking errors
  4. Wire it up — Code must be called; dead code is worse than no code
  5. No tech debt — No backwards-compatibility shims; change interfaces directly

Coverage

Target: 80%. Run make test-cov to see current coverage.