feat: consolidate dbt skills and add altimate-dbt CLI package

[suryaiyer95]

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]

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]

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]

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]

✅ Tests — All Passed

TypeScript — passed

Python — passed

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

[suryaiyer95]

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