feat: consolidate dbt skills and add altimate-dbt CLI package by suryaiyer95 · Pull Request #201 · AltimateAI/altimate-code

suryaiyer95 · 2026-03-16T23:09:34Z

What does this PR do?

Consolidates 8 scattered dbt skills into 5 focused, well-structured skills with a references/ system for modular knowledge. Adds a standalone altimate-dbt CLI package for dbt project operations. Rewrites the builder prompt with a skills-first architecture and leaner token footprint.

Type of change

New feature (non-breaking change which adds functionality)
Refactoring (no functional changes, no API changes)

Changes

Skills consolidation (8 → 5):

New: dbt-analyze, dbt-develop, dbt-docs, dbt-test, dbt-troubleshoot
Each skill has a references/ directory with modular knowledge docs (altimate-dbt commands, patterns, error guides)
Removed: generate-tests, impact-analysis, incremental-logic, medallion-patterns, model-scaffold, yaml-config

New packages/dbt-tools package:

Standalone altimate-dbt CLI for dbt project operations
Commands: build, compile, deps, columns, graph, init, doctor
Bundles altimate_python_packages for Python bridge integration

Builder prompt rewrite:

Skills-first architecture surfacing altimate_core tools
Leaner token footprint — removed unused sections to save event budget

Other:

python-bridge@1.1.0 patch for packaging fix

How did you verify your code works?

TypeScript typecheck passes (bun turbo typecheck — all 5 packages clean)
altimate-dbt CLI boots and resolves commands
Consolidated skills load correctly in opencode skill registry

Checklist

My code follows the style guidelines of this project
I have performed a self-review of my own code
Tests added/updated
Documentation updated (if needed)

🤖 Generated with Claude Code

claude · 2026-03-16T23:09:37Z

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review.

Copilot

Pull request overview

This PR introduces a new altimate-dbt CLI package for dbt operations and updates the Altimate builder guidance/tooling to prefer that CLI over the existing raw dbt_run tool, alongside a dependency patch for python-bridge to improve runtime compatibility.

Changes:

Add packages/dbt-tools (CLI + adapter) exposing altimate-dbt commands like init, doctor, compile, build, execute, and DAG helpers.
Remove dbt_run tool exposure from the opencode tool registry / barrel exports, and update prompts/docs to steer usage toward altimate-dbt.
Add a python-bridge@1.1.0 patch and wire it via patchedDependencies.

Reviewed changes

