Bootstrap SQLMesh spec kit

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,14 @@
+---
+name: Bug report
+about: Report a sqlmesh-spec-kit issue
+---
+
+## Version
+
+## Command
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Minimal Reproduction

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,10 @@
+---
+name: Feature request
+about: Suggest a sqlmesh-spec-kit improvement
+---
+
+## Use Case
+
+## Proposed Behavior
+
+## SQLMesh Context

.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+## SQLMesh Evidence
+
+- `sqlmesh plan <env>`:
+- tests/audits:
+- apply/promote evidence:
+
+## Spec Boundary
+
+- spec:
+- plan:
+- tasks:
+- files outside approved plan: no

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv run --extra dev ruff check src tests
+      - run: uv run --extra dev mypy src tests
+      - run: uv run --extra dev pytest
+      - run: uv run --extra dev python -m build --sdist --wheel
+      - run: uv run --extra dev python -m twine check dist/*
+      - name: Check sdist exclusions
+        run: |
+          python - <<'PY'
+          import tarfile
+          from pathlib import Path
+          sdist = next(Path("dist").glob("*.tar.gz"))
+          with tarfile.open(sdist) as tar:
+              names = tar.getnames()
+          forbidden = [
+              name
+              for name in names
+              if "/.git/" in name
+              or name.endswith(("/PLAN.md", "/FOLLOWUP.md", "/QUESTIONS.md", "/BUILD-SUMMARY.md"))
+          ]
+          if forbidden:
+              raise SystemExit(f"forbidden paths in sdist: {forbidden}")
+          PY

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sqlmesh-spec-kit
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: uv run --extra dev ruff check src tests
+      - run: uv run --extra dev mypy src tests
+      - run: uv run --extra dev pytest
+      - run: uv run --extra dev python -m build --sdist --wheel
+      - run: uv run --extra dev python -m twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtualenvs
+.venv/
+venv/
+env/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local-only build artifacts
+WAITING.md
+uv.lock
+
+# sqlmesh-spec-kit test outputs inside fixtures
+tests/fixtures/**/.sqlmesh-specify/

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial SQLMesh-native bootstrap.
+- Added installable `sqlmesh-specify` CLI.
+- Added lifecycle, spec, SQLMesh project, doctor, report, Jira, and Confluence support.
+- Added templates, commands, agents, skills, engine presets, docs, tutorials, examples, CI, and release workflow.

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+Use Python 3.11 or newer.
+
+```bash
+uv run --extra dev ruff check src tests
+uv run --extra dev mypy src tests
+uv run --extra dev pytest
+uv run --extra dev python -m build --sdist --wheel
+uv run --extra dev python -m twine check dist/*
+```
+
+Engine presets live in `presets/<engine>/` and may add constitution and plan sections. They must not weaken the base lifecycle gates.

README.md

@@ -0,0 +1,79 @@
+# 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
+
+After the first PyPI release:
+
+```bash
+uvx --from sqlmesh-spec-kit sqlmesh-specify --help
+```
+
+Before PyPI release, install directly from this repository:
+
+```bash
+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.
+
+```bash
+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:
+
+```bash
+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](docs/tutorials/02-ship-a-sqlmesh-change.md).
+
+## 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
+
+```bash
+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](docs/getting-started.md)
+- [Methodology](docs/methodology.md)
+- [Enterprise CI](docs/enterprise-ci.md)
+- [SQLMesh AI SDLC walkthrough](docs/sqlmesh-ai-sdlc-walkthrough.md)
+- [Memory and repo hygiene](docs/sqlmesh-memory-and-repo-hygiene.md)
+- [Tutorials](docs/tutorials/README.md)
+- [Roadmap](ROADMAP.md)

ROADMAP.md

