Configuration¶
All nspec configuration lives in .novabuilt.dev/nspec/config.toml.
Full Reference¶
[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
[session]
sessions_dir = "sessions" # Session state directory
[skills]
sources = ["builtin"] # Skill sources
targets = { claude = ".claude/commands" } # Where to symlink skills
[validation]
enforce_epic_grouping = false # Require all specs in an epic
strict_completion_parity = true # FR/IMPL completion must match
[strict]
require_default_epic = true # Enforce default epic exists
validation_on_mutate = true # Reject mutations that fail validation
[project]
code_root = "." # Working directory for git diff (multi-repo)
# --- GitHub Integration ---
[github]
repo = "" # "owner/repo" for issue import
default_priority = "P2" # Default priority for imported issues
[github.label_priority_map]
"priority:p0" = "P0"
"critical" = "P0"
"priority:p1" = "P1"
"urgent" = "P1"
"priority:p3" = "P3"
"low" = "P3"
# --- Templates ---
[templates]
default = "standard" # quick, standard, full, formal
[id_ranges]
spec_min = 1 # Lowest spec ID
spec_max = 899 # Highest spec ID
epic_min = 1 # Lowest epic ID
epic_max = 99 # Highest epic ID
adr_min = 901 # ADR range start
adr_max = 999 # ADR range end
[backend]
engine = "markdown" # "markdown" or "terminusdb"
# --- Refinement (FR/IMPL authoring) ---
[refinement]
agent = "codex" # Which agent refines skeletons
timeout = 300
[refinement.codex]
model = "gpt-5.3-codex"
effort = "medium"
[refinement.claude]
model = "opus"
effort = "high"
# --- Review ---
[review]
agent = "codex" # Review backend: "codex", "claude", or "gemini"
timeout = 300 # Review timeout in seconds
token_ttl_hours = 24 # Review token validity
diff_exclude = [".novabuilt.dev/", ".claude/", "poetry.lock", "work/"]
diff_include = [] # Empty = all paths (no inclusion filter)
[review.codex]
model = "gpt-5.3-codex" # Codex review model
effort = "medium" # Reasoning effort: low, medium, high
[review.claude]
model = "opus" # Claude review model
effort = "high"
[review.gemini]
model = "gemini-3-pro-preview" # Gemini review model
# --- Agent Executors ---
[codex]
model = "gpt-5.3-codex" # Codex CLI model
reasoning_effort = "medium"
sandbox = "workspace-write" # Sandbox mode
approval_policy = "on-request"
flags = ["--full-auto"] # Extra CLI flags
timeout = 300 # Execution timeout (seconds)
poll_interval = 2.0 # Poll interval (seconds)
session_prefix = "nspec-codex" # tmux session prefix
[gemini]
model = "gemini-3-pro-preview" # Gemini CLI model
approval_mode = "plan"
sandbox = false
flags = []
timeout = 300
poll_interval = 2.0
session_prefix = "nspec-gemini"
[agents]
# Map logical agent names to implementations
# "self" = current session, "subprocess:codex" = codex CLI, "mcp:<server>" = MCP
# Default: { executor = "self", reviewer = "subprocess:codex" }
# --- Loop Orchestrator ---
[loop]
session_timeout = "30m" # timeout(1) format: 30m, 1h
max_retries = 3 # Spec-level retries before Exception
# pipeline = [...] # Custom pipeline steps (advanced)
# --- Timeouts ---
[timeouts]
lock_acquire_s = 10.0 # File lock acquire timeout
lock_stale_s = 3600 # Stale lock threshold (seconds)
git_s = 30 # Git command timeout
subprocess_s = 10 # Subprocess timeout
mcp_s = 120 # MCP tool call timeout
# --- Multi-Agent Queue ---
[queue]
mode = "single" # "single" or "multi"
max_agents = 5 # Max concurrent agents
lease_ttl_seconds = 300 # Lease timeout before auto-release
# --- Watchdog (Claude Code stall detector) ---
[watchdog]
stall_timeout = 180 # Seconds before declaring token stall
mcp_stall_timeout = 120 # Seconds before declaring MCP tool hang
poll_interval = 15 # Seconds between polls
recovery_message = "Please continue from where you left off."
# --- TUI ---
[tui]
col_id = 5 # Column widths for spec table
col_priority = 3
col_status = 3
col_upstream = 6
col_downstream = 6
col_estimate = 5
min_title_width = 25
# --- LOE Estimator ---
[loe]
weight_task_count = 1.0 # Algorithm weights for LOE estimation
weight_max_depth = 2.0
weight_nested_ratio = 1.5
weight_dep_count = 1.5
weight_complexity_signal = 3.0
min_history_specs = 10 # Min completed specs for calibration
# --- Claude Code Swarm ---
[claude_code]
model = "sonnet" # Model for swarm agents
permission_mode = "bypassPermissions" # Agent permission mode
timeout = 1800 # Agent timeout (seconds)
worktree_base = ".worktrees" # Git worktree directory
# --- Error Agent (auto-spec from failures) ---
[error_agent]
enabled = false # Auto-create specs from errors
auto_create_spec = true
auto_park_on_blocking = true
epic_id = "" # Target epic for error specs
max_per_session = 5
# --- Guard (hook enforcement) ---
[guard]
credential_patterns = [".env", "*.pem", "*.key", "credentials.json"]
destructive_patterns = ["rm -rf", "git push --force", "git reset --hard"]
audit_log = ".novabuilt.dev/nspec/audit/blocked-ops.log"
# --- Emojis (override defaults) ---
# [emojis]
# fr_proposed = "🟡"
# impl_paused = "⏳"
# priority_p0 = "🔥"
Priority Order¶
Configuration values are resolved in this order (highest priority first):
- CLI arguments —
--docs-root,--epic, etc. - Environment variables —
NSPEC_FR_DIR,NSPEC_IMPL_DIR,NSPEC_COMPLETED_DIR - Config file —
.novabuilt.dev/nspec/config.toml - Built-in defaults
Environment Variables¶
| Variable | Description |
|---|---|
NSPEC_FR_DIR |
Feature request directory |
NSPEC_IMPL_DIR |
Implementation spec directory |
NSPEC_COMPLETED_DIR |
Completed specs archive |
NSPEC_MCP_PORT |
MCP server port (default: 8080) |
NSPEC_MCP_TRANSPORT |
MCP transport: sse or http |
NSPEC_ALLOW_CREDENTIAL_READ |
Bypass credential guard hook |
NSPEC_CONFIRM_DESTRUCTIVE |
Bypass destructive command guard hook |
Review Configuration¶
The [review] section controls which external agent performs code reviews before a spec can be completed.
[review]
agent = "gemini" # Which agent reviews code
timeout = 300 # Max seconds for a review
[review.gemini]
model = "gemini-3-pro-preview"
The review agent is dispatched via execute_agent(). The agent name must match [review].agent — passing a different name to write_review_verdict is rejected.
Available review backends:
| Agent | Config Section | Default Model |
|---|---|---|
codex |
[review.codex] |
gpt-5.3-codex |
claude |
[review.claude] |
opus |
gemini |
[review.gemini] |
gemini-3-pro-preview |
Backend Configuration¶
nspec supports pluggable persistence backends:
[backend]
engine = "markdown" # Default: plain markdown files
# engine = "terminusdb" # Graph database backend
Project Structure¶
After nspec init, your project will have:
project-root/
├── .novabuilt.dev/
│ └── nspec/
│ ├── config.toml # Configuration
│ ├── commands/ # Installed skills
│ └── sessions/ # Session state (gitignored)
├── .claude/
│ └── commands/ # Symlinks to nspec commands
├── docs/
│ ├── frs/active/ # Feature requests
│ ├── impls/active/ # Implementation specs
│ └── completed/
│ ├── done/
│ ├── superseded/
│ └── rejected/
└── nspec.mk # Makefile fragment