Open Source

Spec-driven development
for AI-assisted teams

A CLI and spec engine that gives your AI agents intent, context, and accountability. Build with specs that persist across sessions, agents, and tools.

Get Startedbun i -g @betterspec/cli
~/my-project
$ betterspec propose "Add user authentication with OAuth"
betterspec
spec-driven development for AI-assisted teams
Created change: auth-oauth
betterspec/changes/auth-oauth/
proposal.md your idea, structured
specs/
requirements.md what must be true
scenarios.md how it should behave
design.md how to build it
tasks.md what to do, step by step
$ betterspec verify auth-oauth
5/5 checks passed
$ _

How it works

From init to compounding knowledge in three steps. Specs persist across sessions, agents, and tools.

Step 1

Init & Configure

Run betterspec init, choose your tool, and agents, hooks, and skills are set up automatically. One command to go from zero to spec-driven development.

betterspec init
$ betterspec init

  Detected: git repo, package.json
  Choose your tool:
    ● OpenCode
    ○ Claude Code
    ○ Gemini CLI
    ○ Cursor
    ○ Codex

  ✓ Agents configured
  ✓ Hooks installed
  ✓ Skills loaded
  Ready to spec.
Step 2

Spec & Build

Propose changes, plan with specs, build with AI agents that follow your specs. Every task is tracked, every decision is documented.

betterspec propose
$ betterspec propose "Add dark mode"

  Created: betterspec/changes/dark-mode/
    proposal.md
    specs/requirements.md
    specs/scenarios.md
    design.md
    tasks.md

  Agent building... 4/6 tasks done
Step 3

Archive & Compound

Archive completed changes to capture capabilities and decisions. Knowledge compounds: every change makes the project smarter for future agents and developers.

betterspec archive
$ betterspec archive dark-mode

  Archiving: dark-mode
  ✓ Outcome recorded
  ✓ Capability extracted: ui-theming
  ✓ Knowledge base updated
  ✓ Drift score: 100/100

  3 new capabilities this week.
  Your project knows more than yesterday.

Everything you need to build with intent

betterspec gives your AI agents the context, structure, and accountability they need to build the right thing — not just any thing.

Spec Engine

Structured change specs with proposals, requirements, scenarios, design, and tasks. Everything an agent needs to build correctly.

Knowledge Base

Architecture decisions, patterns, and conventions persist in your repo. New agents and new team members get context instantly.

AI-Ready Data Layer

betterspec is a pure data tool — no built-in AI. Your AI platform (OpenCode, Claude Code, Gemini CLI) reads specs, calls betterspec commands, and does the reasoning. Deterministic, fast, provider-agnostic.

Drift Detection

Detect when implementation drifts from specs. Catch misalignment before it compounds across changes.

MCP Server

Expose your knowledge base to any MCP-compatible AI tool. Architecture docs, patterns, capabilities, and decisions — accessible via betterspec serve.

Tool Adapters

One command sets up agents, hooks, and skills for your tool. Built-in support for OpenCode, Claude Code, Gemini CLI, Cursor, and Codex.

Capabilities Tracking

Track what your system can do, not just what code exists. Archive changes into reusable knowledge.

Progress Tracking

See task status across all active changes. Know what's done, what's in progress, and what's blocked.

Tool Adapters

One command sets up your tool. Adapters configure agents, hooks, and skills automatically. Every integration is available today.

OpenCode

Available

Full support: agents, subagents, inline plugin with hooks, agentskills.io skills.

Claude Code

Available

Full support: subagents, lifecycle hooks, skills preloading, CLAUDE.md context.

Gemini CLI

Available

Subagents, hooks, skills via agentskills.io, GEMINI.md context.

Cursor

Available

Comprehensive .cursor/rules/ with workflow context, agentskills.io skills.

Codex

Available

AGENTS.md context, agentskills.io skills.

Stay in the loop

We're building team features, workspace support, and deeper integrations. Get early access and help shape what comes next.

No spam. Unsubscribe anytime.