feat: skill follow-up suggestions to improve dbt experience (#546)

* feat(dbt-tools): build entire project when no --model flag given

`altimate-dbt build` without arguments now builds the whole project via
`unsafeBuildProjectImmediately`, replacing the need for the separate
`build-project` command. Updated all dbt skill references accordingly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(dbt-tools): add unit tests for build command routing

Covers: no-model → project build, --model → single model, --downstream flag.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: address code review — remove `build-project` command, update help text, add stderr test

- Remove `build-project` from command map and switch case in `index.ts`
  (now redundant since `build` without `--model` does the same thing)
- Update `build` help text to reflect optional `--model`
- Remove unused `project` import from `build.test.ts`
- Add test for `format()` stderr error path
- Fix comment alignment in all 5 `altimate-dbt-commands.md` reference files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: add missing `fullOutput` field to satisfy `CommandProcessResult` type

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add follow-up suggestions after skill completion to reduce first-run churn

Telemetry analysis showed 78% of users churn after a single 2.4-minute session,
mostly dbt developers who run one skill and leave. Users who reach warehouse/schema
tools retain at 24.8% vs 3.3% for those who don't.

This adds contextual "What's Next?" suggestions after skill execution:
- Maps each skill to relevant follow-up skills (e.g., `dbt-develop` → `dbt-test`, `dbt-docs`)
- Includes a warehouse discovery nudge to bridge non-warehouse users
- Appended after `</skill_content>` so it doesn't interfere with skill parsing
- Covers all dbt skills, SQL skills, and data quality skills (12 skills total)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address code review — truncation-safe followups, telemetry, immutable `get()`

- Move follow-up suggestions before `<skill_content>` so they survive output truncation
- Add `has_followups` and `followup_count` to `skill_used` telemetry event
- Return `readonly Suggestion[]` via `Object.freeze()` from `get()` to prevent shared state mutation
- Rewrite integration tests to verify followups appear before `<skill_content>` in output assembly
- Wrap custom return block in `altimate_change` markers for upstream safety

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add e2e tests for skill follow-up suggestions via `SkillTool.execute`

- Test that `dbt-develop` skill output includes follow-ups before `<skill_content>`
- Test that unmapped skills produce no follow-up section
- Both tests invoke the real `SkillTool.execute` path end-to-end

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Michiel De Smet <mdesmet@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.opencode/skills/dbt-analyze/SKILL.md

@@ -111,7 +111,7 @@ If no manifest is available:
 1. Run `lineage_check` on the changed SQL
 2. Show column-level data flow
 3. Note: downstream impact requires a manifest
-4. Suggest: `altimate-dbt build-project` to generate one
+4. Suggest: `altimate-dbt build` to generate one
 
 ## Common Mistakes
 

.opencode/skills/dbt-analyze/references/altimate-dbt-commands.md

@@ -20,10 +20,10 @@ altimate-dbt info                          # Project name, adapter, root
 ## Build & Run
 
 ```bash
-altimate-dbt build --model <name> [--downstream]   # compile + run + test
+altimate-dbt build                                  # full project build (compile + run + test)
+altimate-dbt build --model <name> [--downstream]   # build a single model
 altimate-dbt run --model <name> [--downstream]      # materialize only
 altimate-dbt test --model <name>                     # run tests only
-altimate-dbt build-project                           # full project build
 ```
 
 ## Compile

.opencode/skills/dbt-develop/references/altimate-dbt-commands.md

@@ -20,10 +20,10 @@ altimate-dbt info                          # Project name, adapter, root
 ## Build & Run
 
 ```bash
-altimate-dbt build --model <name> [--downstream]   # compile + run + test
+altimate-dbt build                                  # full project build (compile + run + test)
+altimate-dbt build --model <name> [--downstream]   # build a single model
 altimate-dbt run --model <name> [--downstream]      # materialize only
 altimate-dbt test --model <name>                     # run tests only
-altimate-dbt build-project                           # full project build
 ```
 
 ## Compile

.opencode/skills/dbt-docs/references/altimate-dbt-commands.md

@@ -20,10 +20,10 @@ altimate-dbt info                          # Project name, adapter, root
 ## Build & Run
 
 ```bash
-altimate-dbt build --model <name> [--downstream]   # compile + run + test
+altimate-dbt build                                  # full project build (compile + run + test)
+altimate-dbt build --model <name> [--downstream]   # build a single model
 altimate-dbt run --model <name> [--downstream]      # materialize only
 altimate-dbt test --model <name>                     # run tests only
-altimate-dbt build-project                           # full project build
 ```
 
 ## Compile

.opencode/skills/dbt-test/references/altimate-dbt-commands.md

@@ -20,10 +20,10 @@ altimate-dbt info                          # Project name, adapter, root
 ## Build & Run
 
 ```bash
-altimate-dbt build --model <name> [--downstream]   # compile + run + test
+altimate-dbt build                                  # full project build (compile + run + test)
+altimate-dbt build --model <name> [--downstream]   # build a single model
 altimate-dbt run --model <name> [--downstream]      # materialize only
 altimate-dbt test --model <name>                     # run tests only
-altimate-dbt build-project                           # full project build
 ```
 
 ## Compile

.opencode/skills/dbt-troubleshoot/references/altimate-dbt-commands.md

@@ -20,10 +20,10 @@ altimate-dbt info                          # Project name, adapter, root
 ## Build & Run
 
 ```bash
-altimate-dbt build --model <name> [--downstream]   # compile + run + test
+altimate-dbt build                                  # full project build (compile + run + test)
+altimate-dbt build --model <name> [--downstream]   # build a single model
 altimate-dbt run --model <name> [--downstream]      # materialize only
 altimate-dbt test --model <name>                     # run tests only
-altimate-dbt build-project                           # full project build
 ```
 
 ## Compile

packages/dbt-tools/src/commands/build.ts

@@ -2,7 +2,7 @@ import type { DBTProjectIntegrationAdapter, CommandProcessResult } from "@altima
 
 export async function build(adapter: DBTProjectIntegrationAdapter, args: string[]) {
   const model = flag(args, "model")
-  if (!model) return { error: "Missing --model" }
+  if (!model) return project(adapter)
   const downstream = args.includes("--downstream")
   const result = await adapter.unsafeBuildModelImmediately({
     plusOperatorLeft: "",

packages/dbt-tools/src/index.ts

@@ -11,10 +11,9 @@ const USAGE = {
     info: "Get project info (paths, targets, version)",
     compile: "Compile a model (Jinja to SQL) --model <name>",
     "compile-query": "Compile a raw query --query <sql> [--model <name>]",
-    build: "Build a model --model <name> [--downstream]",
+    build: "Build project, or a single model with --model <name> [--downstream]",
     run: "Run a model --model <name> [--downstream]",
     test: "Test a model --model <name>",
-    "build-project": "Build entire project",
     execute: "Execute SQL --query <sql> [--model <name>] [--limit <n>]",
     columns: "Get columns of model --model <name>",
     "columns-source": "Get columns of source --source <name> --table <name>",
@@ -171,9 +170,6 @@ async function main() {
       case "test":
         result = await (await import("./commands/build")).test(adapter, rest)
         break
-      case "build-project":
-        result = await (await import("./commands/build")).project(adapter)
-        break
       case "execute":
         result = await (await import("./commands/execute")).execute(adapter, rest)
         break

packages/dbt-tools/test/build.test.ts

@@ -0,0 +1,57 @@
+import { describe, test, expect, mock } from "bun:test"
+import { build } from "../src/commands/build"
+import type { DBTProjectIntegrationAdapter } from "@altimateai/dbt-integration"
+
+function makeAdapter(overrides: Partial<DBTProjectIntegrationAdapter> = {}): DBTProjectIntegrationAdapter {
+  return {
+    unsafeBuildModelImmediately: mock(() => Promise.resolve({ stdout: "model built", stderr: "" })),
+    unsafeBuildProjectImmediately: mock(() => Promise.resolve({ stdout: "project built", stderr: "" })),
+    unsafeRunModelImmediately: mock(() => Promise.resolve({ stdout: "", stderr: "" })),
+    unsafeRunModelTestImmediately: mock(() => Promise.resolve({ stdout: "", stderr: "" })),
+    dispose: mock(() => Promise.resolve()),
+    ...overrides,
+  } as unknown as DBTProjectIntegrationAdapter
+}
+
+describe("build command", () => {
+  test("build without --model builds entire project", async () => {
+    const adapter = makeAdapter()
+    const result = await build(adapter, [])
+    expect(adapter.unsafeBuildProjectImmediately).toHaveBeenCalledTimes(1)
+    expect(adapter.unsafeBuildModelImmediately).not.toHaveBeenCalled()
+    expect(result).toEqual({ stdout: "project built" })
+  })
+
+  test("build --model <name> builds single model", async () => {
+    const adapter = makeAdapter()
+    const result = await build(adapter, ["--model", "orders"])
+    expect(adapter.unsafeBuildModelImmediately).toHaveBeenCalledTimes(1)
+    expect(adapter.unsafeBuildModelImmediately).toHaveBeenCalledWith({
+      plusOperatorLeft: "",
+      modelName: "orders",
+      plusOperatorRight: "",
+    })
+    expect(adapter.unsafeBuildProjectImmediately).not.toHaveBeenCalled()
+    expect(result).toEqual({ stdout: "model built" })
+  })
+
+  test("build --model <name> --downstream sets plusOperatorRight", async () => {
+    const adapter = makeAdapter()
+    await build(adapter, ["--model", "orders", "--downstream"])
+    expect(adapter.unsafeBuildModelImmediately).toHaveBeenCalledWith({
+      plusOperatorLeft: "",
+      modelName: "orders",
+      plusOperatorRight: "+",
+    })
+  })
+
+  test("build surfaces stderr as error", async () => {
+    const adapter = makeAdapter({
+      unsafeBuildProjectImmediately: mock(() =>
+        Promise.resolve({ stdout: "partial output", stderr: "compilation error", fullOutput: "" }),
+      ),
+    })
+    const result = await build(adapter, [])
+    expect(result).toEqual({ error: "compilation error", stdout: "partial output" })
+  })
+})

packages/opencode/src/altimate/telemetry/index.ts

@@ -349,6 +349,8 @@ export namespace Telemetry {
         skill_name: string
         skill_source: "builtin" | "global" | "project"
         duration_ms: number
+        has_followups: boolean
+        followup_count: number
       }
     // altimate_change start — first_launch event for new user counting (privacy-safe: only version + machine_id)
     | {