dbt-spec-kit 1.0.0

Enterprise AI SDLC toolkit for dbt projects, with spec-driven workflows, CI validation, and warehouse-specific presets.

dbt-spec-kit

AI SDLC for dbt teams: specs are contracts, agents do bounded implementation, and CI proves the work followed the plan.

dbt-spec-kit helps analytics engineering teams use AI coding agents safely inside real dbt projects. It adds a lightweight spec-driven workflow, warehouse-aware planning templates, agent prompts, and CI validation to an existing dbt repo.

It is modeled on GitHub Spec Kit, composes with dbt-labs/dbt-agent-skills, and works with any agent that reads markdown context, including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and Cline.

Why teams use it

AI agents are useful, but "build a customer mart" is too vague for enterprise dbt work. A safe dbt change needs grain, source contracts, tests, semantic-layer impact, downstream consumers, warehouse cost decisions, and human approval points.

dbt-spec-kit turns that into a repeatable loop:

Idea -> spec.md -> plan.md -> tasks.md -> dbt changes -> CI report -> review

The default is controlled autonomy. Agents can draft and implement, but humans approve the spec, the plan, and the final diff.

Try it with jaffle-shop

The fastest way to understand the workflow is to apply it to the upstream dbt-labs/jaffle-shop project.

git clone https://github.com/dbt-labs/jaffle-shop.git
cd jaffle-shop

uvx --from git+https://github.com/duckcode-ai/dbt-spec-kit.git \
  dbt-specify init jaffle-shop --warehouse bigquery

dbt-specify doctor

Then use your AI agent:

/dbt.specify Add a customer segmentation field to the customers mart without breaking existing metrics.
/dbt.plan
/dbt.tasks
/dbt.implement
/dbt.review

See the full walkthrough: Jaffle-shop AI SDLC walkthrough.

Install

Requires Python 3.11+. Recommended via uv.

After the first PyPI release:

uvx --from dbt-spec-kit dbt-specify init my-project --warehouse snowflake

From the GitHub source before the PyPI release:

uvx --from git+https://github.com/duckcode-ai/dbt-spec-kit.git \
  dbt-specify init my-project --warehouse snowflake

Persistent install:

uv tool install dbt-spec-kit
dbt-specify --version

Supported warehouse presets: snowflake, databricks, trino, and bigquery.

What init adds

Running dbt-specify init in an existing dbt project creates:

• .dbt-specify/constitution.md for project principles and warehouse guardrails
• .dbt-specify/templates/ for spec, plan, tasks, retro, and CI templates
• .dbt-specify/skills/ for spec-writing guidance
• .dbt-specify/commands/ for agent prompts
• CLAUDE.md or CLAUDE.md.dbt-specify-suggested
• specs/ for feature-level SDLC artifacts

The agent commands are:

• /dbt.specify drafts the requirement.
• /dbt.plan creates a file-by-file implementation contract.
• /dbt.tasks decomposes the approved plan into small tasks.
• /dbt.implement executes one task at a time.
• /dbt.analyze checks traceability before implementation.
• /dbt.review reviews the final diff against the approved plan.

CI trust boundary

Use these checks locally or in CI:

dbt-specify validate project
dbt parse
dbt-specify validate dbt --manifest target/manifest.json
dbt-specify report --format markdown

Use dbt-specify ci when the lifecycle and dbt artifact checks should block a PR.

Who this is for

• Analytics engineers who want AI help without losing dbt conventions.
• Data platform leads standardizing AI-assisted delivery across teams.
• dbt consultants who need a repeatable client onboarding method.
• OSS contributors building warehouse presets, validators, examples, and skills.

Docs

• Getting started
• Jaffle-shop AI SDLC walkthrough
• Team onboarding playbook
• Methodology
• Enterprise CI
• Brownfield onboarding
• EARS cheatsheet
• Releasing to PyPI
• Snowflake guide
• Databricks guide
• Trino guide
• BigQuery guide

OSS project

• Contributing
• Security
• Support
• Roadmap
• Changelog

What this is not

• Not a replacement for dbt or dbt Cloud.
• Not a replacement for dbt-labs/dbt-agent-skills.
• Not an IDE or hosted service.
• Not full autonomy or auto-merge.

License

MIT.