sqlmesh-spec-kit

AI SDLC and durable memory for SQLMesh teams: specs are contracts, SQLMesh plans are deployment evidence, and agents implement only inside approved task boundaries.

Install

Install from PyPI:

uvx --from sqlmesh-spec-kit sqlmesh-specify --help

To test unreleased changes from main, install directly from this repository:

uvx --from git+https://github.com/duckcode-ai/sqlmesh-spec-kit.git sqlmesh-specify --help

Initialize

Run inside an existing SQLMesh project with config.yaml, config.yml, or config.py and a models/ directory.

sqlmesh-specify init analytics --engine duckdb --target .
sqlmesh-specify doctor --target .
sqlmesh-specify validate project --target .
sqlmesh-specify validate sqlmesh --target .
sqlmesh-specify report --target . --format markdown

Supported engine presets: duckdb, snowflake, databricks, bigquery, trino, redshift, postgres, mysql, mssql, athena, spark, and clickhouse.

Verified SQLMesh Example

The full SDLC flow has been tested against the official SQLMesh examples repository:

git clone https://github.com/TobikoData/sqlmesh-examples.git
cd sqlmesh-examples/001_sushi/2_moderate
uvx --from git+https://github.com/duckcode-ai/sqlmesh-spec-kit.git sqlmesh-specify init sushi-moderate --engine duckdb --target .
uvx --from git+https://github.com/duckcode-ai/sqlmesh-spec-kit.git sqlmesh-specify ci --target .

For the complete spec, plan, tasks, implementation, SQLMesh test, and sqlmesh plan dev --auto-apply --no-prompts flow, follow Tutorial 02.

Workflow

1. Draft spec.md with EARS acceptance criteria.
2. Human approves the spec by setting status exactly to approved.
3. Create plan.md with SQLMesh environment, changed models, audits/tests, backfill scope, forward-only/restatement decision, and plan/apply evidence expectations.
4. Human approves the plan by setting status exactly to approved.
5. Create tasks.md and implement only approved files.
6. Review final diff against spec.md, plan.md, tasks.md, and SQLMesh plan/audit/test evidence.

Validators do not execute SQLMesh in v0.1. Run sqlmesh plan <env>, tests, and audits in your project workflow and attach the evidence to the spec directory or PR.

CLI

sqlmesh-specify init <project-name> --engine <engine> --target . [--force]
sqlmesh-specify doctor --target .
sqlmesh-specify validate <path/to/spec.md>
sqlmesh-specify validate project --target .
sqlmesh-specify validate sqlmesh --target .
sqlmesh-specify report --target . --format markdown
sqlmesh-specify ci --target .
sqlmesh-specify jira pull|attach|create-tasks|sync
sqlmesh-specify confluence pull-page|publish|sync

Docs

• Getting started
• Methodology
• Enterprise CI
• SQLMesh AI SDLC walkthrough
• Memory and repo hygiene
• Tutorials
• Roadmap