Skip to content
/
Tier B A4 Markdown scaffold Variant

spec-driver (davidlee)

spec-driver-davidlee · davidlee/spec-driver · ★ 25 · last commit 2026-05-19

Python CLI + 24 skills + TUI for evergreen specification management — specs that stay accurate as implementations evolve, not disposable planning documents.

Best whenDisposable specs are waste; the machine's job is to convert every implementation change back into verified spec truth via delta tracking, drift detection, an…
Skip ifThrowaway specifications, Specs that diverge silently from implementation
vs seeds
superpowers' passive methodology injection. The PostToolUse hook (artifact_event.py, async) enables TUI follow mode — no seed uses …
Primitive shape 27 total
Skills 24 Subagents 1 Hooks 2
00

Summary

spec-driver (davidlee) — Summary

A Python CLI (spec-driver) that installs a spec-driven development workspace into any repository, shipping 24 skills, 2 hooks, and a configurable TOML-based workflow configuration. Installable via Homebrew, pip (uv/PyPI), or Nix flake. The framework's tagline is "Slow is smooth. Smooth is fast."

The key architectural distinction from other SDD frameworks: spec-driver is built for evergreen specifications — specs that stay accurate as implementations evolve. Rather than write-and-forget planning documents, it maintains a living registry of specifications synchronized to the actual codebase via delta tracking, drift ledgers, and revision history.

A dedicated TUI (spec-driver tui) allows browsing project documentation and following active agent sessions in real time ("live agent session follow mode"). Three ceremony modes (pioneer/settler/town_planner) scale governance from lightweight kanban to full ADR-based policy enforcement.

This is a fork-style relative of the SEED spec-driver already in the corpus at spec-system/spec-driver/. The relationship is direct: the seed spec-driver and this spec-driver-davidlee refer to the same repository (davidlee/spec-driver). The seed analysis was done at an earlier version (v0.9.2 installed config, but v0.9.7 is the current VERSION file); this analysis represents a current-version deep dive with v3 rubric fields populated.

01

Overview

spec-driver (davidlee) — Overview

Origin

Created by davidlee. Repository description: "You install it. Claude drives the CLI tool. At first it might seem like too much. Eventually, nothing less will make sense." 25 stars, Python language, version 0.9.7, last commit 2026-05-19. Available on PyPI, Homebrew tap (davidlee/spec-driver), and as a Nix flake.

Philosophy

From the README:

"Spec-driver is not a framework for development from disposable specifications. It's for driving trustworthy, evergreen specifications out of implementation. A machine, if you will, for converting change into truth."

"Because: when machines can code, what remains is system design. This is a system designed to take care of the rest."

On the core workflow philosophy:

"Slow is smooth. Smooth is fast."

On scope:

"A single framework which can scale from low-ceremony kanban, up to the robust process you need for serious codebases." "Greenfield spec-driven development with Claude Code & friends (Codex, etc)." "Legacy conversions (drift ledgers, incremental specification)."

On the machinery:

"The machinery required is more complex than naive approaches (research → specify → plan → execute) - but it's a very conscious tradeoff."

On pioneer/settler/town_planner modes:

The three ceremony modes represent increasing governance levels:

  • pioneer: lightweight, low-ceremony kanban
  • settler: moderate governance with policies
  • town_planner: full governance (ADRs, policies, standards, coverage gates)

Unique concepts

  • Evergreen specs: Specs that are kept accurate as code evolves, not written-and-abandoned
  • Delta tracking: Changes tracked as deltas against existing specs
  • Drift ledgers: Track where code has drifted from its specification
  • Revisions: Formal spec revision history
  • Agent session follow mode: TUI that shows which artifacts an active Claude session is reading/writing in real time
02

Architecture

spec-driver (davidlee) — Architecture

Distribution

  • Type: cli-tool (Python)
  • Install: Homebrew, uv tool install, pip, Nix flake
  • Install complexity: multi-step