@@ -0,0 +1,28 @@
+# Roadmap
+
+## Phase 1: Bootstrap and Parity
+
+- SQLMesh-native CLI, init, lifecycle validation, doctor, report, CI, Jira, Confluence, docs, templates, commands, agents, skills, examples, and release workflow.
+- Validators check project shape without executing SQLMesh.
+- Humans provide `sqlmesh plan`, audit, test, apply, and promote evidence.
+
+## Phase 2: Policy Configuration
+
+- Add `.sqlmesh-specify/config.yml`.
+- Support severity overrides and project-specific policy toggles.
+
+## Phase 3: Plan/Diff Enforcement
+
+- Validate changed files stay inside approved `plan.md` file lists.
+- Add PR evidence for changed files, AC coverage, SQLMesh plan output, tests, and downstream impact.
+- Candidate command: `sqlmesh-specify validate diff --target . --base-ref main`.
+
+## Phase 4: SQLMesh Artifact Intelligence
+
+- Compare before/after SQLMesh manifests or state artifacts.
+- Detect changed models, downstream children, removed/renamed models, grain changes, missing tests, and semantic-layer impact.
+
+## Phase 5: Enterprise Integration Hardening
+
+- Improve Jira/Confluence idempotency, dry-run detail, version tracking, and failure-mode tests.
+- Add stronger redaction guidance before external publishing.

SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+Do not commit secrets, credentials, customer data, or raw production extracts to spec artifacts.
+
+Before publishing to Jira or Confluence, redact sensitive SQL, PII samples, environment credentials, and private endpoint names that are not required for review.
+
+Report security issues privately through the repository security advisory flow.

SUPPORT.md

@@ -0,0 +1,9 @@
+# Support
+
+Open an issue with:
+
+- sqlmesh-spec-kit version
+- SQLMesh version
+- engine preset
+- command and output
+- minimal repo shape or sanitized spec directory

agents/engine-optimizer.md

@@ -0,0 +1,10 @@
+# Engine Optimizer
+
+Reviews engine-specific SQLMesh tradeoffs.
+
+Responsibilities:
+
+- check materialization, partitioning, clustering, catalog, and cost decisions for the selected engine
+- verify engine preset additions are addressed in `plan.md`
+- flag query patterns that are unsafe for the target engine
+- produce review notes without editing implementation files

agents/governance-reviewer.md

@@ -0,0 +1,10 @@
+# Governance Reviewer
+
+Reviews privacy, access, and publishing risk.
+
+Responsibilities:
+
+- identify PII, regulated fields, and access policy changes
+- require masking, redaction, and downstream owner approval when needed
+- check Jira and Confluence output for sensitive content before publishing
+- block promotion when governance evidence is absent

agents/implementation-agent.md

@@ -0,0 +1,10 @@
+# Implementation Agent
+
+Implements approved tasks only.
+
+Responsibilities:
+
+- read `spec.md`, `plan.md`, and `tasks.md`
+- edit only files listed in the approved plan
+- stop on unexpected SQLMesh plan output, failed audits/tests, or unclear AC traceability
+- update tasks only after evidence exists

agents/review-agent.md

@@ -0,0 +1,10 @@
+# Review Agent
+
+Performs final change review.
+
+Responsibilities:
+
+- compare final diff to `spec.md`, `plan.md`, `tasks.md`, and SQLMesh evidence
+- verify every AC has implementation and evidence
+- block files outside the approved plan
+- summarize residual risk and missing evidence

agents/spec-steward.md

@@ -0,0 +1,10 @@
+# Spec Steward
+
+Owns spec clarity before implementation.
+
+Responsibilities:
+
+- enforce exact lifecycle statuses
+- keep acceptance criteria EARS-formatted
+- ensure SQLMesh models, environments, audits/tests, and downstream owners are named
+- block plans from draft, invalid, or missing-status specs

agents/sqlmesh-architect.md

@@ -0,0 +1,10 @@
+# SQLMesh Architect
+
+Reviews SQLMesh design before tasks are written.
+
+Responsibilities:
+
+- validate model boundaries, snapshot impact, backfill windows, restatements, and forward-only decisions
+- ensure `plan.md` lists every file to add, modify, or delete
+- require `sqlmesh plan <env>` evidence for review
+- block work when plan output is unclear or risky