Specs & Documents¶

nspec manages two paired document types: Feature Requests (FR) and Implementation Specs (IMPL). Every FR must have a matching IMPL, and vice versa. Orphans are detected automatically by the validation engine.

Feature Request (FR)¶

# FR-001: Feature Title

**Priority:** P0
**Status:** Proposed
deps: [002, 003]

epic_id: E001

## Overview
Feature description...

## Acceptance Criteria
- [ ] AC-F1: First criterion
- [x] AC-F2: Second criterion (completed)
- [~] AC-F3: Third criterion (obsolete)

Fields¶

Field	Format	Required
Title	`FR-NNN: Title`	Yes
Priority	P0–P3 (specs), P1–P50 (epics)	Yes
Status	See status codes below	Yes
deps	Comma-separated IDs	No
epic_id	Epic ID (e.g., `E001`)	No

Acceptance Criteria Categories¶

AC-F — Functional
AC-P — Performance
AC-Q — Quality
AC-D — Documentation

Implementation Spec (IMPL)¶

# IMPL-001: Feature Title

**Status:** Active
**LOE:** 3d

## Tasks
- [ ] 1. First task
- [x] 2. Second task (completed)
  - [ ] 2.1. Subtask
  - [->S220] 2.2. Delegated to spec S220

Task Markers¶

Marker	Meaning
`[ ]`	Pending
`[x]`	Completed
`[~]`	Obsolete
`[->SNNN]`	Delegated to another spec

LOE Format¶

Level of effort uses duration notation: 1d (1 day), 3d, 1w (1 week), 2w, etc.

Review & Remediation Lifecycle¶

Before a spec can be completed it must pass an external code review (no self-review). The pipeline is structured end-to-end:

Request — once implementation is committed, the spec is dispatched to the configured review agent ([review].agent, default codex) against the base branch.
Structured verdict — the agent returns a machine-parsed verdict: APPROVED or NEEDS_WORK. The verdict, reviewer, and timestamp are recorded on the IMPL with a tamper-evident signature, and the full history is preserved in the IMPL's Review section.
Structured remediation (on NEEDS_WORK) — the reviewer's blocking findings are injected into the IMPL's ## Tasks as a ### Phase N: Review Remediation (Round R) checklist. The implementer works those injected tasks (they participate in the approval-evidence gate — APPROVED requires every task checked), not the prose findings.
Re-review — after the fixes are committed, review is re-dispatched, repeating up to [review].max_retries (default 5) rounds; on exhaustion the spec is parked with the remediation checklist left in the IMPL as durable, resumable work.
Complete — only an APPROVED verdict (plus all tasks and acceptance criteria checked) lets complete() archive the spec.

Architecture Decision Records (ADR)¶

ADRs use the FR-900–999 ID range and follow an extended lifecycle:

Status	Meaning
DRAFT	Under discussion
PROPOSED	Ready for review
ACCEPTED	Approved and active
DEPRECATED	No longer recommended
SUPERSEDED	Replaced by another ADR

Create an ADR:

nspec adr create --title "Use PostgreSQL for persistence"

Template Profiles¶

When creating specs, you can choose a ceremony level:

nspec spec create --title "My feature" --template quick

Profile	Description
`quick`	Minimal — just title, priority, and placeholder sections
`standard`	Default — executive summary, problem, solution, acceptance criteria
`full`	Extended — adds technical design, test specifications, source files
`formal`	Maximum ceremony — adds dependencies, notes, and all optional sections

Set the default profile in config:

[templates]
default = "standard"

Status Codes¶

FR Statuses¶

Code	Emoji	Status
0	🟡	Proposed
1	🔵	In Design
2	🔵	Active
3	✅	Completed
4	❌	Rejected
5	🔄	Superseded
6	⏳	Deferred

IMPL Statuses¶

Code	Emoji	Status
0	🟡	Planning
1	🔵	Active
2	🧪	Testing
3	🟠	Ready
4	⏳	Paused
5	⚪	Hold
6	⚠️	Exception

View status codes at any time:

nspec status-codes

Priority Levels¶

Level	Emoji	Label
P0	🔥	Critical
P1	🟠	High
P2	🟡	Medium
P3	🔵	Low

Epics use the same P0–P3 range but priorities must be unique across epics. Use swap_priority to reorder.