Install commands

# Homebrew (recommended macOS)
brew tap davidlee/spec-driver && brew install spec-driver

# uv (recommended cross-platform)
uv tool install spec-driver

# PyPI
pip install spec-driver

# Nix
nix profile install github:davidlee/spec-driver

After install:

spec-driver install    # Initialize workspace in current repo
spec-driver doctor     # Verify dependencies
spec-driver tui        # Launch TUI browser

Directory tree (workspace, post-install)

.spec-driver/
├── workflow.toml        ← Main config (ceremony, kanban, verification, etc.)
├── AGENTS.md            ← Agent guidance
├── README.md
├── about/               ← Project context
├── agents/
├── audits/
├── backlog/
├── decisions/           ← ADRs
├── deltas/              ← Change tracking
├── drift/               ← Drift ledgers
├── hooks/               ← Event log
├── memory/              ← Agent memory files
├── policies/
├── product/             ← Product specs
├── registry/            ← Spec registry
├── revisions/           ← Spec revision history
├── skills.allowlist     ← Skill permission list
├── skills/              ← Custom project skills
├── standards/           ← Coding standards
├── tech/                ← Technical specs
├── templates/           ← Document templates
└── workflow.toml

.claude/
├── AGENTS.md
├── README.md
├── agents/
│   └── dispatch-worker.md
├── hooks/
│   ├── artifact_event.py   ← PostToolUse hook (file change tracking)
│   ├── startup.sh          ← SessionStart hook (preboot + session ID)
│   └── prompt.sh
├── rules/
├── settings.json           ← Hooks config
└── skills/                 ← 24 named skills

Required runtime

  • Python 3.x
  • uv (recommended)
  • Git

Target AI tools

  • Claude Code (primary — full skills + hooks integration)
  • Codex (.agents/ directory support)
03

Components

spec-driver (davidlee) — Components

CLI Binary: spec-driver

Subcommand Purpose
install Initialize spec-driver workspace in repo
sync Idempotent sync after upgrade
validate Check all registries
doctor Health check
tui Launch TUI browser
admin preboot Pre-generate boot context (called by startup.sh hook)
Additional subcommands for registry, delta, drift, spec management

Skills (24, in .claude/skills/)

Skill Purpose
audit-change Audit a completed change
boot Session initialization (invoked by startup hook)
capturing-memory Record knowledge to memory files
close-change Close/complete a change
consult Consult on approach before acting
continuation Resume from previous work
dispatch Dispatch work to sub-driver
doctrine Load project doctrine
draft-design-revision Draft a design revision
execute-phase Execute a phase from the plan
implement Implement a spec delta
maintaining-memory Maintain memory files
next Determine next action
notes Record working notes
plan-phases Plan execution phases
preflight Pre-implementation check
retrieving-memory Read from memory files
reviewing-memory Review memory state
scope-delta Define scope of a change
shape-revision Shape a revision
spec-driver Main workflow entry point
sub-driver Sub-driver dispatch
update-delta-docs Update delta documentation
using-spec-driver Usage guidance

Subagents (1)

Agent File Purpose
dispatch-worker .claude/agents/dispatch-worker.md Worker agent for dispatched tasks

Hooks (2)

Event File Purpose
SessionStart .claude/hooks/startup.sh Extract session ID, run preboot, inject boot instruction
PostToolUse (Read/Edit/Write) .claude/hooks/artifact_event.py Track file changes for drift/delta detection (async)

Scripts (within CLI)

The Python CLI handles all internal operations (registry sync, preboot generation, validation). No separate bash/python scripts in the repo root.

Templates

templates/ directory in .spec-driver/ — document templates for specs, ADRs, decisions.

MCP Servers

None bundled, but spec-driver can generate TypeScript/JavaScript/Go/Zig contract docs via optional integrations:

  • gomarkdoc
  • ts-doc-extract
  • zigmarkdoc
05

Prompts

