Imported from yu-iskw/dbt-tools-ts (
AGENTS.md). Install upstream withnpx skills add yu-iskw/dbt-tools-ts. Copyright stays with the author.
Agent instructions (dbt-tools-ts)
Agent documentation split
- This file (
AGENTS.md) is canonical for humans and all agent tools: stack, package layout, quality gates, commands, and policy detail. CLAUDE.mdis a Claude Code entry digest that points back here and adds Claude-specific coordination notes.- If anything disagrees, this file wins; update this file first, then adjust shorter mirrors such as
CLAUDE.mdor.cursor/rules/*.mdc.
Tech stack
- Package manager: pnpm workspace.
- Node.js: use
.node-versionfor local development and CI. Published packages require Node.js 20+. - Language: TypeScript. Unit tests use Vitest from the repository root (per-package
vitest.config.tsprojects; coverage and global thresholds only in rootvitest.config.ts). - Repository boundary: this repo owns
@dbt-tools/core,@dbt-tools/cli,@dbt-tools/mcp, and@dbt-tools/web.dbt-artifacts-parseris an external npm dependency and upstream parser package, not a workspace package here.
Packages
| Package | Path | Role |
|---|---|---|
@dbt-tools/core |
packages/core |
Artifact analysis substrate: manifest graph, execution analysis, snapshots, discovery, exports, and browser-safe facade. |
@dbt-tools/cli |
packages/cli |
Structured CLI for operators, CI, scripts, and coding agents (dbt-tools). |
@dbt-tools/mcp |
packages/mcp |
Long-lived MCP server for interactive agent workflows over resident parsed artifacts (dbt-tools-mcp). |
@dbt-tools/web |
packages/web |
Deterministic investigation UI and local static server (dbt-tools-web). |
Product positioning is ADR-0008. Core/web/CLI scalability boundaries are ADR-0003, ADR-0004, ADR-0006, and ADR-0010.
Frontend application
@dbt-tools/webis an artifact-driven investigation UI; it must remain useful without a chat surface or LLM dependency.- Web app code lives in
packages/web/src; Playwright specs live inpackages/web/e2e. - Use
@dbt-tools/core/browserin workers and code that must avoid Node built-ins. Use the full@dbt-tools/coreentry for Vite/Node-only code such as artifact-source middleware and server-side CLI wiring. - Path alias
@webmaps topackages/web/src; keep package and root Vitest/Vite aliases in sync when it changes.
Design tokens and styling
- Token source of truth:
packages/web/src/styles/tokens.css. - TypeScript mirror:
packages/web/src/constants/theme-colors.generated.tsis generated bypnpm tokens:sync; never edit it manually. - New CSS should use semantic
var(--*)tokens for colors, spacing, typography, and radii. See.cursor/rules/design-tokens.mdc. - Run
pnpm lint:stylelintafter substantive CSS changes;pnpm lint:reportis ESLint-only.
Unit test and coverage configuration
- Global thresholds:
coverage-thresholds.mjs— lines 60%, branches 50%, functions 60%, statements 60%. - Workspace mins:
packages/*/coverage.policy.ts— per-package floors merged at root. - Shared aliases / pool:
vitest.shared.ts. - Coverage provider and reporters: root
vitest.config.tsonly (Vitest projects do not supportcoveragein package configs). - Agent harness:
pnpm coverage:reportrunsvitest.coverage.tsand writescoverage-report.json.
Quality gates
Unless the user explicitly narrows scope, run the relevant gates from the repository root before claiming completion:
Root eslint.config.mjs layers eslint-plugin-security (code patterns) on top of Trunk security scanners (Trivy/OSV). See pnpm lint:security for dependency/CVE scope. Dynamic filesystem paths must go through packages/core/src/io/safe-fs.ts (resolveSafePath first); packaged fixture reads use packages/test-fixtures/dbt-artifacts-parser/test-utils.ts. pnpm lint:trunk-all expects zero eslint/security/* findings—use Map / typed-map.ts helpers instead of dynamic object indexing elsewhere.
pnpm testfor Vitest.pnpm lint:reportandpnpm knip.pnpm coverage:report.- Full
pnpm lintor scoped Trunk when touching Markdown, YAML,.trunk/, GitHub workflow files, or substantive CSS. pnpm buildwhen the change spans package exports, shared TypeScript, worker protocol, package manifests, or publish-shaped behavior.pnpm test:e2ewhen changingpackages/web/e2e/or material web journeys.pnpm verify:pluginswhen changingplugins/**,.agents/plugins/**,.cursor-plugin/**, or.claude/skills/dbt-tools-cli-plugin-skill/**.
For documentation-only and agent-resource edits, the default repo policy still expects pnpm lint:report, pnpm knip, and pnpm coverage:report; a user may explicitly narrow verification for migration or review work. Cursor mirror: .cursor/rules/coverage-and-lint-reports.mdc.
Commands
pnpm install # respects root .npmrc ignore-scripts=true; pnpm-workspace minimumReleaseAge
pnpm build
pnpm test
pnpm lint:report
pnpm coverage:report
pnpm knip
pnpm verify:plugins
pnpm dev:web
pnpm test:e2e
pnpm --filter @dbt-tools/web build
Pack and npx smoke for the web package is documented in .claude/skills/dbt-tools-web-pack-npx-smoke/SKILL.md.
Agent resources
- CLI plugin authoring:
.claude/skills/dbt-tools-cli-plugin-skill/SKILL.md. - Agent plugins (primitive skills):
plugins/dbt-tools-cli/README.md,plugins/dbt-tools-mcp/README.md. - E2E authoring:
.claude/skills/dbt-tools-web-e2e/SKILL.md. - E2E fix loop:
.claude/skills/dbt-tools-web-e2e-fix/SKILL.md. - UI-scope verification:
.claude/skills/ui-feature-verify/SKILL.md. - Workspace package version bump (release semver sync):
.claude/skills/bump-workspace-versions/SKILL.md. - Full verification prompt:
.claude/agents/verifier.md.
Documentation boundaries
- Parser schema generation, parser package publishing, and parser-only development guidance belong in the external
dbt-artifacts-parserrepository. Keep only the context needed to explain that@dbt-tools/*depends on the published parser package. - ADRs should describe durable decisions and invariants, not volatile file inventories or generated tables. Operational details belong in this file, package READMEs, code, and tests.
- Do not edit GitHub workflow files unless the task explicitly owns CI.
Secrets and suppressions
Do not commit API keys, tokens, or passwords into docs, prompts, rules, or tracked config. Reference environment variable names only. Fix lint/static-analysis findings at the root cause; inline suppressions are a last resort and must be narrow and justified.
Learned User Preferences
- Prefer simple, minimal scope in plans and implementations; avoid over-engineering when the user asks to keep work simple.
- Do not create git commits or open/update pull requests unless the user explicitly asks.
- On follow-up code or security reviews, describe only remaining issues—do not rehash fixes already applied.
- For large design questions, use structured problem-solving (intent, alternatives, scored recommendation) before implementation when the user invokes that workflow.
- CLI and MCP surfaces should use warehouse-specific filter and sort shapes, not flat option bags that mix conditions across warehouses.
- Prefer
dbt-tools-mcpfor long, multi-step agent work over large artifacts; preferdbt-tools-clifor one-shot shell/CI or manifest-only readiness beforerun_results.jsonexists. - For
docs/site/, prefer task-oriented workflows and recipes (jobs users complete) over mirroring package READMEs; keep full CLI/MCP flag reference inpackages/*/README.mdwith deliberate links from the site. - When growing the published docs, add a Workflows hub and shallow per-surface tours before package-first reference dumps; expand
guide/agents/for plugins/skills rather than folding agent docs into MCP pages. - GitHub Pages (
docs/site/) is for end users of CLI/MCP/Web/plugins—do not link to ADRs there; keep ADRs indocs/adr/for contributors and agents. - End-user docs use “coding agent” and “agent skills” wording; avoid generic “AI agent” phrasing on the published site.
Learned Workspace Facts
docs/adr/is the only canonical ADR corpus; agents should read ADRs there directly rather than relying on the published site alone.docs/architecture/holds non-ADR explanatory history; do not create new ADRs outsidedocs/adr/.docs/site/is the VitePress end-user docs (@dbt-tools/site, base/dbt-tools-ts/): sidebar Start Here, Foundations (guide/foundations/new-to-dbt, expandedconcepts/dbt-artifacts), Concepts (local/remote artifacts, discovery parity, operational intelligence), per-surface CLI / Web / MCP / Agents guides with nested Workflows, and Reference (configuration env tables, CLI cheatsheet, MCP tools, deep links); documents CLI, MCP, Web, and agent plugins—not@dbt-tools/core. Build withpnpm site:build/pnpm site:dev; deploy via.github/workflows/pages.yml; separate fromdocs/adr/.- Do not ship demo artifact bundles (
demo-artifacts.zip) or hand-crafted fixture JSON from this repo; users without a project should generate real artifacts via public sample repos—default jaffle_shop_duckdb (local DuckDB), optional jaffle-shop when a warehouse profile exists—documented atdocs/site/guide/try-with-sample-project.md(redirect from/guide/demo-artifacts). - Remote artifacts do not use
DBT_TOOLS_REMOTE_SOURCE(removed); use--dbt-target/DBT_TOOLS_DBT_TARGETwiths3://orgs://URIs, granularDBT_TOOLS_*remote env vars, and the web Load artifacts UI for server-mediated buckets—seedocs/site/concepts/local-and-remote-artifacts.md. - Keep
@dbt-tools/mcppackage README isolated: do not add cross-links to CLI or web package docs from the MCP README. - Execution search APIs (CLI/MCP) should align with per-adapter response schemas in
packages/corerather than mixing warehouse metrics in one shared options type. - VitePress in this monorepo needs
vite.esbuild,vite.build, andoptimizeDeps.esbuildOptionsall set toesnextindocs/site/.vitepress/config.tsorpnpm site:devfails on legacy browser downlevel targets. - First-party plugins (
plugins/dbt-tools-cli,plugins/dbt-tools-mcp) ship eight primitive skills with identical folder/YAML names (bind-targetthroughsummarize-run); compose workflows from handles likedbt-tools-cli:bind-target, not monolithic workflow skills. PluginSKILL.mdfiles hold the stable contract;references/implementation.mdmaps to current CLI subcommands or MCP tools when surfaces change. - Bundled
plugins/dbt-tools-mcp/mcp.jsonis spawn-only (npx -y @dbt-tools/mcp); per-session artifact roots usedbt_tools_set_target, notDBT_TOOLS_*env in the plugin bundle. @dbt-tools/mcploadsmanifest.jsonandrun_results.jsontogether; there is no manifest-only MCP session—use CLIcheck-sessionfor manifest-only readiness.- MCP
ArtifactWorkspacekeeps up to three parsed artifact roots in memory by default (DBT_TOOLS_MAX_CACHED_TARGETS,--max-cached-targets; 0 disables). Tools:dbt_tools_unset_target,dbt_tools_clear_cached_targets; optional idle eviction viaDBT_TOOLS_CACHE_TTL_MS/--cache-ttl-ms. Background poll anddbt_tools_refreshonly touch the active target. - Local CodeQL analysis: run
dev/codeql.shfrom the repo root (see.claude/skills/codeql-fix/SKILL.md).
