feat: add altimate-dbt CLI and consolidate dbt skills into 5 focused skills

[suryaiyer95]

Summary

• Adds altimate-dbt CLI package (packages/dbt-tools/) — a Bun TypeScript wrapper around @altimateai/dbt-integration for dbt project operations
• Consolidates 8 scattered dbt skills into 5 focused skills with references/ directories for progressive context disclosure
• All skills now use altimate-dbt commands instead of raw dbt

altimate-dbt CLI (packages/dbt-tools/)

New package providing 16 commands for dbt project operations:

Command	Purpose
init	Auto-detect dbt project, write config
doctor	Validate project health
info	Project metadata
compile / compile-query	Jinja compilation
build / run / test / build-project	Model execution
execute	SQL execution against warehouse
columns / columns-source / column-values	Column introspection
children / parents	DAG navigation
deps / add-packages	Package management

Architecture: one-shot CLI (run command → print JSON → exit). No MCP, no server, no API key required. Wraps @altimateai/dbt-integration via DBTProjectIntegrationAdapter.

dbt Skills Consolidation

New Skill	Purpose	References	Replaces
dbt-develop	Model creation hub	6 refs	model-scaffold, yaml-config, medallion-patterns, incremental-logic, dbt-cli
dbt-test	Schema + unit + custom tests	4 refs	generate-tests
dbt-docs	Model documentation	2 refs	(enhanced)
dbt-troubleshoot	Error diagnosis workflow	4 refs	(new)
dbt-analyze	Downstream impact analysis	2 refs	impact-analysis

Deleted: dbt-cli, model-scaffold, generate-tests, yaml-config, incremental-logic, medallion-patterns, impact-analysis

Architecture: Lean SKILL.md for AI routing → deep references/ files loaded on-demand. Adopts patterns from dbt-labs/dbt-agent-skills: Iron Rules, Common Mistakes tables, explicit boundaries.

Test plan

• bun packages/dbt-tools/src/index.ts prints usage
• bun packages/dbt-tools/src/index.ts init detects dbt project
• bun test --cwd packages/dbt-tools passes
• Skills activate for correct prompt types
• Deleted skills no longer appear in skill list
• Spider2-DBT benchmark tasks for end-to-end validation

🤖 Generated with Claude Code

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

[sentry]

Bug: The children and parents commands are not awaited in index.ts. This causes them to return an unresolved Promise instead of the expected lineage data.
_{Severity: CRITICAL}

Suggested Fix

Add the await keyword to the children and parents command calls within the switch statement in index.ts. Also, ensure the children() and parents() functions in graph.ts are marked as async to correctly handle the Promises returned by the adapter methods.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: packages/dbt-tools/src/index.ts#L156-L161

Potential issue: In `index.ts`, the `switch` statement handling CLI commands is missing
the `await` keyword for the `children` and `parents` cases. The corresponding functions
in `graph.ts` return Promises from adapter calls. Because these Promises are not
awaited, they are passed directly to `JSON.stringify()`, which serializes them to an
empty object `"{}"`. This breaks the lineage analysis feature, causing the commands to
return no data. Additionally, this creates a race condition where `adapter.dispose()`
may be called before the async operation completes.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[dev-punia-altimate]

🤖 Behavioral Analysis — 2 Finding(s)

🟡 Warnings (2)

• F1 packages/dbt-tools/src/commands/execute.ts:9 [Silent logic error — limit flag ignored for 0 and NaN]
  The limit check if (limit) is falsy for both 0 and NaN. When a user passes --limit 0, parseInt returns 0 (falsy), so the code silently falls through to adapter.immediatelyExecuteSQL (no limit) instead of immediatelyExecuteSQLWithLimit. The user gets ALL rows when they expected zero. --limit abc gives NaN (also falsy), also silently ignoring the flag. --limit -5 is truthy and passes a negative limit to the adapter with undefined behavior. Evidence: execute.ts lines 7-10: const raw = flag(args, 'limit'); const limit = raw ? parseInt(raw, 10) : undefined; if (limit) return adapter.immediatelyExecuteSQLWithLimit(sql, model, limit); return adapter.immediatelyExecuteSQL(sql, model);

• F2 packages/dbt-tools/src/config.ts:14 [Unhandled JSON.parse exception on corrupted config gives confusing error]
  read() does return JSON.parse(raw) as Config with no try-catch. If ~/.altimate-code/dbt.json exists but contains malformed JSON, JSON.parse throws a SyntaxError. The caller in index.ts also has no try-catch (const cfg = await read()), so the error propagates to main().catch(bail). bail() hits the diagnose() fallthrough: return { error: msg, fix: 'Run: altimate-dbt doctor' }, printing the raw SyntaxError message (e.g. 'Unexpected token } in JSON at position 42'). The user has no indication the config is corrupted and no hint to re-run altimate-dbt init. Evidence: config.ts line 14 — return JSON.parse(raw) as Config. index.ts caller — const cfg = await read() with no surrounding try-catch.

_{Analysis run | Powered by QA Autopilot}

[dev-punia-altimate]

✅ Tests — All Passed

TypeScript — passed

Python — passed

_{Tested at 83733d3e | Run log | Powered by QA Autopilot}