spec-driver (davidlee) — Prompts

Excerpt 1 — SessionStart hook output (from startup.sh verbatim)

# Output the boot prompt (existing behavior)
echo '{"systemMessage":"Welcome to spec-driver","hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"you MUST use the /boot skill IMMEDIATELY after receiving the next prompt."}}'

Prompting technique: Mandatory post-hook instruction injection. The hook injects a system-level instruction into Claude's context via the hook's hookSpecificOutput mechanism, instructing the agent to run /boot before anything else. The "MUST" + "IMMEDIATELY" language creates urgency that overrides default agent behavior of responding to the user's prompt first.

Excerpt 2 — workflow.toml comment (verbatim)

## Ceremony mode controls governance posture: how much structure agents
## apply.  Options: "pioneer" (lightweight), "settler" (moderate),
## "town_planner" (full governance).
# ceremony = "town_planner"

## When true, delta completion enforces all coverage gates.
## When false (default), agents may use --force to bypass.
# strict_mode = false

Prompting technique: Escape hatch design. The strict_mode = false default with --force bypass is a deliberate concession to developer pragmatism — the framework acknowledges that 100% enforcement is sometimes counterproductive and provides a documented escape hatch rather than a workaround.

Excerpt 3 — README manifesto (verbatim)

## Slow is smooth. Smooth is fast.

**Why should you care?**
- Designed for building sustainably with agents; supports "pioneer / settler / town planner" modes
- Instead of expensive throwaway research, maintain verifiably accurate, evergreen specs.
- Cheap, fast, deterministically generated docs to help those messy, stochastic agents.
- A TUI for browsing project documentation; live agent session follow mode.
- Token footprint: < 3k to boot with everything activated; skills designed for token-efficiency.

"Spec-driver is not a framework for development from disposable specifications. It's for driving trustworthy, evergreen specifications out of implementation. A machine, if you will, for converting change into truth."

Prompting technique: Anti-throwaway positioning. The framing "not disposable specifications" and "converting change into truth" establishes a philosophical stance that influences how agent skills are written — they are designed to update and maintain specs rather than create-and-forget.

09

Uniqueness

spec-driver (davidlee) — Uniqueness

differs_from_seeds

This IS the spec-driver seed — same repository (davidlee/spec-driver). The seed entry at spec-system/spec-driver/ was analyzed at an earlier state (24 skills per seed-comparison.md) with a simpler v2 rubric. This Phase D analysis adds the v3 fields: the TUI (spec-driver tui) with live session follow mode is the single most distinctive v3 feature — no seed ships a terminal UI for watching active agent artifact access in real time. The SessionStart hook's startup.sh injects a system-level instruction mandating /boot immediately, which is more aggressive than superpowers' SessionStart hook (which injects methodology passively). The PostToolUse hook tracking file changes via artifact_event.py (async) enables the TUI follow mode — no seed uses PostToolUse for this purpose. The three ceremony modes (pioneer/settler/town_planner) provide governance scaling not present in any seed: superpowers is always-on high-ceremony; spec-driver can start lightweight. Most similar seed: superpowers (Archetype 1 — skills-only, 24 skills) but spec-driver adds a CLI, TOML configuration, registry-based spec management, and TUI.

Positioning

The most sophisticated single-author SDD framework in the batch in terms of tooling depth. The evergreen-spec philosophy (not disposable, not throwaway, converted from implementation changes) differentiates it from planning-focused frameworks. The delta → revision → audit chain makes spec maintenance as systematic as code maintenance.

For greenfield projects: pioneer ceremony mode provides a fast on-ramp. For mature codebases: town_planner mode with strict_mode coverage gates provides enterprise-grade governance.