Copilot reviewed 53 out of 55 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
patches/python-bridge@1.1.0.patch	Patch `python-bridge` to stop promisifying `child_process`.
packages/opencode/src/tool/registry.ts	Removes `DbtRunTool` from tool registration.
packages/opencode/src/altimate/tools/dbt-run.ts	Updates tool description to position it as fallback vs `altimate-dbt`.
packages/opencode/src/altimate/prompts/builder.txt	Rewrites builder prompt to mandate `altimate-dbt` workflows.
packages/opencode/src/altimate/index.ts	Stops exporting `dbt-run` tool from barrel.
packages/dbt-tools/tsconfig.json	New strict TS config for the CLI package.
packages/dbt-tools/test/config.test.ts	Adds initial config tests (currently not exercising module behavior).
packages/dbt-tools/test/cli.test.ts	Adds CLI smoke tests via `bun spawnSync`.
packages/dbt-tools/src/index.ts	Implements CLI entrypoint/dispatch, output formatting, diagnostics.
packages/dbt-tools/src/config.ts	Adds HOME-based config read/write for `~/.altimate-code/dbt.json`.
packages/dbt-tools/src/commands/init.ts	Adds `init` command with project + python auto-detection.
packages/dbt-tools/src/commands/info.ts	Adds `info` command wrapper.
packages/dbt-tools/src/commands/graph.ts	Adds `children`/`parents` command wrappers.
packages/dbt-tools/src/commands/execute.ts	Adds `execute` command with optional `--limit`.
packages/dbt-tools/src/commands/doctor.ts	Adds `doctor` command (prereq checks summary).
packages/dbt-tools/src/commands/deps.ts	Adds `deps` / `add-packages` commands.
packages/dbt-tools/src/commands/compile.ts	Adds `compile` / `compile-query` commands.
packages/dbt-tools/src/commands/columns.ts	Adds model/source columns + column-values commands.
packages/dbt-tools/src/commands/build.ts	Adds `build`, `run`, `test`, and `build-project` commands.
packages/dbt-tools/src/check.ts	Adds prereq validation logic (python/dbt/project).
packages/dbt-tools/src/adapter.ts	Creates `DBTProjectIntegrationAdapter` wired for local execution.
packages/dbt-tools/script/copy-python.ts	Copies bundled Python packages into `dist/`.
packages/dbt-tools/package.json	Defines the `altimate-dbt` bin + build/test scripts.
packages/dbt-tools/bin/altimate-dbt	Node shebang launcher importing built dist entrypoint.
package.json	Adds `packages/dbt-tools` workspace and patched dependency for `python-bridge`.
bun.lock	Locks new workspace package + patched dependency entries.
.opencode/skills/yaml-config/SKILL.md	Removes old skill doc.
.opencode/skills/model-scaffold/SKILL.md	Removes old skill doc.
.opencode/skills/medallion-patterns/SKILL.md	Removes old skill doc.
.opencode/skills/incremental-logic/SKILL.md	Removes old skill doc.
.opencode/skills/impact-analysis/SKILL.md	Removes old skill doc.
.opencode/skills/generate-tests/SKILL.md	Removes old skill doc.
.opencode/skills/dbt-troubleshoot/SKILL.md	Adds new troubleshooting skill centered on `altimate-dbt`.
.opencode/skills/dbt-troubleshoot/references/test-failures.md	Adds troubleshooting reference (tests).
.opencode/skills/dbt-troubleshoot/references/runtime-errors.md	Adds troubleshooting reference (runtime errors).
.opencode/skills/dbt-troubleshoot/references/compilation-errors.md	Adds troubleshooting reference (compile errors).
.opencode/skills/dbt-troubleshoot/references/altimate-dbt-commands.md	Adds CLI command reference.
.opencode/skills/dbt-test/SKILL.md	Adds new dbt testing skill doc.
.opencode/skills/dbt-test/references/unit-test-guide.md	Adds dbt unit test guidance.
.opencode/skills/dbt-test/references/schema-test-patterns.md	Adds schema-test patterns reference.
.opencode/skills/dbt-test/references/custom-tests.md	Adds custom tests reference.
.opencode/skills/dbt-test/references/altimate-dbt-commands.md	Adds CLI command reference (duplicated for skill).
.opencode/skills/dbt-docs/SKILL.md	Updates docs skill to use `altimate-dbt` and new standards.
.opencode/skills/dbt-docs/references/documentation-standards.md	Adds documentation standards reference.
.opencode/skills/dbt-docs/references/altimate-dbt-commands.md	Adds CLI command reference (for docs skill).
.opencode/skills/dbt-develop/SKILL.md	Adds dbt development skill doc.
.opencode/skills/dbt-develop/references/yaml-generation.md	Adds YAML generation reference.
.opencode/skills/dbt-develop/references/medallion-architecture.md	Adds medallion architecture reference.
.opencode/skills/dbt-develop/references/layer-patterns.md	Adds dbt layering reference.
.opencode/skills/dbt-develop/references/incremental-strategies.md	Adds incremental strategies reference.
.opencode/skills/dbt-develop/references/common-mistakes.md	Adds common mistakes reference.
.opencode/skills/dbt-develop/references/altimate-dbt-commands.md	Adds CLI command reference (for develop skill).
.opencode/skills/dbt-analyze/SKILL.md	Adds dbt impact analysis skill doc.
.opencode/skills/dbt-analyze/references/lineage-interpretation.md	Adds lineage interpretation reference.
.opencode/skills/dbt-analyze/references/altimate-dbt-commands.md	Adds CLI command reference (for analyze skill).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

suryaiyer95 · 2026-03-16T23:28:19Z

Note on `patches/python-bridge@1.1.0.patch`

What it does: Removes bluebird's promisifyAll from python-bridge's child_process require — a Bun compatibility fix.

Dependency chain:@altimateai/dbt-integration → python-bridge@^1.1.0 → bluebird. The promisifyAll monkey-patching breaks under Bun's runtime.

How it's applied: Via Bun's patchedDependencies in root package.json — applied automatically on bun install.

Risks:

Bun-only — npm/yarn installs won't apply the patch. Fine for this monorepo (Bun-based, dbt-tools is private: true), but won't survive if dbt-tools is ever distributed as a standalone npm package.
Version-pinned — If python-bridge updates past 1.1.0, the patch reference breaks silently.

Worth considering a more robust solution longer-term (e.g., fork python-bridge, or upstream a fix to @altimateai/dbt-integration to drop the bluebird dependency).

github-actions · 2026-03-17T02:49:05Z

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

dev-punia-altimate · 2026-03-17T16:36:49Z

✅ Tests — All Passed

TypeScript — passed

Python — passed

_{Tested at 40399d04 | Run log | Powered by QA Autopilot}

- New `@altimateai/dbt-tools` package with `altimate-dbt` CLI binary - Commands: init, doctor, compile, build, run, test, execute, columns, graph, deps - Auto-detects dbt project, Python environment, and adapter type - Friendly error diagnostics with actionable fix suggestions - Consolidate 6 old skills into 5 reference-backed skills: dbt-develop, dbt-test, dbt-docs, dbt-troubleshoot, dbt-analyze - Update builder prompt to prefer `altimate-dbt` CLI over raw `dbt_run` tool - Remove orphaned `dbt-run.ts` tool file and unused `python-bridge` patch - Fix missing `await` on `children`/`parents` graph commands - Fix `--limit 0` to correctly support schema inspection - Wrap `adapter.dispose()` in try-catch to prevent masking command errors - Skip stub config tests pending rewrite Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

suryaiyer95 · 2026-03-17T16:50:49Z

Note on patches/python-bridge@1.1.0.patch
What it does: Removes bluebird's promisifyAll from python-bridge's child_process require — a Bun compatibility fix.
Dependency chain:@altimateai/dbt-integration → python-bridge@^1.1.0 → bluebird. The promisifyAll monkey-patching breaks under Bun's runtime.
How it's applied: Via Bun's patchedDependencies in root package.json — applied automatically on bun install.
Risks:
Bun-only — npm/yarn installs won't apply the patch. Fine for this monorepo (Bun-based, dbt-tools is private: true), but won't survive if dbt-tools is ever distributed as a standalone npm package.
Version-pinned — If python-bridge updates past 1.1.0, the patch reference breaks silently.
Worth considering a more robust solution longer-term (e.g., fork python-bridge, or upstream a fix to @altimateai/dbt-integration to drop the bluebird dependency).

Discussed with Michiel and this is safe to remove. We have removed it

