AGENT SKILL

dbt-workflows

Route dbt intent to Seshat's governed shadow workflow or the official dbt Labs competence and execution owner, without bypassing readiness or evidence.

License 许可
Apache-2.0
所属仓库
Kemetra/Seshat-BI
最近更新
2026-11-11
Stars
★ 2
Forks
0

01 前言 Front Matter

name
dbt-workflows
description
Route dbt intent to Seshat's governed shadow workflow or the official dbt Labs competence and execution owner, without bypassing readiness or evidence.

03 SKILL.md 正文

Governed dbt workflows

Read ../../portable-operating-contract.md before acting. For a governed Seshat shadow workflow, use only the installed seshat dbt helpers; never bypass their fixed selector, target, profile, lock, redaction, or artifact checks with raw dbt commands.

Intent ownership

User intent Seshat pre-gate Execution owner Seshat afterward
Decide whether dbt fits the current BI stage Readiness and approved-mapping context Seshat selection policy State one truthful next action
Scaffold governed shadow models Approved committed source map Seshat source-map-derived scaffold Validate citations and the meta.seshat contract
Governed compile, build, test, or parity Mapping Ready, exact selector, shadow target, and accepted immutable plan dbt Core through seshat dbt Normalize artifacts into derived evidence, blockers, and parity findings
Generic dbt model authoring, test design, syntax, docs, or troubleshooting Prove the official skill is activated and discoverable Official dbt Labs agent skills If the work enters Seshat's governed project, return through the Seshat gates above
Native dbt MCP configuration or tool use Prove the exact MCP registration is activated and discoverable Official dbt MCP and its official configuration skill Do not infer a readiness effect; route governed execution back through seshat dbt
Switch from migrations to dbt Passing parity evidence plus a named-human approval Named human Retain migrations as parity oracle and rollback path

Spec 148 provides the read-only harness proof for the official dbt Labs agent skills. Before routing generic competence, run seshat integrations setup --profile analytics-full --harness <claude-code|codex> and require the dbt-agent-skills result to be discoverable. MCP liveness remains a separate preflight fact. Report the exact blocker for either surface; do not copy official guidance into this router, claim an installed payload is usable, or execute raw dbt commands against the governed project as a fallback.

Fixed workflow

  1. Check prerequisites without a database query:

    seshat dbt doctor --format json

  2. Materialize the governed model set from the approved map (once per table):

    seshat dbt scaffold --table <table> --format json

    This writes, FROM the approved committed source map, the staging model, one gold model per fact/dim, the parity-audit model, their native dbt contracts, the seshat_table_<table> selector row, and the bronze + migration_gold sources. It is non-destructive (an existing file is kept) and needs no database. The generated .sql files are SKELETONS: their SELECT column list is the governed output contract (do not rename or drop columns), but the joins, casts, and surrogate-key logic are yours to complete before the live build. NOTE: scaffold is non-destructive (it never overwrites an existing model), so after a source-map re-commit a plain re-run does NOT refresh a stale source_map_revision — you must update each model's source_map_revision by hand, or delete the generated _models.yml and re-scaffold. See "The meta.seshat model contract" below for the shape scaffold emits and validate enforces.

  3. Validate the Mapping Ready gate, shadow schemas, selector, and citations:

    seshat dbt validate --table <table> --format json

  4. Produce and review the immutable plan:

    seshat dbt plan --table <table> --format json

    Confirm the approved mapping identity, pinned dbt versions, exact selected model/test IDs, and shadow-only schemas. The returned digest is the only valid --accept-plan value; it is neither a mapping approval nor a readiness approval.

  5. With the reviewed digest, execute the fixed graph:

    seshat dbt build --table <table> --accept-plan <digest> --format json

    Use seshat dbt test --table <table> --accept-plan <digest> --format json only for a test-only rerun. Both recompute the plan before database access; drift stops execution and requires a new plan and review.

  6. Review the returned normalized evidence. When a user supplies an existing run directory under .seshat/dbt/runs/, revalidate it offline with:

    seshat dbt inspect-run --table <table> --artifacts <run-directory> --format json

    Do not invent a run directory or treat inspect-run as a required second build. Report parity failures and blocking_reasons, then stop for a named human. Passing output is derived evidence only.

The meta.seshat model contract