Observable failure modes

  1. Complexity barrier: The framework is explicitly more complex than "naive approaches." The README acknowledges this. New users frequently hit the learning curve before they see the value.
  2. Python/uv dependency: Requires a working Python environment. Projects not using Python add a runtime dependency.
  3. 25 stars despite quality: Very low adoption signal relative to the framework's sophistication. The README tone ("at first it might seem like too much") suggests awareness of the accessibility problem.
  4. TOML config must be maintained: workflow.toml changes require running spec-driver sync to regenerate .claude/ skills — users who edit .claude/skills/ directly will have their changes overwritten.
  5. TUI platform limitation: The terminal TUI may not work well in all Claude Code environments (some run without a true TTY).
04

Workflow

spec-driver (davidlee) — Workflow

Overall flow

Install → Configure workflow.toml → Boot session → Agent drives workflow

The agent (Claude Code) manages the workflow by invoking spec-driver CLI commands. Users rarely interact with the CLI directly after setup.

Ceremony modes

ceremony in workflow.toml:

  • pioneer: Low-ceremony kanban workflow. Task cards, backlog, plans. Minimal overhead.
  • settler: Moderate. Adds policies and standards enforcement.
  • town_planner: Full governance. ADRs, policies, standards, coverage gates, strict_mode option.

Key workflow concepts

Kanban

Task cards in .spec-driver/kanban/. Lanes: backlog → next → doing → finishing → done.

Delta workflow

Changes tracked as deltas:

  1. scope-delta skill: define the scope of a change
  2. implement skill: implement against the delta
  3. audit-change skill: verify the implementation
  4. close-change skill: mark complete and update registry

Spec sync

spec-driver sync — idempotent; run after upgrading. Regenerates .claude/ skills from .spec-driver/ source.

Session boot

At every session start:

  1. startup.sh hook fires → extracts session ID, runs spec-driver admin preboot, injects instruction to use /boot immediately
  2. Agent runs /boot skill → loads project doctrine, memory, and current state

Phase artifacts

Phase Artifact location
Product specs .spec-driver/product/
Technical specs .spec-driver/tech/
Decisions (ADRs) .spec-driver/decisions/
Change deltas .spec-driver/deltas/
Spec revisions .spec-driver/revisions/
Drift records .spec-driver/drift/
Audit logs .spec-driver/audits/
Agent memory .spec-driver/memory/

Approval gates

Gate When Type
Preflight check Before implementation file-review (consult skill)
Delta scope confirmation Before implementing a change yes-no
Audit gate After implementation file-review
strict_mode enforcement Delta completion coverage gates programmatic (CLI)

Verification

Configurable in workflow.toml:

[verification]
command = "just check"   # or "npm test", "pytest", etc.

When set, the close-change skill runs this command before marking complete.

06

Memory Context

spec-driver (davidlee) — Memory & Context

State storage

File-based YAML registries + structured Markdown documents. All state lives in .spec-driver/:

.spec-driver/
├── registry/       ← Spec registry (YAML, relational structure)
├── memory/         ← Agent memory files (persistent notes, knowledge)
├── deltas/         ← Change history
├── revisions/      ← Spec revision history
├── drift/          ← Drift ledgers (where code diverged from spec)
├── audits/         ← Audit records
├── decisions/      ← ADRs
├── policies/
├── standards/
├── product/        ← Product specs
├── tech/           ← Technical specs
└── backlog/        ← Kanban task cards

Memory system

Three memory skills:

  • capturing-memory — Record insights to .spec-driver/memory/
  • maintaining-memory — Update/organize memory files
  • retrieving-memory — Recall relevant memory at task start
  • reviewing-memory — Audit memory state

Persistence

  • Project level: All .spec-driver/ files committed to repository
  • Session level: Session ID tracked via $SPEC_DRIVER_SESSION environment variable (set by startup hook)

Cross-session handoff

The boot skill loads:

  1. Project doctrine (.spec-driver/doctrine.md if configured)
  2. Current memory state
  3. Active deltas and change state

The continuation skill handles resuming from interrupted work.

Artifact event tracking