…bt` works in published releases `bun build` replaces `__dirname` with a compile-time constant when bundling `python-bridge` (transitive dep of `@altimateai/dbt-integration`). In CI this bakes `/home/runner/work/...` into the bundle, causing `altimate-dbt build` and all Python-bridge commands to fail with ENOENT on every user's machine. Fix: - Copy `node_python_bridge.py` into `dist/` alongside `index.js` - Post-process the bundle to replace the frozen path with `import.meta.dirname` - Fail the build if the patch pattern isn't found (safety net) - Add CI smoke test to prevent regression Broken since PR #201. Closes#466. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… binary (#467) * fix: patch hardcoded `__dirname` in `dbt-tools` bundle so `altimate-dbt` works in published releases `bun build` replaces `__dirname` with a compile-time constant when bundling `python-bridge` (transitive dep of `@altimateai/dbt-integration`). In CI this bakes `/home/runner/work/...` into the bundle, causing `altimate-dbt build` and all Python-bridge commands to fail with ENOENT on every user's machine. Fix: - Copy `node_python_bridge.py` into `dist/` alongside `index.js` - Post-process the bundle to replace the frozen path with `import.meta.dirname` - Fail the build if the patch pattern isn't found (safety net) - Add CI smoke test to prevent regression Broken since PR #201. Closes#466. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: address PR review — add Node 18 fallback and broaden path assertions - Use `fileURLToPath(import.meta.url)` fallback for Node < 20.11.0 - Broaden smoke test and build integrity checks to catch any hardcoded absolute path (Unix + Windows), not just `home/runner` * fix: drop Node 18 fallback — `path` is not in scope before `__dirname` in bundle GLM-5 review correctly identified that `path` is defined AFTER `__dirname` in the bundled output, so the `path.dirname(fileURLToPath(...))` fallback would throw `ReferenceError` on Node < 20.11.0. Since Node 18 is EOL (April 2025), use `import.meta.dirname` unconditionally. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: copy `node_python_bridge.py` in `publish.ts` so npm tarball includes it `copyAssets` copied `dbt-tools/dist/index.js` but not the `.py` file the patched `__dirname` resolves to. Without this, the fix would still break in published packages. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: spread real `child_process` in `mock.module` to prevent `execFileSync` leak `mock.module("child_process")` in `dbt-cli.test.ts` only provided `execFile`, causing `dbt-resolve.test.ts` to fail with `Export named 'execFileSync' not found` when Bun leaks the mock across test files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: use __require fallback for __dirname to support Node < 20.11.0 `import.meta.dirname` is unavailable before Node 20.11.0. The previous fallback was dropped because `path`/`fileURLToPath` weren't in scope at that point in the bun-generated __commonJS IIFE. Using `__require` (a module-level closure bun always emits) works at any Node version. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * style: format `dbt-cli.test.ts` and `publish.ts` with Prettier Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: add adversarial tests for `__dirname` patch and build integrity 22 tests covering regex edge cases, runtime resolution, idempotency, CI smoke test parity, and built bundle invariants. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: address code review — existence check, comment fix, better diagnostics - Add `existsSync` check before copying `node_python_bridge.py` with a clear error message if the file is missing from the dependency - Fix misleading comment that said "no fallback needed" while fallback code existed — now accurately describes the `__require` fallback - Log the nearest `__dirname` match on pattern mismatch to aid debugging Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * test: expand adversarial tests to 43 cases covering runtime, publish, and mutation New test categories: - Script execution: verify exit codes, progress output, build determinism - Bundle runtime structure: `__require` origin, `__commonJS` scope, spawn chain - Publish pipeline: patched artifacts integrity before copy - Mutation testing: verify guards catch removal of key fix components - Regex performance: no catastrophic backtracking on 100KB+ input - Malformed inputs: unicode, spaces, special chars, surrounding code preservation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: eliminate flaky CI test failures in dispatcher, dbt, and tracer tests Root causes: - `dispatcher.test.ts`: Bun's multi-file runner leaks `_ensureRegistered` hook from other files' `native/index.ts` imports. `reset()` clears handlers but not the hook, so `call()` triggers lazy registration instead of throwing. Fix: clear hook in `beforeEach`. - `dbt-first-execution.test.ts`: `mock.module` for DuckDB leaked across files. Fix: spread real module exports + ensure native/index.ts import. - `tracing-adversarial-final.test.ts`: 50ms snapshot waits too tight for CI under load. Fix: increase to 200ms/300ms. Result: 0 failures in full suite (4961 pass, 340 skip). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: replace environment-coupled `runner` assertion with directory existence check Address CodeRabbit review: `expect(dirname).not.toContain("runner")` would fail on GitHub CI where test runs under `/home/runner/`. Use `existsSync(dirname)` to validate the directory is real instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Michiel De Smet <mdesmet@gmail.com> Co-authored-by: anandgupta42 <anand@altimate.ai> Co-authored-by: anandgupta42 <93243293+anandgupta42@users.noreply.github.com>

CopilotAI review requested due to automatic review settings March 16, 2026 23:09

github-actionsBot added the contributor label Mar 16, 2026

Copilotstarted reviewing on behalf of suryaiyer95 March 16, 2026 23:10 View session

sentryBot reviewed Mar 16, 2026
View reviewed changes

Comment threadpackages/dbt-tools/src/index.ts Outdated

CopilotAI reviewed Mar 16, 2026
View reviewed changes

Comment threadpackages/dbt-tools/src/commands/execute.ts
Comment threadpackages/dbt-tools/test/config.test.ts
Comment threadpackages/dbt-tools/test/config.test.ts
Comment threadpackages/dbt-tools/src/commands/init.ts
Comment threadpackages/dbt-tools/src/commands/init.ts

sentryBot reviewed Mar 16, 2026
View reviewed changes

Comment threadpackages/dbt-tools/src/index.ts

anandgupta42 force-pushed the main branch from c86970e to d097682Compare March 17, 2026 00:40

suryaiyer95 force-pushed the feat/builder-prompt-dbt-skills branch from c52e6a1 to 2da80e7Compare March 17, 2026 02:48

github-actionsBot added the needs:compliance label Mar 17, 2026