transform

Transform

Author and refactor the dbt project: both the SQL transformations (staging to marts, tests, docs) and the semantic layer on top (entities, dimensions, measures, metrics). Both are the same job, writing reviewable diffs to the dbt project, which is the source of truth. This is the building half of the loop. It writes only to the repo, as reviewable diffs, and runs against a dev target only.

How to drive it

uv run "${CLAUDE_SKILL_DIR}/scripts/run.py" <subcommand> [flags]

dex runs its engine through uv, which is a prerequisite and is not installed by Claude Code. If the shell reports uv: command not found, stop and tell the user to install it (curl -LsSf https://astral.sh/uv/install.sh | sh, or brew install uv, or pipx install uv), then re-run. Never fall back to editing the dbt project by hand instead: the validation, the diffs, and the dev-target gating live in the engine, so any other path is unguarded.

You author the dbt file content; the engine validates it, computes the diffs, and stores the proposal as a plan. Hand content over with --edits-file <path> (or - to read stdin), a JSON payload:

{"edits": [
  {"path": "models/staging/stg_orders.sql", "kind": "model_sql", "content": "..."},
  {"path": "models/staging/stg_orders.yml", "kind": "schema_yml", "content": "..."},
  {"path": "snapshots/snap_orders.sql", "kind": "snapshot_sql", "content": "..."},
  {"path": "seeds/country_vat.csv", "kind": "seed_csv", "content": "..."},
  {"path": "tests/assert_totals_reconcile.sql", "kind": "test_sql", "content": "..."},
  {"path": "analyses/email_skew.sql", "kind": "analysis_sql", "content": "..."},
  {"path": "models/marts/dim_orders.sql", "kind": "model_sql", "op": "delete"}
]}

kind is model_sql, schema_yml, semantic_yml (optional on semantic define|update|plan, which imply it), macro_sql (a macro file under the project's macro paths), snapshot_sql (a snapshot under the snapshot paths), seed_csv (a seed's CSV under the seed paths), test_sql (a singular test or a generic test definition under the test paths), analysis_sql (SQL dbt compiles but never runs, under the analysis paths), packages_yml, project_yml (the project-root dbt_project.yml), or profiles_yml (the project-root profiles.yml). Model SQL must be a single read-only SELECT once its jinja is stripped; semantic YAML is validated against MetricFlow's schemas, cross-reference-checked, and (when dbt is available) parsed by dbt itself before the plan is accepted; a macro file must hold only macro definitions and jinja comments. A snapshot must hold exactly one {% snapshot %} block whose config() names a unique_key and a strategy of timestamp (with updated_at) or check (with check_cols), and whose body is a single read-only SELECT. A seed must parse as CSV with a named, duplicate-free header and one field per column on every row, and stays under 5,000 data rows and 1 MiB (past that it is data rather than a lookup: load it into the warehouse and source() it). A test_sql file is read to decide which of the two shapes sharing the test paths it is: one holding {% test %} blocks is a generic test definition and must hold only those and jinja comments, balanced; anything else is a singular test and must be a single read-only SELECT. A singular test that names no ref() or source() is warned about, not refused, because it runs against nothing and passes unconditionally. An analysis must be a single read-only SELECT too, even though dbt only compiles it. project_yml must keep a name; profiles_yml must reference every secret via {{ env_var('NAME') }} (a literal credential is refused so none reaches the diff). Config kinds, snapshots and seeds are all parsed by dbt at plan time.