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.

Enterprise adoption choices

Most teams should start with these defaults, then tighten or relax them as their governance needs become clear.

Decision	Recommended default	Deep dive
Development workflow	Use the four-phase loop: specify, plan, tasks, implement. Keep human approval at the spec, plan, and final review gates.	Methodology
Repo retention	Use balanced retention: merge spec.md, plan.md, and review/report evidence; keep tasks.md for complex, regulated, or high-risk work.	Spec retention and repo hygiene
Brownfield rollout	Add the methodology layer first, capture existing conventions, and prove the flow on one low-risk dbt change before broad rollout.	Brownfield onboarding, Team onboarding playbook
Agent knowledge	Use dbt Labs skills for dbt mechanics. Use dbt-spec-kit skills and sub-agent roles for business meaning, planning, governance, and review evidence.	Skills and sub-agents
Warehouse guidance	Pick the closest warehouse preset for cost, materialization, SQL dialect, and governance guardrails. The project still runs through your normal dbt adapter and database connection.	Warehouse guides
CI evidence	Start with local validate and report; promote dbt-specify ci when the team wants lifecycle checks to block PRs.	Enterprise CI
Jira integration	Pull Jira issues into local specs, attach approved specs/plans back to Jira, and create Jira subtasks from tasks.md.	Jira integration
Confluence integration	Pull approved wiki context into specs/<NNN>/context/ and publish spec summaries back to Confluence.	Confluence integration

The key repo hygiene rule: keep approved decision records, not raw agent scratch work.

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 dbt-spec-kit dbt-specify init jaffle-shop --warehouse bigquery

uvx --from dbt-spec-kit 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.

Use uvx for one-off commands. uvx does not install a permanent dbt-specify command, so keep the uvx --from dbt-spec-kit prefix for each CLI call:

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

From GitHub source for development builds:

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
dbt-specify doctor

Use the persistent install when you want to run dbt-specify directly from your shell.

Supported warehouse presets: snowflake, databricks, trino, bigquery, redshift, postgres, sqlserver, azure-sql, mysql, duckdb, motherduck, and athena.

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
• .dbt-specify/agents/ for sub-agent role and handoff templates
• CLAUDE.md or CLAUDE.md.dbt-specify-suggested
• specs/ for feature-level SDLC artifacts

Spec folder structure

Use one direct child folder under specs/ for each meaningful dbt change:

specs/
  001-core-customer-segmentation/
    spec.md
    plan.md
    tasks.md
    review.md
    findings.md

The folder name should be <NNN>-<domain>-<slug> when the team is large enough to need domain visibility. Keep domain names in the slug, not as nested folders. dbt-specify validate project treats each direct specs/*/ child as a feature spec directory.

spec.md is required. plan.md is added after spec approval. tasks.md is added after plan approval. Review, governance, findings, and retro files are optional decision records governed by your team's spec retention policy.

Skills vs sub-agents

Skills are reusable knowledge. They teach an agent how to do a category of work better, such as writing mart specs with grain, checking PII access rules, or using dbt Labs guidance for unit tests.

Sub-agents are bounded workers. Their templates define the mission, required context, allowed edit paths, forbidden files, and output contract for a specific handoff.

Use dbt Labs skills for dbt framework mechanics. Use dbt-spec-kit skills and sub-agent roles for the enterprise delivery workflow around specs, plans, governance, warehouse guardrails, and CI evidence.

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.implement-all executes approved pending tasks sequentially, stopping on validation or scope failures.
• /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

If you did not install the CLI persistently, run the dbt-specify commands above with uvx --from dbt-spec-kit dbt-specify ....

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

Jira bridge

For teams that use Jira as the intake system:

export JIRA_BASE_URL="https://your-company.atlassian.net"
export JIRA_EMAIL="you@company.com"
export JIRA_API_TOKEN="<atlassian-api-token>"

uvx --from dbt-spec-kit dbt-specify jira pull NBA-123
uvx --from dbt-spec-kit dbt-specify jira attach NBA-123 \
  --spec specs/001-nba-123-player-journey/spec.md \
  --plan specs/001-nba-123-player-journey/plan.md
uvx --from dbt-spec-kit dbt-specify jira create-tasks NBA-123 \
  --from specs/001-nba-123-player-journey/tasks.md

Jira remains intake and tracking. spec.md and plan.md remain the approved engineering contract. See Jira integration.

Confluence bridge

For teams that use Confluence as the knowledge base:

export CONFLUENCE_BASE_URL="https://your-company.atlassian.net"
export CONFLUENCE_EMAIL="you@company.com"
export CONFLUENCE_API_TOKEN="<atlassian-api-token>"

uvx --from dbt-spec-kit dbt-specify confluence pull-page 123456789 \
  --to specs/001-player-journey/context/player-metrics.md
uvx --from dbt-spec-kit dbt-specify confluence publish \
  --spec-dir specs/001-player-journey \
  --space-key DATA \
  --parent-id 987654321
uvx --from dbt-spec-kit dbt-specify confluence sync \
  --spec-dir specs/001-player-journey

Confluence remains the knowledge base. spec.md, plan.md, and tasks.md remain the approved implementation contract. See Confluence integration.

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
• Tutorials
• Jaffle-shop AI SDLC walkthrough
• Team onboarding playbook
• Methodology
• Spec retention and repo hygiene
• Skills and sub-agents
• Enterprise CI
• Jira integration
• Confluence integration
• Brownfield onboarding
• EARS cheatsheet
• Releasing to PyPI
• Snowflake guide
• Databricks guide
• Trino guide
• BigQuery guide
• Redshift guide
• Postgres guide
• SQL Server guide
• Azure SQL guide
• MySQL guide
• DuckDB guide
• MotherDuck guide
• Athena 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.