The artifact_event.py PostToolUse hook fires asynchronously on every Read/Edit/Write tool call, recording which files the agent is accessing. This enables the TUI's "live agent session follow mode" — users can watch in real time which spec files Claude is reading/writing.

Compaction handling

The PreCompact event is not in the hooks — spec-driver relies on the boot skill and memory retrieval to rebuild context after compaction.

Memory type

File-based (Markdown + YAML registries). The registry provides relational structure (spec → delta → revision → audit relationships) without a database.

Evergreen spec mechanism

The delta → revision → audit chain ensures specs stay synchronized with implementation:

  1. Developer defines scope via scope-delta
  2. Agent implements delta
  3. audit-change verifies spec and implementation match
  4. close-change updates registry and closes delta
  5. If spec is now outdated, draft-design-revision creates a revision
07

Orchestration

spec-driver (davidlee) — Orchestration

Multi-agent support

Yes, via dispatch and sub-driver skills. Work can be dispatched to a sub-driver agent (dispatch-worker.md) for parallel task execution.

Orchestration pattern

Sequential primary workflow with optional parallel dispatch via sub-driver.

Isolation mechanism

None mandated (in-place), but the dispatch / sub-driver pattern likely uses separate sessions.

Execution mode

Interactive-loop. The agent drives the CLI; the user initiates sessions.

Multi-model routing

None.

Prompt chaining

Yes, via the boot → doctrine → memory → task chain at every session start:

  1. startup.sh hook → injects boot instruction
  2. /boot skill → loads doctrine + memory
  3. /next skill → determines next action from current state
  4. Appropriate work skill executes

Consensus mechanism

None.

Auto-validators

  • artifact_event.py — real-time file change tracking (PostToolUse, async)
  • spec-driver validate — registry integrity check
  • spec-driver doctor — dependency health check
  • Verification command (configurable in workflow.toml) — run by close-change

Git automation

Not automated. Conventional git usage is encouraged but the framework does not auto-commit or auto-PR.

Parallel execution

Optional via dispatch / sub-driver skills. Not mandated.

08

Ui Cli Surface

spec-driver (davidlee) — UI / CLI Surface

Dedicated CLI binary

Yes.

  • Name: spec-driver
  • Language: Python (packaged via uv/PyPI)
  • Is thin wrapper: No — it is a full Python application with registry management, preboot generation, validation, and TUI
  • Key subcommands: install, sync, validate, doctor, tui, admin preboot

Local TUI

Yes.

  • Type: terminal-tui
  • Command: spec-driver tui
  • Features:
    • Browse project documentation (project-overview.md, specs, ADRs, etc.)
    • Fuzzy find across all project docs
    • Live agent session follow mode: watch which files an active Claude Code session is reading/writing in real-time
  • Tech stack: Python TUI (specific library unknown — likely textual or rich)

From the README:

"A TUI for browsing project documentation; live agent session follow mode." "Fun fact: you can follow the artifacts a claude code session interacts with, in real time."

Observability

  • Session follow mode: TUI shows live artifact access during active agent session
  • artifact_event.py: PostToolUse hook records every Read/Edit/Write with session ID
  • spec-driver validate: Registry integrity check
  • spec-driver doctor: Dependency health check

IDE integration

No IDE extension. Integration is through:

  • .claude/ directory (Claude Code skills + hooks)
  • .agents/ directory (Codex support)
  • CLAUDE.md / AGENTS.md (agent guidance injection)

Installation surface

Multi-platform:

  • Homebrew tap (macOS primary)
  • uv tool install spec-driver (cross-platform, recommended)
  • PyPI pip install spec-driver
  • Nix flake
  • Development: uv add git+https://github.com/davidlee/spec-driver

Contract doc generators (optional extras)

For TypeScript/JavaScript/Go/Zig projects:

  • npm install -g ts-doc-extract
  • go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest
  • zigmarkdoc (davidlee's own tool)

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367
A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25
A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k
A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…