Getting Started
Install betterspec and create your first spec in under 5 minutes.
Getting Started
betterspec is a spec-driven development tool for AI-assisted teams. It provides a CLI and spec engine for managing specifications, knowledge bases, capabilities, and drift detection — with no AI of its own. Your AI coding platform reads betterspec specs and calls betterspec commands to manage the workflow.
Installation
bun i -g @betterspec/clinpm i -g @betterspec/cliQuick Start
Initialize betterspec in your project
cd your-project
betterspec initThis creates a betterspec/ directory with your project config, knowledge base, and a skill file for AI agents.
Propose a change
betterspec propose "Add user authentication with OAuth"This scaffolds a full change spec:
betterspec/changes/auth-oauth/
proposal.md # What and why
specs/
requirements.md # What must be true
scenarios.md # How it should behave
design.md # How to build it
tasks.md # Step-by-step implementation planFill in the specs
Edit the generated files to describe your change. The more detail you provide, the better your AI agents can implement it.
Verify completeness
betterspec verify auth-oauthChecks that all spec files are present and well-formed. All 5 checks should pass before you start building.
Build and validate
Use your preferred AI tool to implement the tasks. When done, archive the change:
betterspec archive auth-oauthThis captures the outcome, extracts knowledge, and moves the change to the archive.
What's Next?
- CLI Reference — All 14 commands explained
- Core Concepts — Specs, changes, knowledge, capabilities
- Integrations — Connect betterspec to your AI tools
betterspec is provider-agnostic and has no built-in AI. Specs are markdown files in your repo — any AI tool can read them. For the richest integration, connect your AI tool via the MCP server.