spec-driver 0.4.0

Specification-driven development toolkit with multi-language spec sync and documentation generation

spec-driver

Specification-driven development toolkit with multi-language spec sync and documentation generation.

Why?

• Maintain verifiably accurate, evergreen specs covering your entire system
• Use cheap, fast, deterministically generated docs to complement and audit the work of messy, stochastic agents
• The combination of markdown and YAML is a surprisingly powerful platform for structured, legible data
• Tooling joins related entities through a registry for fast lookup, validation, and relational data propagation
• Stop banging rocks together

Status

Alpha - Under active development. API and CLI may change.

Features

• Multi-language spec sync: Automatically sync specifications with Go, Python & TypeScript/JS codebases
• Architecture Decision Records (ADRs): Manage and track architectural decisions
• Policies & Standards: Document hard rules (policies) and conventions (standards) with lifecycle management
• Delta/Change tracking: Relate specification changes, requirements, deltas, implementation plans and revisions
• Documentation generation: Generate compact, legible, deterministic markdown documentation from code
• Workspace validation: Ensure consistency across specification artifacts
• Orphan detection: Safely remove specs for deleted source files

Installation

PyPi package

# try before you buy (no install)
uvx spec-driver --help

# Or settle in with it 
uv init
uv add speec-driver
uv run spec-driver --help

From GitHub (Development)

# Install from latest commit
uv init 
uv add git+https://github.com/davidlee/spec-driver
uv run spec-driver --help

# Or use it right off the tubes
uvx --from git+https://github.com/davidlee/spec-driver spec-driver --help

Quick Start

# Initialize workspace in your project
spec-driver install

# Sync specs with your codebase
spec-driver sync

# List all specs
spec-driver list specs

# Create a new spec
spec-driver create spec --kind tech

# Create a new delta
spec-driver create delta 

Usage

All commands are accessed through the unified spec-driver CLI.

Installation & Setup

# Initialize spec-driver workspace structure
spec-driver install

# This creates:
# - specify/ directory (for specs, ADRs)
# - change/ directory (for deltas, revisions)
# - .spec-driver/registry/ (for YAML registries)
# - Templates and configuration files

Synchronization

# Sync all specs with source code (auto-discovery)
spec-driver sync

# Sync only existing registered specs
spec-driver sync --existing

# Sync specific language
spec-driver sync --language python

# Sync specific targets
spec-driver sync go:internal/foo python:module.py

# Dry run to preview changes
spec-driver sync --dry-run

# Check if docs are up-to-date (CI-friendly)
spec-driver sync --check

# Remove specs for deleted source files
spec-driver sync --existing --prune

# Sync ADR registry
spec-driver sync --adr

Creating Artifacts

# Create a new technical spec
spec-driver create spec --kind tech

# Create a new product spec
spec-driver create spec --kind product

# Create a new delta (change proposal)
spec-driver create delta

# Create a requirement breakout
spec-driver create requirement

# Create a spec revision
spec-driver create revision

# Create an ADR
spec-driver create adr

Delta creation scaffolds a full bundle by default:

• DE-XXX.md — delta summary and scope
• DR-XXX.md — design revision capturing architecture intent, code impacts, and verification alignment
• IP-XXX.md — implementation plan
• phases/phase-01.md — first execution phase sheet
• notes.md — scratchpad for research and findings

Listing Artifacts

# List all specs
spec-driver list specs

# List specs for specific package
spec-driver list specs --package internal/foo

# List specs with package details
spec-driver list specs --packages

# List deltas
spec-driver list deltas

# List deltas by status
spec-driver list deltas --status active

# List all changes (deltas, revisions, audits)
spec-driver list changes

# List changes by kind
spec-driver list changes --kind delta

Architecture Decision Records

# Create new ADR
spec-driver create adr

# List ADRs
spec-driver list adrs

# List ADRs by status
spec-driver list adrs --status accepted

# Show ADR details
spec-driver show adr ADR-001

# Sync ADR registry
spec-driver sync --adr

Policies and Standards

# Create a policy (hard rule)
spec-driver create policy "All code must have tests"

# Create a standard (convention/default)
spec-driver create standard "Use Google Python Style Guide"

# List policies
spec-driver list policies

# List policies by status
spec-driver list policies --status required

# List standards with "default" status
spec-driver list standards --status default

# Show policy details
spec-driver show policy POL-001

# Show standard details
spec-driver show standard STD-001

# List ADRs that reference a policy
spec-driver list adrs --policy POL-001

# List ADRs that reference a standard
spec-driver list adrs --standard STD-001

Validation

# Validate workspace consistency
spec-driver validate

Completing Work

# Mark delta as completed
spec-driver complete delta DE-001

Project Integration

spec-driver integrates into your project using:

1. Directory structure: specify/ and change/ directories
2. Registry files: .spec-driver/registry/*.yaml for cross-references
3. Templates: .spec-driver/templates/ for consistent artifact creation
4. Agent instructions: .claude/commands for AI-assisted development

Common Workflows

Daily Development

# 1. Create a delta for your change
spec-driver create delta

# 2. Write code, update specs as needed

# 3. Sync specs with code
spec-driver sync

# 4. Validate consistency
spec-driver validate

# 5. Mark delta complete
spec-driver complete delta DE-XXX

Onboarding New Code

# Auto-discover and create specs for existing code
spec-driver sync --language python

# Review what would be created first
spec-driver sync --dry-run

Cleaning Up

# Find orphaned specs (source files deleted)
spec-driver sync --existing --prune --dry-run

# Remove them
spec-driver sync --existing --prune

Continuous Integration

# Verify specs are up-to-date
spec-driver sync --check

# Validate workspace
spec-driver validate

Development

This package is under active development and cli API stability is not even hinted at.

I'll aim not to make breaking changes to data formats, though.

Related

• PyPi project
• npm dependency for TS doc gen
• sort of a website

License

MIT