feat: plan agent refinement, feature discovery

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

@@ -349,6 +349,9 @@ export namespace Telemetry {
         skill_name: string
         skill_source: "builtin" | "global" | "project"
         duration_ms: number
+        // altimate_change start — skill trigger classification for discovery analytics
+        trigger: "user_command" | "llm_selected" | "auto_suggested" | "unknown"
+        // altimate_change end
       }
     // altimate_change start — first_launch event for new user counting (privacy-safe: only version + machine_id)
     | {
@@ -385,6 +388,15 @@ export namespace Telemetry {
         source: "cli" | "tui"
       }
     // altimate_change end
+    // altimate_change start — plan refinement telemetry event
+    | {
+        type: "plan_revision"
+        timestamp: number
+        session_id: string
+        revision_number: number
+        action: "refine" | "approve" | "reject"
+      }
+    // altimate_change end
     | {
         type: "sql_execute_failure"
         timestamp: number
@@ -395,6 +407,16 @@ export namespace Telemetry {
         masked_sql: string
         duration_ms: number
       }
+    // altimate_change start — feature_suggestion event for post-connect and progressive disclosure tracking
+    | {
+        type: "feature_suggestion"
+        timestamp: number
+        session_id: string
+        suggestion_type: "post_warehouse_connect" | "dbt_detected" | "schema_not_indexed" | "progressive_disclosure"
+        suggestions_shown: string[]
+        warehouse_type?: string
+      }
+    // altimate_change end
     | {
         type: "core_failure"
         timestamp: number
@@ -561,6 +583,16 @@ export namespace Telemetry {
     return "standard"
   }
 
+  // altimate_change start — classify how a skill was triggered for discovery analytics
+  export function classifySkillTrigger(extra?: { [key: string]: any }): "user_command" | "llm_selected" | "auto_suggested" | "unknown" {
+    if (!extra) return "llm_selected"
+    if (extra.trigger === "user_command") return "user_command"
+    if (extra.trigger === "auto_suggested") return "auto_suggested"
+    if (extra.trigger === "llm_selected") return "llm_selected"
+    return "llm_selected"
+  }
+  // altimate_change end
+
   export function bucketCount(n: number): string {
     if (n <= 0) return "0"
     if (n <= 10) return "1-10"

packages/opencode/src/altimate/tools/post-connect-suggestions.ts

@@ -0,0 +1,106 @@
+/**
+ * Post-connect feature suggestions and progressive disclosure.
+ *
+ * After warehouse connect, users often don't know what to do next.
+ * This module provides contextual suggestions based on the user's
+ * environment and progressive next-step hints after tool usage.
+ */
+
+import { Telemetry } from "../../telemetry"
+
+export namespace PostConnectSuggestions {
+  export interface SuggestionContext {
+    warehouseType: string
+    schemaIndexed: boolean
+    dbtDetected: boolean
+    connectionCount: number
+    toolsUsedInSession: string[]
+  }
+
+  export function getPostConnectSuggestions(ctx: SuggestionContext): string {
+    const suggestions: string[] = []
+
+    if (!ctx.schemaIndexed) {
+      suggestions.push(
+        "Index your schema — enables SQL analysis, column-level lineage, and data quality checks. Use the schema_index tool.",
+      )
+    }
+
+    suggestions.push(
+      "Run SQL queries against your " +
+        ctx.warehouseType +
+        " warehouse using sql_execute",
+    )
+    suggestions.push(
+      "Analyze SQL quality and find potential issues with sql_analyze",
+    )
+
+    if (ctx.dbtDetected) {
+      suggestions.push(
+        "dbt project detected — try /dbt-develop to help build models or /dbt-troubleshoot to debug issues",
+      )
+    }
+
+    suggestions.push(
+      "Trace data lineage across your models with lineage_check",
+    )
+    suggestions.push("Audit for PII exposure with schema_detect_pii")
+
+    if (ctx.connectionCount > 1) {
+      suggestions.push("Compare data across warehouses with data_diff")
+    }
+
+    return (
+      "\n\n---\nAvailable capabilities for your " +
+      ctx.warehouseType +
+      " warehouse:\n" +
+      suggestions.map((s, i) => `${i + 1}. ${s}`).join("\n")
+    )
+  }
+
+  /**
+   * Progressive disclosure: suggest next tool based on what was just used.
+   * Returns null if no suggestion applies or tool is unknown.
+   */
+  export function getProgressiveSuggestion(
+    lastToolUsed: string,
+  ): string | null {
+    const progression: Record<string, string | null> = {
+      sql_execute:
+        "Tip: Use sql_analyze to check this query for potential issues, performance optimizations, and best practices.",
+      sql_analyze:
+        "Tip: Use schema_inspect to explore the tables and columns referenced in your query.",
+      schema_inspect:
+        "Tip: Use lineage_check to see how this data flows through your models.",
+      schema_index:
+        "Schema indexed! You can now use sql_analyze for quality checks, schema_inspect for exploration, and lineage_check for data flow analysis.",
+      warehouse_add: null, // Handled by post-connect suggestions
+    }
+    return progression[lastToolUsed] ?? null
+  }
+
+  /**
+   * Track that feature suggestions were shown, for measuring discovery rates.
+   */
+  export function trackSuggestions(opts: {
+    suggestionType:
+      | "post_warehouse_connect"
+      | "dbt_detected"
+      | "progressive_disclosure"
+    suggestionsShown: string[]
+    warehouseType?: string
+  }): void {
+    try {
+      Telemetry.track({
+        type: "feature_suggestion",
+        timestamp: Date.now(),
+        session_id: Telemetry.getContext().sessionId,
+        suggestion_type: opts.suggestionType,
+        suggestions_shown: opts.suggestionsShown,
+        warehouse_type: opts.warehouseType ?? "unknown",
+      })
+    } catch {
+      // Telemetry must never break tool execution
+    }
+  }
+}

packages/opencode/src/altimate/tools/project-scan.ts

@@ -506,6 +506,23 @@ export const ProjectScanTool = Tool.define("project_scan", {
       if (dbtProject.hasPackages) {
         lines.push(`  ✓ packages.yml or dependencies.yml found`)
       }
+      // altimate_change start — dbt auto-detection skill suggestions
+      lines.push("")
+      lines.push(`  Recommended skills:`)
+      lines.push(`  - /dbt-develop — Build and modify dbt models with AI assistance`)
+      lines.push(`  - /dbt-troubleshoot — Debug failing dbt models and tests`)
+      lines.push(`  - /dbt-analyze — Analyze dbt project structure and dependencies`)
+
+      try {
+        const { PostConnectSuggestions } = await import("./post-connect-suggestions")
+        PostConnectSuggestions.trackSuggestions({
+          suggestionType: "dbt_detected",
+          suggestionsShown: ["dbt_develop", "dbt_troubleshoot", "dbt_analyze"],
+        })
+      } catch {
+        // Telemetry must never break scan output
+      }
+      // altimate_change end
     } else {
       lines.push("✗ No dbt_project.yml found")
     }

packages/opencode/src/altimate/tools/schema-index.ts

@@ -2,6 +2,9 @@ import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
 import type { SchemaIndexResult } from "../native/types"
+// altimate_change start — progressive disclosure suggestions
+import { PostConnectSuggestions } from "./post-connect-suggestions"
+// altimate_change end
 
 export const SchemaIndexTool = Tool.define("schema_index", {
   description:
@@ -15,14 +18,26 @@ export const SchemaIndexTool = Tool.define("schema_index", {
         warehouse: args.warehouse,
       })
 
+      // altimate_change start — progressive disclosure suggestions
+      let output = formatIndexResult(result)
+      const suggestion = PostConnectSuggestions.getProgressiveSuggestion("schema_index")
+      if (suggestion) {
+        output += "\n\n" + suggestion
+        PostConnectSuggestions.trackSuggestions({
+          suggestionType: "progressive_disclosure",
+          suggestionsShown: ["sql_analyze", "schema_inspect", "lineage_check"],
+          warehouseType: result.type,
+        })
+      }
+      // altimate_change end
       return {
         title: `Schema Indexed: ${result.warehouse}`,
         metadata: {
           schemas: result.schemas_indexed,
           tables: result.tables_indexed,
           columns: result.columns_indexed,
         },
-        output: formatIndexResult(result),
+        output,
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)

packages/opencode/src/altimate/tools/schema-inspect.ts

@@ -2,6 +2,9 @@ import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
 import type { SchemaInspectResult } from "../native/types"
+// altimate_change start — progressive disclosure suggestions
+import { PostConnectSuggestions } from "./post-connect-suggestions"
+// altimate_change end
 
 export const SchemaInspectTool = Tool.define("schema_inspect", {
   description: "Inspect database schema — list columns, types, and constraints for a table.",
@@ -18,10 +21,21 @@ export const SchemaInspectTool = Tool.define("schema_inspect", {
         warehouse: args.warehouse,
       })
 
+      // altimate_change start — progressive disclosure suggestions
+      let output = formatSchema(result)
+      const suggestion = PostConnectSuggestions.getProgressiveSuggestion("schema_inspect")
+      if (suggestion) {
+        output += "\n\n" + suggestion
+        PostConnectSuggestions.trackSuggestions({
+          suggestionType: "progressive_disclosure",
+          suggestionsShown: ["lineage_check"],
+        })
+      }
+      // altimate_change end
       return {
         title: `Schema: ${result.table}`,
         metadata: { columnCount: result.columns.length, rowCount: result.row_count },
-        output: formatSchema(result),
+        output,
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)

packages/opencode/src/altimate/tools/sql-analyze.ts

@@ -2,6 +2,9 @@ import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
 import type { SqlAnalyzeResult } from "../native/types"
+// altimate_change start — progressive disclosure suggestions
+import { PostConnectSuggestions } from "./post-connect-suggestions"
+// altimate_change end
 
 export const SqlAnalyzeTool = Tool.define("sql_analyze", {
   description:
@@ -21,6 +24,17 @@ export const SqlAnalyzeTool = Tool.define("sql_analyze", {
         dialect: args.dialect,
       })
 
+      // altimate_change start — progressive disclosure suggestions
+      let output = formatAnalysis(result)
+      const suggestion = PostConnectSuggestions.getProgressiveSuggestion("sql_analyze")
+      if (suggestion) {
+        output += "\n\n" + suggestion
+        PostConnectSuggestions.trackSuggestions({
+          suggestionType: "progressive_disclosure",
+          suggestionsShown: ["schema_inspect"],
+        })
+      }
+      // altimate_change end
       return {
         title: `Analyze: ${result.error ? "PARSE ERROR" : `${result.issue_count} issue${result.issue_count !== 1 ? "s" : ""}`} [${result.confidence}]`,
         metadata: {
@@ -29,7 +43,7 @@ export const SqlAnalyzeTool = Tool.define("sql_analyze", {
           confidence: result.confidence,
           ...(result.error && { error: result.error }),
         },
-        output: formatAnalysis(result),
+        output,
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e)

packages/opencode/src/altimate/tools/sql-execute.ts

@@ -5,6 +5,9 @@ import type { SqlExecuteResult } from "../native/types"
 // altimate_change start - SQL write access control
 import { classifyAndCheck } from "./sql-classify"
 // altimate_change end
+// altimate_change start — progressive disclosure suggestions
+import { PostConnectSuggestions } from "./post-connect-suggestions"
+// altimate_change end
 
 export const SqlExecuteTool = Tool.define("sql_execute", {
   description: "Execute SQL against a connected data warehouse. Returns results as a formatted table.",
@@ -37,7 +40,18 @@ export const SqlExecuteTool = Tool.define("sql_execute", {
         limit: args.limit,
       })
 
-      const output = formatResult(result)
+      let output = formatResult(result)
+      // altimate_change start — progressive disclosure suggestions
+      const suggestion = PostConnectSuggestions.getProgressiveSuggestion("sql_execute")
+      if (suggestion) {
+        output += "\n\n" + suggestion
+        PostConnectSuggestions.trackSuggestions({
+          suggestionType: "progressive_disclosure",
+          suggestionsShown: ["sql_analyze"],
+          warehouseType: args.warehouse ?? "default",
+        })
+      }
+      // altimate_change end
       return {
         title: `SQL: ${args.query.slice(0, 60)}${args.query.length > 60 ? "..." : ""}`,
         metadata: { rowCount: result.row_count, truncated: result.truncated },

packages/opencode/src/altimate/tools/warehouse-add.ts

@@ -1,6 +1,9 @@
 import z from "zod"
 import { Tool } from "../../tool/tool"
 import { Dispatcher } from "../native"
+// altimate_change start — post-connect feature suggestions
+import { PostConnectSuggestions } from "./post-connect-suggestions"
+// altimate_change end
 
 export const WarehouseAddTool = Tool.define("warehouse_add", {
   description:
@@ -41,10 +44,49 @@ IMPORTANT: For private key file paths, always use "private_key_path" (not "priva
       })
 
       if (result.success) {
+        // altimate_change start — append post-connect feature suggestions
+        let output = `Successfully added warehouse '${result.name}' (type: ${result.type}).\n\nUse warehouse_test to verify connectivity.`
+        try {
+          const schemaCache = await Dispatcher.call("schema.cache_status", {}).catch(() => null)
+          const schemaIndexed = (schemaCache?.total_tables ?? 0) > 0
+          const warehouseList = await Dispatcher.call("warehouse.list", {}).catch(() => ({ warehouses: [] }))
+
+          let dbtDetected = false
+          try {
+            const { detectDbtProject } = await import("./project-scan")
+            const dbtInfo = await detectDbtProject(process.cwd())
+            dbtDetected = dbtInfo.found
+          } catch {
+            // project-scan unavailable — skip dbt detection
+          }
+
+          const ctx: PostConnectSuggestions.SuggestionContext = {
+            warehouseType: result.type,
+            schemaIndexed,
+            dbtDetected,
+            connectionCount: warehouseList.warehouses.length,
+            toolsUsedInSession: [],
+          }
+          output += PostConnectSuggestions.getPostConnectSuggestions(ctx)
+
+          const suggestionsShown = ["sql_execute", "sql_analyze", "lineage_check", "schema_detect_pii"]
+          if (!schemaIndexed) suggestionsShown.unshift("schema_index")
+          if (dbtDetected) suggestionsShown.push("dbt_develop", "dbt_troubleshoot")
+          if (warehouseList.warehouses.length > 1) suggestionsShown.push("data_diff")
+          PostConnectSuggestions.trackSuggestions({
+            suggestionType: "post_warehouse_connect",
+            suggestionsShown,
+            warehouseType: result.type,
+          })
+        } catch {
+          // Suggestions must never break the add flow
+        }
+        // altimate_change end
+
         return {
           title: `Add '${args.name}': OK`,
           metadata: { success: true, name: result.name, type: result.type },
-          output: `Successfully added warehouse '${result.name}' (type: ${result.type}).\n\nUse warehouse_test to verify connectivity.`,
+          output,
         }
       }