Core Concepts
Understand the spec engine that powers betterspec.
Core Concepts
betterspec is a spec engine — it manages the lifecycle of changes to your project through structured specifications, a persistent knowledge base, and capability tracking. Everything is stored as plain files in your repository.
Specs & Changes
The fundamental unit in betterspec is a change. Each change moves through a defined lifecycle (proposed → in-progress → completed → archived) and is described by a set of spec files: a proposal, requirements, scenarios, design, and tasks.
Read more about Specs & Changes →
Knowledge Base
The betterspec/knowledge/ directory stores persistent project knowledge that accumulates over time. When a change is archived, lessons learned and patterns discovered are extracted into the knowledge base. AI agents read this context to make better decisions on future changes.
Capabilities
Capabilities are registered descriptions of what your project can do. They live in betterspec/capabilities/ and give AI agents a map of existing functionality, preventing duplicate work and enabling smarter planning.
Drift Detection
betterspec can detect when implementation drifts from specs. The betterspec diff command compares your current code against the spec files to surface discrepancies before they compound.
Progress Tracking
Each change includes a tasks.md file with checkboxes. betterspec parses these to provide a real-time progress dashboard via betterspec status, so you always know where a change stands.
Configuration
The betterspec.json config file controls how betterspec operates — local-only, global, or a hybrid of both.
Read more about Configuration →
Programmatic API
The @betterspec/core package exposes a TypeScript API for reading configs, listing changes, and scaffolding specs programmatically.