From b520f7025124c249cf05da60c8a325ba79381c21 Mon Sep 17 00:00:00 2001 From: KKranthi6881 Date: Sun, 17 May 2026 22:46:58 -0500 Subject: [PATCH] Add skills and sub-agent architecture --- CHANGELOG.md | 5 + README.md | 9 +- agents/dbt-architect.md | 27 +++++ agents/governance-reviewer.md | 26 +++++ agents/implementation-agent.md | 29 +++++ agents/review-agent.md | 26 +++++ agents/spec-steward.md | 26 +++++ agents/warehouse-optimizer.md | 25 +++++ docs/brownfield-onboarding.md | 4 +- docs/enterprise-ci.md | 3 + docs/getting-started.md | 11 +- docs/jaffle-shop-ai-sdlc-walkthrough.md | 8 +- docs/methodology.md | 11 ++ docs/releasing.md | 4 +- docs/skills-and-sub-agents.md | 104 ++++++++++++++++++ pyproject.toml | 5 +- skills/capturing-project-conventions/SKILL.md | 34 ++++++ skills/reviewing-ac-traceability/SKILL.md | 33 ++++++ skills/reviewing-ci-evidence/SKILL.md | 36 ++++++ .../reviewing-pii-access-governance/SKILL.md | 33 ++++++ src/dbt_specify/_version.py | 2 +- src/dbt_specify/doctor.py | 6 + src/dbt_specify/init.py | 8 +- src/dbt_specify/templates_loader.py | 4 +- templates/CLAUDE.md.template | 15 +++ tests/test_dbt_artifacts.py | 16 +++ tests/test_docs.py | 26 +++++ tests/test_init.py | 15 ++- 28 files changed, 528 insertions(+), 23 deletions(-) create mode 100644 agents/dbt-architect.md create mode 100644 agents/governance-reviewer.md create mode 100644 agents/implementation-agent.md create mode 100644 agents/review-agent.md create mode 100644 agents/spec-steward.md create mode 100644 agents/warehouse-optimizer.md create mode 100644 docs/skills-and-sub-agents.md create mode 100644 skills/capturing-project-conventions/SKILL.md create mode 100644 skills/reviewing-ac-traceability/SKILL.md create mode 100644 skills/reviewing-ci-evidence/SKILL.md create mode 100644 skills/reviewing-pii-access-governance/SKILL.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7415ae7..7b55b66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.1.0] — 2026-05-18 + ### Added +- Sub-agent role templates installed to `.dbt-specify/agents/`. +- Enterprise skills for AC traceability, PII/access governance, project convention capture, and CI evidence review. +- Skills and sub-agents documentation showing how dbt-spec-kit composes with dbt-labs/dbt-agent-skills. - Launch-ready OSS project files: issue templates, pull request template, SECURITY, SUPPORT, and ROADMAP. - Jaffle-shop AI SDLC walkthrough using the upstream dbt Labs project as the onboarding demo. - Team onboarding playbook for introducing dbt-spec-kit to analytics engineering teams. diff --git a/README.md b/README.md index d70739b..14dd31a 100644 --- a/README.md +++ b/README.md @@ -36,8 +36,7 @@ The fastest way to understand the workflow is to apply it to the upstream git clone https://github.com/dbt-labs/jaffle-shop.git cd jaffle-shop -uvx --from git+https://github.com/duckcode-ai/dbt-spec-kit.git \ - dbt-specify init jaffle-shop --warehouse bigquery +uvx --from dbt-spec-kit dbt-specify init jaffle-shop --warehouse bigquery dbt-specify doctor ``` @@ -58,13 +57,11 @@ See the full walkthrough: [Jaffle-shop AI SDLC walkthrough](docs/jaffle-shop-ai- Requires Python 3.11+. Recommended via [uv](https://docs.astral.sh/uv/). -After the first PyPI release: - ```bash uvx --from dbt-spec-kit dbt-specify init my-project --warehouse snowflake ``` -From the GitHub source before the PyPI release: +From GitHub source for development builds: ```bash uvx --from git+https://github.com/duckcode-ai/dbt-spec-kit.git \ @@ -88,6 +85,7 @@ Running `dbt-specify init` in an existing dbt project creates: - `.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 @@ -126,6 +124,7 @@ Use `dbt-specify ci` when the lifecycle and dbt artifact checks should block a P - [Jaffle-shop AI SDLC walkthrough](docs/jaffle-shop-ai-sdlc-walkthrough.md) - [Team onboarding playbook](docs/team-onboarding-playbook.md) - [Methodology](docs/methodology.md) +- [Skills and sub-agents](docs/skills-and-sub-agents.md) - [Enterprise CI](docs/enterprise-ci.md) - [Brownfield onboarding](docs/brownfield-onboarding.md) - [EARS cheatsheet](docs/ears-cheatsheet.md) diff --git a/agents/dbt-architect.md b/agents/dbt-architect.md new file mode 100644 index 0000000..7f555cb --- /dev/null +++ b/agents/dbt-architect.md @@ -0,0 +1,27 @@ +# dbt Architect + +## Mission + +Review the proposed dbt design for model layering, lineage, contracts, tests, semantic-layer impact, +and use of dbt Labs skills. + +## Required context + +- Approved `spec.md` +- Draft or approved `plan.md` +- `dbt_project.yml` +- `models/`, `macros/`, `snapshots/`, `seeds/`, and semantic-layer files relevant to the plan +- Installed `dbt-labs/dbt-agent-skills` for dbt framework mechanics + +## Allowed edits + +- `specs/-/plan-review.md` +- `specs/-/findings.md` + +Do not edit SQL, YAML, macros, or package files. + +## Output contract + +- A review of model boundaries, tests, contracts, lineage, and semantic-layer impacts. +- A list of required plan changes before implementation. +- Explicit confirmation that dbt framework questions were routed to dbt Labs skills. diff --git a/agents/governance-reviewer.md b/agents/governance-reviewer.md new file mode 100644 index 0000000..53cfa5e --- /dev/null +++ b/agents/governance-reviewer.md @@ -0,0 +1,26 @@ +# Governance Reviewer + +## Mission + +Review PII, access, contracts, ownership, data retention, and policy-sensitive changes. + +## Required context + +- Approved `spec.md` +- Approved or draft `plan.md` +- Project governance conventions in `CLAUDE.md` +- `.dbt-specify/skills/reviewing-pii-access-governance/SKILL.md` +- Relevant model YAML, source YAML, exposure YAML, and semantic-layer files + +## Allowed edits + +- `specs/-/governance-review.md` +- `specs/-/findings.md` + +Do not edit production dbt assets directly. + +## Output contract + +- A pass/block decision for PII and access handling. +- Required ownership, masking, grants, contracts, or exposure changes. +- Any unresolved policy questions for a human owner. diff --git a/agents/implementation-agent.md b/agents/implementation-agent.md new file mode 100644 index 0000000..29b9d1a --- /dev/null +++ b/agents/implementation-agent.md @@ -0,0 +1,29 @@ +# Implementation Agent + +## Mission + +Implement exactly one approved task from `tasks.md`. + +## Required context + +- Approved `spec.md` +- Approved `plan.md` +- Approved `tasks.md` +- `.dbt-specify/constitution.md` +- `CLAUDE.md` +- Relevant dbt Labs and dbt-spec-kit skills + +## Allowed edits + +- Only files listed in the approved plan's "Files to add/modify/delete" section. +- The active task checkbox in `tasks.md`. +- `specs/-/findings.md` for discovered out-of-scope issues. + +Do not edit unlisted files. Do not work ahead to the next task. + +## Output contract + +- The completed task id. +- Files changed. +- Validation commands and results. +- Any blocked or deferred findings. diff --git a/agents/review-agent.md b/agents/review-agent.md new file mode 100644 index 0000000..21f67fb --- /dev/null +++ b/agents/review-agent.md @@ -0,0 +1,26 @@ +# Review Agent + +## Mission + +Review the final diff against the approved spec, plan, tasks, tests, and CI evidence. + +## Required context + +- Approved `spec.md`, `plan.md`, and `tasks.md` +- Git diff for the PR +- `dbt-specify report --format markdown` output +- dbt parse/build/test evidence supplied by the implementer + +## Allowed edits + +- `specs/-/review.md` +- `specs/-/findings.md` + +Do not fix issues during review. Report them with severity and exact file references. + +## Output contract + +- Findings ordered by severity. +- AC coverage summary. +- Validation evidence summary. +- Final recommendation: approve, request changes, or block. diff --git a/agents/spec-steward.md b/agents/spec-steward.md new file mode 100644 index 0000000..e52b72b --- /dev/null +++ b/agents/spec-steward.md @@ -0,0 +1,26 @@ +# Spec Steward + +## Mission + +Convert a business request into an approved `spec.md` that an implementation agent can safely use. + +## Required context + +- `.dbt-specify/constitution.md` +- `CLAUDE.md` +- `.dbt-specify/templates/spec-template.md` +- Relevant `.dbt-specify/skills/` files + +## Allowed edits + +- `specs/-/spec.md` +- `specs/-/questions.md` +- `specs/-/findings.md` + +Do not edit dbt models, YAML, macros, packages, seeds, snapshots, or CI files. + +## Output contract + +- A complete spec with EARS-formatted acceptance criteria. +- A short review note naming open assumptions and reviewer questions. +- `dbt-specify validate specs/-/spec.md` evidence. diff --git a/agents/warehouse-optimizer.md b/agents/warehouse-optimizer.md new file mode 100644 index 0000000..4eb4cef --- /dev/null +++ b/agents/warehouse-optimizer.md @@ -0,0 +1,25 @@ +# Warehouse Optimizer + +## Mission + +Review warehouse-specific design decisions before code is written. + +## Required context + +- Approved `spec.md` +- Draft or approved `plan.md` +- `.dbt-specify/constitution.md` +- Warehouse-specific plan additions and skills under `.dbt-specify/skills/` + +## Allowed edits + +- `specs/-/warehouse-review.md` +- `specs/-/findings.md` + +Do not edit dbt models or warehouse configuration files directly. + +## Output contract + +- A table of cost, performance, partitioning, clustering, materialization, and governance findings. +- Required changes to the plan before implementation. +- Clear "approved" or "blocked" status for warehouse decisions. diff --git a/docs/brownfield-onboarding.md b/docs/brownfield-onboarding.md index b17f77f..4cec6b3 100644 --- a/docs/brownfield-onboarding.md +++ b/docs/brownfield-onboarding.md @@ -10,8 +10,8 @@ cd path/to/dbt-project dbt-specify doctor ``` -The doctor command reports missing adoption pieces such as `.dbt-specify/`, `CLAUDE.md`, `specs/`, -`target/manifest.json`, and model documentation/test inventory. +The doctor command reports missing adoption pieces such as `.dbt-specify/`, `CLAUDE.md`, +`.dbt-specify/agents/`, `specs/`, `target/manifest.json`, and model documentation/test inventory. If your team wants a low-risk practice run first, use the [jaffle-shop AI SDLC walkthrough](jaffle-shop-ai-sdlc-walkthrough.md). It shows the same adoption diff --git a/docs/enterprise-ci.md b/docs/enterprise-ci.md index 92900dd..0f3ee87 100644 --- a/docs/enterprise-ci.md +++ b/docs/enterprise-ci.md @@ -58,3 +58,6 @@ For the jaffle-shop semantic mart walkthrough, the PR should include: - `dbt parse` evidence showing semantic models, metrics, and saved queries still resolve - `dbt-specify-report.md` generated with `dbt-specify report --format markdown` - reviewer sign-off for metric compatibility and downstream impact + +For delegated reviews, attach the relevant `.dbt-specify/agents/` output files such as +`warehouse-review.md`, `governance-review.md`, or `review.md`. diff --git a/docs/getting-started.md b/docs/getting-started.md index a41d0af..dbc186e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -17,7 +17,7 @@ The recommended path uses `uv` for isolated tool installation: curl -LsSf https://astral.sh/uv/install.sh | sh # install dbt-specify as a tool -uv tool install dbt-spec-kit --from git+https://github.com/duckcode-ai/dbt-spec-kit.git +uv tool install dbt-spec-kit ``` Verify: @@ -38,6 +38,7 @@ This creates: - `.dbt-specify/templates/` — spec, plan, tasks, retro - `.dbt-specify/skills/` — tier-2 and tier-3 spec-writing skills - `.dbt-specify/commands/` — slash-command prompts +- `.dbt-specify/agents/` — sub-agent role and handoff templates - `CLAUDE.md` — the agent orientation file (or `CLAUDE.md.dbt-specify-suggested` if you already have one) - `specs/` — empty directory for your first spec @@ -55,7 +56,12 @@ npx skills add dbt-labs/dbt-agent-skills tessl install dbt-labs/dbt-agent-skills ``` -CLAUDE.md from `dbt-specify init` already defers tier-1 questions to that collection. +CLAUDE.md from `dbt-specify init` already defers tier-1 questions to that collection and routes +business, warehouse, governance, and traceability decisions to `.dbt-specify/skills/`. + +For delegation guidance, see [Skills and sub-agents](skills-and-sub-agents.md). The short version: +skills are reusable knowledge; sub-agents are bounded workers with file ownership and output +contracts. ## Your first spec @@ -94,5 +100,6 @@ dbt-specify doctor - Try the [jaffle-shop AI SDLC walkthrough](jaffle-shop-ai-sdlc-walkthrough.md) to see the process on a real dbt Labs project. - Use the [team onboarding playbook](team-onboarding-playbook.md) when presenting the workflow to an analytics engineering team. - Read [methodology.md](methodology.md) for the full four-phase loop. +- Read [skills-and-sub-agents.md](skills-and-sub-agents.md) for dbt Labs skills composition and safe sub-agent delegation. - Read [warehouse-guides/snowflake.md](warehouse-guides/snowflake.md) or [databricks.md](warehouse-guides/databricks.md) for your warehouse's preset. - See [`examples/jaffle-shop-staging-overhaul/`](../examples/jaffle-shop-staging-overhaul/) for a complete worked example. diff --git a/docs/jaffle-shop-ai-sdlc-walkthrough.md b/docs/jaffle-shop-ai-sdlc-walkthrough.md index 048cc53..ae54254 100644 --- a/docs/jaffle-shop-ai-sdlc-walkthrough.md +++ b/docs/jaffle-shop-ai-sdlc-walkthrough.md @@ -51,8 +51,7 @@ If you are using dbt Cloud, run the equivalent steps in the Cloud IDE or Cloud C Choose the preset that matches your warehouse: ```bash -uvx --from git+https://github.com/duckcode-ai/dbt-spec-kit.git \ - dbt-specify init jaffle-shop --warehouse bigquery +uvx --from dbt-spec-kit dbt-specify init jaffle-shop --warehouse bigquery ``` For Snowflake, Databricks, or Trino, replace `bigquery` with the matching preset. @@ -63,8 +62,9 @@ Run the brownfield diagnostic: dbt-specify doctor ``` -Expected result: doctor reports adoption status for `.dbt-specify/`, `CLAUDE.md`, `specs/`, model -inventory, and `target/manifest.json`. This is a readiness check, not a dbt model change. +Expected result: doctor reports adoption status for `.dbt-specify/`, `.dbt-specify/agents/`, +`CLAUDE.md`, `specs/`, model inventory, and `target/manifest.json`. This is a readiness check, not +a dbt model change. ## 3. Demo story: semantic customer segmentation diff --git a/docs/methodology.md b/docs/methodology.md index 4c5f37d..90273d0 100644 --- a/docs/methodology.md +++ b/docs/methodology.md @@ -19,6 +19,8 @@ Each phase has a **human checkpoint**. No phase skips, no auto-merge. The spec answers: what problem, who's affected, what's the result, what are the acceptance criteria, what's out of scope, what are the constraints. ACs are EARS-formatted and validatable with `dbt-specify validate`. If the spec describes a staging model, use the `writing-staging-model-specs` skill. For mart-level work, use `writing-mart-specs-with-grain`. For anything involving entities that span systems, also use `writing-business-glossary-specs`. +When a separate worker drafts the spec, use `.dbt-specify/agents/spec-steward.md` as its handoff +contract. ## Phase 2: Plan @@ -29,6 +31,9 @@ If the spec describes a staging model, use the `writing-staging-model-specs` ski The plan enumerates every file that will be added, modified, or deleted; the tests for each AC; the warehouse-specific concerns (clustering, masking, governance, cost guardrails); and the downstream impact (semantic-layer metrics, exposures, reverse-ETL). The warehouse preset's plan additions are appended automatically by `dbt-specify init`. Fill in the warehouse-specific tables before the plan is approved. +Use `.dbt-specify/agents/dbt-architect.md`, `.dbt-specify/agents/warehouse-optimizer.md`, and +`.dbt-specify/agents/governance-reviewer.md` for bounded review of design, warehouse, and policy +questions. ## Phase 3: Tasks @@ -45,11 +50,17 @@ Tasks are ordered by dependency: sources → staging → intermediate → marts **Human checkpoint:** the engineer reviews and approves the final diff before merge. `/dbt.implement` runs one task per invocation. After each task: validate, commit with the task-id message format, and stop. Never work ahead. +If delegated, the implementation worker follows `.dbt-specify/agents/implementation-agent.md` and +may edit only files listed in the approved plan. Before implementation, run `/dbt.analyze` or `dbt-specify validate project` to confirm the lifecycle artifacts are traceable. Before merge, run `/dbt.review`, `dbt parse`, and `dbt-specify validate dbt --manifest target/manifest.json` so the final diff has machine-readable evidence. +Use `.dbt-specify/agents/review-agent.md` when delegating final review. + +See [Skills and sub-agents](skills-and-sub-agents.md) for the difference between reusable skills and +bounded sub-agent roles. ## The retro (not a separate phase, but mandatory) diff --git a/docs/releasing.md b/docs/releasing.md index 61a5b91..7c1c3ad 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -55,9 +55,9 @@ git push origin v1.0.0 The release workflow verifies that the GitHub Release tag matches the `pyproject.toml` version. A release tagged `v1.0.0` must publish package version `1.0.0`; mismatches fail before upload. -## Install after release +## Install from PyPI -Once the first PyPI release is published, users can install from PyPI: +Users can install from PyPI: ```bash uvx --from dbt-spec-kit dbt-specify --version diff --git a/docs/skills-and-sub-agents.md b/docs/skills-and-sub-agents.md new file mode 100644 index 0000000..b639da5 --- /dev/null +++ b/docs/skills-and-sub-agents.md @@ -0,0 +1,104 @@ +# Skills and sub-agents + +dbt-spec-kit composes with +[dbt-labs/dbt-agent-skills](https://github.com/dbt-labs/dbt-agent-skills) instead of copying it. +dbt Labs owns framework-level dbt mechanics. dbt-spec-kit owns the enterprise AI SDLC layer around +business intent, approved plans, task boundaries, governance, warehouse guardrails, and CI evidence. + +## The stack + +| Layer | Owner | Purpose | +|---|---|---| +| dbt framework skills | dbt Labs | How dbt works: commands, tests, docs, semantic layer, Mesh, MCP, migration, troubleshooting | +| Project context | Each dbt team | Naming, layering, CTE, ownership, package, and review conventions in `CLAUDE.md` or future `AGENTS.md` | +| Enterprise skills | dbt-spec-kit | Business meaning, grain, warehouse decisions, governance, traceability, and CI evidence | +| Sub-agent roles | dbt-spec-kit | Handoff protocols for bounded workers with file ownership and output contracts | + +dbt Labs describes its skills as automatically loaded by agents when the prompt matches a use case, +not slash commands. dbt-spec-kit uses slash-command prompts for the SDLC phases and markdown role +templates for delegation. + +## Install dbt Labs skills separately + +For Claude Code, install the dbt Labs marketplace and dbt plugin: + +```text +/plugin marketplace add dbt-labs/dbt-agent-skills +/plugin install dbt@dbt-agent-marketplace +/plugin install dbt-migration@dbt-agent-marketplace +``` + +The `/plugin` commands install the skills. They do not change how skills are invoked during dbt +work: after installation, agents load matching skills from natural-language prompts. + +Use the Vercel Skills CLI: + +```bash +npx skills add dbt-labs/dbt-agent-skills +npx skills add dbt-labs/dbt-agent-skills --skill using-dbt-for-analytics-engineering +``` + +Or use Tessl: + +```bash +tessl install dbt-labs/dbt-agent-skills +tessl install dbt-labs/dbt-agent-skills --skill using-dbt-for-analytics-engineering +``` + +Do not vendor dbt Labs skills into your dbt repo unless your organization has a specific mirroring +policy. Prefer installing them through the supported skill tooling and referencing them from +`CLAUDE.md`. + +## Skill routing + +| dbt Labs skill family | Use during dbt-spec-kit phase | dbt-spec-kit complement | +|---|---|---| +| `using-dbt-for-analytics-engineering` | Plan, implement, review | Enforce approved spec, file list, and project conventions | +| `adding-dbt-unit-test` | Plan, tasks, implement | Map tests to AC ids and CI evidence | +| `building-dbt-semantic-layer` | Specify, plan, review | Capture metric compatibility and downstream impact | +| `working-with-dbt-mesh` | Plan, review | Capture ownership, contracts, exposures, and cross-team impact | +| `running-dbt-commands` | Implement, review, CI | Require validation commands in tasks and reports | +| `fetching-dbt-docs` | Specify, plan, review | Keep dbt framework facts current without weakening local rules | +| Troubleshooting and migration skills | Implement, review | Record findings without silently expanding scope | + +## Skills versus sub-agents + +Skills are reusable knowledge. A skill tells the current agent how to do a category of work better: +write a mart spec with grain, choose a Snowflake clustering key, review PII handling, or check AC +traceability. + +Sub-agents are bounded workers. A sub-agent role says what context to read, which files it may edit, +which files it must not touch, and what output it must return. + +Example: + +```text +Business request + -> spec-steward uses spec-writing and business glossary skills + -> dbt-architect uses dbt Labs skills for framework mechanics + -> warehouse-optimizer uses warehouse-specific dbt-spec-kit skills + -> implementation-agent edits one approved task + -> governance-reviewer checks PII and access + -> review-agent checks AC coverage and CI evidence +``` + +## Installed role templates + +`dbt-specify init` installs these templates into `.dbt-specify/agents/`: + +| Role | Responsibility | +|---|---| +| `spec-steward` | Convert a business request into a reviewed `spec.md` | +| `dbt-architect` | Review model design, lineage, contracts, and dbt Labs skill usage | +| `warehouse-optimizer` | Review warehouse cost, materialization, partitioning, and clustering decisions | +| `implementation-agent` | Implement exactly one approved task and stop | +| `governance-reviewer` | Review PII, access, contracts, ownership, and policy-sensitive changes | +| `review-agent` | Check final diff against ACs, plan, tests, and `dbt-specify report` | + +## Delegation rules + +- Parallelize discovery and review only. +- Serialize implementation by task. +- Never let two agents edit the same dbt model or YAML file concurrently. +- Keep implementation inside the approved plan's file list. +- Human approval remains the merge gate. diff --git a/pyproject.toml b/pyproject.toml index 75f2912..7c2eb07 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "dbt-spec-kit" -version = "1.0.0" +version = "1.1.0" description = "Enterprise AI SDLC toolkit for dbt projects, with spec-driven workflows, CI validation, and warehouse-specific presets." readme = "README.md" license = { file = "LICENSE" } @@ -30,10 +30,12 @@ dependencies = [ [project.optional-dependencies] dev = [ + "build>=1.2", "pytest>=7.0", "pytest-cov>=4.0", "ruff>=0.4", "mypy>=1.10", + "twine>=5.0", "types-PyYAML", ] @@ -54,6 +56,7 @@ packages = ["src/dbt_specify"] "presets" = "dbt_specify/_assets/presets" "skills" = "dbt_specify/_assets/skills" "commands" = "dbt_specify/_assets/commands" +"agents" = "dbt_specify/_assets/agents" [tool.ruff] line-length = 100 diff --git a/skills/capturing-project-conventions/SKILL.md b/skills/capturing-project-conventions/SKILL.md new file mode 100644 index 0000000..31aaac1 --- /dev/null +++ b/skills/capturing-project-conventions/SKILL.md @@ -0,0 +1,34 @@ +--- +name: capturing-project-conventions +description: Use when turning an existing dbt repository's naming, layering, testing, materialization, and review patterns into reusable agent guidance. +--- + +# Capturing project conventions + +## When to use this skill + +Use this during brownfield onboarding, retros, and after reviewers repeatedly correct the same +agent behavior. + +## Discovery routine + +1. Inspect `dbt_project.yml` for model paths, materializations, quoting, dispatch, and vars. +2. Sample staging, intermediate, mart, source, exposure, and metric files. +3. Record naming conventions, CTE structure, test patterns, contracts, tags, owners, and grants. +4. Separate hard rules from examples. Hard rules belong in `CLAUDE.md` or the constitution. +5. Turn repeated review feedback into a focused skill under `.dbt-specify/skills/`. + +## Output + +Return: + +- Rules to add to `CLAUDE.md`. +- Candidate skills to add or update. +- Anti-patterns the agent should avoid. +- Examples from real repo files. + +## Common failures + +- Treating one old model as the standard without checking newer models. +- Capturing business meaning as a project convention instead of a business glossary spec. +- Making guidance too broad for a skill to trigger reliably. diff --git a/skills/reviewing-ac-traceability/SKILL.md b/skills/reviewing-ac-traceability/SKILL.md new file mode 100644 index 0000000..e73ca58 --- /dev/null +++ b/skills/reviewing-ac-traceability/SKILL.md @@ -0,0 +1,33 @@ +--- +name: reviewing-ac-traceability +description: Use when checking that a dbt change traces from acceptance criteria to plan, tasks, code, tests, and review evidence. +--- + +# Reviewing AC traceability + +## When to use this skill + +Use this before implementation, before review, and before attaching PR evidence. + +## Review routine + +1. List every AC id from `spec.md`. +2. Confirm each AC id appears in `plan.md`. +3. Confirm each AC id appears in at least one task in `tasks.md`. +4. Confirm each implemented file maps back to a planned task. +5. Confirm each AC has validation evidence: dbt test, dbt parse, manifest check, SQL review, or + explicit human review. +6. Block review if code exists for an AC that is not in the approved spec. + +## Common failures + +- A task says it supports an AC but no test or review evidence exists. +- A model changed because it was nearby, not because the approved plan listed it. +- A reviewer approves functionality without checking the AC id list. + +## Output + +Return a table: + +| AC id | Plan reference | Task reference | Evidence | Status | +|---|---|---|---|---| diff --git a/skills/reviewing-ci-evidence/SKILL.md b/skills/reviewing-ci-evidence/SKILL.md new file mode 100644 index 0000000..c7a2a13 --- /dev/null +++ b/skills/reviewing-ci-evidence/SKILL.md @@ -0,0 +1,36 @@ +--- +name: reviewing-ci-evidence +description: Use when deciding whether a dbt PR has enough validation evidence to merge after AI-assisted implementation. +--- + +# Reviewing CI evidence + +## When to use this skill + +Use this before final review and before marking a task or PR complete. + +## Minimum evidence + +- `dbt-specify validate project` +- `dbt parse` +- `dbt-specify validate dbt --manifest target/manifest.json` when a manifest exists +- `dbt-specify report --format markdown` +- dbt tests selected for changed models and downstream consumers +- Human sign-off for any untestable AC + +## Review routine + +1. Check that every validation command named in `tasks.md` has a result. +2. Check that failures are fixed, not ignored. +3. Confirm skipped commands have a stated reason and human acceptance. +4. Compare the final report against the AC list. +5. Block merge if lifecycle checks or required dbt tests failed. + +## Output + +Return a merge evidence summary: + +| Evidence | Result | Notes | +|---|---|---| + +End with one recommendation: approve, request changes, or block. diff --git a/skills/reviewing-pii-access-governance/SKILL.md b/skills/reviewing-pii-access-governance/SKILL.md new file mode 100644 index 0000000..e6690e4 --- /dev/null +++ b/skills/reviewing-pii-access-governance/SKILL.md @@ -0,0 +1,33 @@ +--- +name: reviewing-pii-access-governance +description: Use when reviewing dbt specs, plans, or diffs that touch PII, access, grants, contracts, exposures, or governed data products. +--- + +# Reviewing PII, access, and governance + +## When to use this skill + +Use this for any source, model, seed, snapshot, metric, or exposure that includes personal data, +financial data, regulated fields, access policy changes, or cross-team data products. + +## Review routine + +1. Identify sensitive columns and classify them as PII, financial, contractual, operational, or public. +2. Check that masking, policy tags, grants, row filters, or authorized views are declared in the plan. +3. Confirm model contracts preserve stable names and types for governed outputs. +4. Confirm owners and downstream consumers are listed for marts, metrics, and exposures. +5. Confirm retention, deletion, and late-arriving-data policies are explicit when relevant. +6. Block implementation if sensitive data appears in a new mart without an access decision. + +## Required evidence + +- Sensitive fields inventory. +- Access or masking decision. +- Contract impact statement. +- Owner and reviewer sign-off for governed outputs. + +## Common failures + +- Masking in marts instead of the staging boundary. +- Creating a convenience mart with unrestricted PII. +- Changing a semantic-layer field without naming downstream consumers. diff --git a/src/dbt_specify/_version.py b/src/dbt_specify/_version.py index 94112f9..60a5e7b 100644 --- a/src/dbt_specify/_version.py +++ b/src/dbt_specify/_version.py @@ -1,4 +1,4 @@ """Single source of truth for the package version.""" from __future__ import annotations -__version__ = "1.0.0" +__version__ = "1.1.0" diff --git a/src/dbt_specify/doctor.py b/src/dbt_specify/doctor.py index 23c1f1a..292add7 100644 --- a/src/dbt_specify/doctor.py +++ b/src/dbt_specify/doctor.py @@ -39,6 +39,12 @@ def doctor_project(target_dir: Path) -> ValidationReport: "SPECS_DIR_MISSING", "No specs/ directory found. New work will not be traceable.", ), + ( + target_dir / ".dbt-specify" / "agents", + "AGENTS_DIR_MISSING", + "No .dbt-specify/agents/ directory found. Run `dbt-specify init --force` " + "or copy the role templates before delegating sub-agent work.", + ), ( target_dir / "target" / "manifest.json", "MANIFEST_MISSING", diff --git a/src/dbt_specify/init.py b/src/dbt_specify/init.py index 5748751..6096b1b 100644 --- a/src/dbt_specify/init.py +++ b/src/dbt_specify/init.py @@ -102,7 +102,11 @@ def init_project( commands_dst = specify_dir / "commands" shutil.copytree(asset_dir("commands"), commands_dst, ignore=_IGNORE_JUNK) - # 8. Create or suggest CLAUDE.md + # 8. Copy sub-agent role templates + agents_dst = specify_dir / "agents" + shutil.copytree(asset_dir("agents"), agents_dst, ignore=_IGNORE_JUNK) + + # 9. Create or suggest CLAUDE.md claude_template = ( (asset_dir("templates") / "CLAUDE.md.template") .read_text() @@ -122,7 +126,7 @@ def init_project( claude_target.write_text(claude_template) click.echo(f"wrote {claude_target.name}") - # 9. Create empty specs/ directory for the user's first spec + # 10. Create empty specs/ directory for the user's first spec (target_dir / "specs").mkdir(exist_ok=True) (target_dir / "specs" / ".gitkeep").touch() diff --git a/src/dbt_specify/templates_loader.py b/src/dbt_specify/templates_loader.py index 1a6bef9..054cda6 100644 --- a/src/dbt_specify/templates_loader.py +++ b/src/dbt_specify/templates_loader.py @@ -5,7 +5,7 @@ from importlib import resources from pathlib import Path -_KNOWN_ASSETS = {"memory", "templates", "presets", "skills", "commands"} +_KNOWN_ASSETS = {"memory", "templates", "presets", "skills", "commands", "agents"} @cache @@ -19,7 +19,7 @@ def asset_dir(kind: str) -> Path: This is the layout an editable install sees (no copy step happens). Args: - kind: One of "memory", "templates", "presets", "skills", "commands". + kind: One of "memory", "templates", "presets", "skills", "commands", "agents". Returns: Absolute Path to the directory. diff --git a/templates/CLAUDE.md.template b/templates/CLAUDE.md.template index 85de9fa..886b8d1 100644 --- a/templates/CLAUDE.md.template +++ b/templates/CLAUDE.md.template @@ -43,6 +43,21 @@ The non-negotiable principles for this project are in `.dbt-specify/constitution | What does the business actually mean by "customer" / "order" / "session"? | `.dbt-specify/skills/writing-business-glossary-specs/SKILL.md` — fill in your glossary spec | | What are {{ warehouse }}-specific patterns we follow here? | `.dbt-specify/constitution.md` (BEGIN {{ warehouse }} ADDITIONS section) | +## Skill routing + +- Use `dbt-labs/dbt-agent-skills` for dbt framework mechanics: dbt commands, tests, docs, semantic layer, Mesh, MCP, troubleshooting, and migration. +- Use `.dbt-specify/skills/` for business meaning, grain, project conventions, warehouse decisions, governance, traceability, and CI evidence. +- Use `.dbt-specify/agents/` when delegating bounded work to sub-agents. +- Do not copy or rewrite dbt Labs skills into this repo. Reference them as the framework layer. + +## Sub-agent safety rules + +- Parallelize discovery and review only. +- Serialize implementation by task. +- Never let two agents edit the same dbt model or YAML file concurrently. +- Keep implementation inside the approved plan's file list. +- Human approval remains the merge gate. + ## Conventions specific to this project