Add skills and sub-agent architecture

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.

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)

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/<NNN>-<slug>/plan-review.md`
+- `specs/<NNN>-<slug>/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.

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/<NNN>-<slug>/governance-review.md`
+- `specs/<NNN>-<slug>/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.

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/<NNN>-<slug>/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.

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/<NNN>-<slug>/review.md`
+- `specs/<NNN>-<slug>/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.

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/<NNN>-<slug>/spec.md`
+- `specs/<NNN>-<slug>/questions.md`
+- `specs/<NNN>-<slug>/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/<NNN>-<slug>/spec.md` evidence.

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/<NNN>-<slug>/warehouse-review.md`
+- `specs/<NNN>-<slug>/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.

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

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`.

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.

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
 

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)
 

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