seshat dbt scaffold emits this shape and seshat dbt validate enforces it; you should never need to reverse-engineer it from a gate error. Each _models.yml row carries, at the TOP level of the row (NOT under config -- nesting meta there silently orphans the model, because the validator reads row['meta'] while the tag reads row['config']['tags']):

- name: <model_name>              # dim_* / stg_* / audit_* / the one fact
  config:
    tags: [seshat_table_<table>]  # the governed selector tag
  meta:
    seshat:
      table_id: <table>
      source_map: mappings/<table>/source-map.yaml
      source_map_revision: <git blob sha of the committed map>
      grain: <one row = ...>
      business_key: [<key column(s)>]
      authority: derived          # always exactly "derived"
  columns:
    - name: <column>
      data_type: <postgres type>  # ADVISORY (source columns only), not an
                                   # enforced contract; the human owns casts
      meta:
        seshat:
          source_columns: [bronze.<table>.<src>]   # OR:
          # derivation: surrogate_key | date_spine | unknown_member | parity_measure

source_map_revision is the git BLOB sha of the committed map (git rev-parse HEAD:mappings/<table>/source-map.yaml), so every model is coupled to one committed map revision: any map edit needs a re-commit AND a re-scaffold, or validate reports DBT_MODEL_CITATION_STALE. Every output column MUST carry either source_columns (an approved-map citation) or one of the four governed derivation values -- an uncited column is a defect.

The parity-audit model emits exactly the assertion rows dbt show consumes: one fact_row_count, one business_key_count (subject = <fact>.<key cols>), one additive_money_total per approved money measure, and one dimension_member_count per built dimension (tolerances: money 0.01, else 0). Scaffold derives this set from the approved map's gold_star.fact tags (business_key, additive_money_measures) and the built dim_* models; do not hand-edit it out of agreement with the map.

Hard boundaries

  • Stop before planning unless Mapping Ready has a named-human approval.
  • Put real SESHAT_DBT_* values only in the gitignored .env; keep profiles.yml as env_var() references.
  • If the dbt extra, profile, DSN, or live database is absent, report [PENDING LIVE PROFILE] with enable steps; never fabricate compile, build, test, or parity success.
  • Migrations remain the default build path after parity. A separate named human must approve switching the active path, and migrations remain the parity oracle and rollback path until separately retired.
  • Never write a readiness pass, migration-switch approval, confidence score, raw adapter output, credential, DSN, or absolute local path.

Exit meanings

  • exit 0: command completed; dbt output remains derived evidence.
  • exit 1: handled model, test, or parity failure.
  • exit 2: usage or runtime/profile/database prerequisite unavailable.
  • exit 3: governance refusal, lock conflict, or accepted-plan drift.
  • exit 4: artifact or normalized-evidence integrity failure.

04 同仓库更多 Skills

Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

bare-skill-no-frontmatter

暂无简介

★ 2
Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

retail-kpi-knowledge

Retail KPI / metric-contract reasoning layer for BI agents in the Seshat BI project. Use when an agent must reason about the BUSINESS MEANING of a retail KPI before any implementation — defining a KPI in business terms, classifying additivity (fully/semi/non-additive), identifying grain, listing required source fields, resolving ambiguity (gross vs net, VAT, returns, cost method, same-store), choosing an MVP KPI pack, reviewing a metric contract for completeness, or preparing a clean handoff to an implementation layer. Also use it to classify KPI sufficiency or prepare an owner policy decision packet. This is a meaning/definition + review layer, not an executor: it does not write DAX/SQL/Python, grant readiness, approve policy, or design dashboards. See INDEX.md for live/planned routes; registry.yaml is the authoritative machine-readable inventory.

★ 2
Kemetra
Kemetra/Seshat-BI

bi-sql-knowledge

SQL reasoning, validation, reconciliation, transformation, diagnostics, and anti-pattern knowledge layer for Seshat BI agents. Use when a task involves reasoning about source SQL: source profiling, table grain, keys & uniqueness, joins & fan-out amplification, aggregation correctness, COUNT/NULL semantics, deduplication, validation queries, reconciliation queries, silver/gold transformation logic, window/date-time analytics, SQL anti-patterns, or basic SQL performance reasoning, or interpretation of a supplied sanitized PostgreSQL JSON execution plan. The SQL counterpart to bi-dax-knowledge. It is a thinking & validation layer, not a database executor, runtime validator, dbt/Dagster project, or automatic tuning service.

★ 2