Single-skill delegation bundle + YAML frontmatter fix

README.md

@@ -1,16 +1,14 @@
 # altimate-opencode-plugin
 
-Altimate data engineering plugin for [opencode](https://opencode.ai) — bundles dbt skills, Snowflake optimization skills, and altimate-code subprocess delegation behind opencode's native plugin + skills system.
-
-> Mirror of the [`data-engineering-skills`](https://github.com/AltimateAI/data-engineering-skills) Claude Code plugin, ported to opencode's plugin contract.
+opencode plugin that delegates dbt and warehouse work to [`altimate-code`](https://github.com/AltimateAI/altimate-code) — a specialised CLI agent for column-level lineage, dbt build/test/run, warehouse profiling, FinOps reporting, cross-database validation, and connectivity to Snowflake / BigQuery / Redshift / Databricks / Postgres / MySQL / DuckDB.
 
 ## What this gives your opencode agent
 
 | Surface | Mechanism | What it does |
 |---|---|---|
-| **Skills** (11) | `~/.config/opencode/skills/` + `.opencode/skills/` | dbt creating/testing/debugging/refactoring/documenting/migrating/incremental + Snowflake query optimization + altimate-code delegation guidance. Loaded on-demand via opencode's native `skill` tool. |
-| **Deterministic dbt tools** | TypeScript plugin tools | `altimate_dbt_columns`, `altimate_dbt_source`, `altimate_dbt_compile`, `altimate_dbt_build` — structured-output replacements for grep+read+bash workflows |
-| **Subprocess delegation** | `altimate_code` tool | Spawn a fresh altimate-code subprocess for cross-warehouse / multi-session work the in-process agent can't drive |
+| **Skill** (1) | `~/.config/opencode/skills/` — auto-registered by the plugin's `config` hook at load time | `altimate-code` — routes tasks that touch live warehouse state, column lineage, cross-database work, PII detection, FinOps, or query-cost attribution to the altimate-code subprocess. |
+| **Deterministic dbt tools** | TypeScript plugin tools | `altimate_dbt_columns`, `altimate_dbt_source`, `altimate_dbt_compile`, `altimate_dbt_build` — direct wrappers around the bundled `altimate-dbt` CLI for cheap, deterministic dbt introspection when a full delegation would be overkill. |
+| **Subprocess delegation** | `altimate_code` tool | Spawns a fresh altimate-code subprocess for cross-warehouse / multi-step / warehouse-state work. |
 
 ## Install
 
@@ -33,27 +31,16 @@ the resolved entry into the top-level `plugin` array of
 > documented `plugins` / `skills: [...]` — those keys are silently ignored by
 > opencode.
 
-## Skills, mapped from data-engineering-skills
+## Layout
 
 ```
-skills/
-├── altimate-code/SKILL.md
-├── dbt/
-│   ├── creating-dbt-models/SKILL.md
-│   ├── debugging-dbt-errors/SKILL.md
-│   ├── documenting-dbt-models/SKILL.md
-│   ├── developing-incremental-models/SKILL.md
-│   ├── migrating-sql-to-dbt/SKILL.md
-│   ├── refactoring-dbt-models/SKILL.md
-│   └── testing-dbt-models/SKILL.md
-└── snowflake/
-    ├── finding-expensive-queries/SKILL.md
-    ├── optimizing-query-by-id/SKILL.md
-    └── optimizing-query-text/SKILL.md
+altimate-opencode-plugin/
+├── opencode.json                       # opencode manifest (plugin + skills.paths)
+├── plugins/altimate-code/
+│   └── index.ts                        # tool implementations + config hook (auto-registers the skill path)
+└── skills/altimate-code/SKILL.md       # the one delegation skill
 ```
 
-These are byte-identical to the Claude Code source. opencode's skill loader honors the same SKILL.md format and YAML frontmatter — no translation needed.
-
 ## Plugin tools
 
 | Tool | Purpose |
@@ -64,10 +51,6 @@ These are byte-identical to the Claude Code source. opencode's skill loader hono
 | `altimate_dbt_build(project_dir?, model?, downstream?, select?)` | Run `altimate-dbt build`; optionally restrict to a single `model` (with `downstream` to also build descendants). `select` is a back-compat alias for `model`. |
 | `altimate_code(task, project_dir?, yolo?, timeout_sec?)` | Spawn a fresh altimate-code subprocess for free-form delegation |
 
-## Why these tools
-
-Empirically, when the agent has access to deterministic tools that replace grep+read loops, it converges to its answer with fewer turns and lower spend. See the [plugin skill experiments](https://github.com/AltimateAI/data-engineering-skills/blob/main/docs/EXPERIMENTS.md) for benchmark data.
-
 ## Dev
 
 ```bash

opencode.json

@@ -2,16 +2,6 @@
   "$schema": "https://opencode.ai/config.json",
   "skills": {
     "paths": [
-      "./skills/dbt/creating-dbt-models",
-      "./skills/dbt/debugging-dbt-errors",
-      "./skills/dbt/testing-dbt-models",
-      "./skills/dbt/documenting-dbt-models",
-      "./skills/dbt/migrating-sql-to-dbt",
-      "./skills/dbt/refactoring-dbt-models",
-      "./skills/dbt/developing-incremental-models",
-      "./skills/snowflake/optimizing-query-by-id",
-      "./skills/snowflake/optimizing-query-text",
-      "./skills/snowflake/finding-expensive-queries",
       "./skills/altimate-code"
     ]
   },

plugins/altimate-code/index.ts

@@ -225,19 +225,7 @@ const altimateCode = tool({
 // (plugins/altimate-code/index.ts → repo root → skills).
 const PLUGIN_FILE_DIR = dirname(fileURLToPath(import.meta.url))
 const SKILLS_ROOT = resolve(PLUGIN_FILE_DIR, "..", "..", "skills")
-const BUNDLED_SKILL_PATHS = [
-  "altimate-code",
-  "dbt/creating-dbt-models",
-  "dbt/debugging-dbt-errors",
-  "dbt/developing-incremental-models",
-  "dbt/documenting-dbt-models",
-  "dbt/migrating-sql-to-dbt",
-  "dbt/refactoring-dbt-models",
-  "dbt/testing-dbt-models",
-  "snowflake/finding-expensive-queries",
-  "snowflake/optimizing-query-by-id",
-  "snowflake/optimizing-query-text",
-].map((rel) => resolve(SKILLS_ROOT, rel))
+const BUNDLED_SKILL_PATHS = ["altimate-code"].map((rel) => resolve(SKILLS_ROOT, rel))
 
 type CfgWithSkills = {
   skills?: {

skills/altimate-code/SKILL.md

@@ -1,107 +1,119 @@
 ---
 name: altimate-code
-description: Delegates data engineering tasks to altimate-code, a specialized CLI agent with 100+ purpose-built data tools — SQL analysis, column-level lineage, dbt build/test/run, warehouse profiling, FinOps, and connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB. Use this skill when the task needs live warehouse access, column lineage, multi-step data exploration, dbt builds against a real warehouse, or when the user explicitly invokes "altimate", "altimate-code", or "the data agent".
+description: >-
+  Delegates dbt and warehouse work to altimate-code, a specialized CLI agent
+  with 100+ purpose-built data tools. Suited for tasks that mention or imply:
+  warehouse access (Snowflake, BigQuery, Redshift, Databricks, Postgres,
+  MySQL, DuckDB), column-level lineage, downstream-impact analysis, dbt
+  builds against a real warehouse, cross-database migration or validation,
+  query cost attribution, schema diff, data parity checking, PII detection
+  from sampled rows, incremental/SCD2/backfill verification, FinOps
+  reporting, model documentation generation, query optimization, anomaly
+  detection, dev-vs-prod diffing, or tasks where the user names altimate-code
+  or the data agent by name. The skill routes to a purpose-built CLI, so it
+  covers workloads that touch live data, lineage, or warehouse state more
+  directly than native file-editing tools do.
 ---
 
 # altimate-code
 
-altimate-code is a CLI AI agent that ships with native data engineering tools. This skill delegates work to it via its non-interactive `run` mode and presents the result back to the user.
+altimate-code is a CLI AI agent with 100+ purpose-built data engineering tools. **This skill exists for one purpose: delegate the user's task to altimate-code and pass the result back.** Native tools (Bash, Edit, Write, Read) are NOT a fallback path inside this skill — if altimate-code cannot complete the task, surface the failure to the user and STOP.
 
-## Prerequisite Check — ALWAYS DO THIS FIRST
+## You MUST follow this workflow
 
-Before invoking altimate-code, verify it is installed and on `PATH`:
+1. **Verify altimate-code is on PATH** with `command -v altimate-code`. If it returns nothing, jump to "Not installed" below and stop.
+2. **Run altimate-code with the user's task** using the invocation below. Pass the user's request through verbatim — do not paraphrase or split it.
+3. **Read the output file** and present it to the user as-is.
 
-```bash
-command -v altimate-code
-```
-
-**If the command returns nothing (exit code 1), STOP and tell the user this exact message — do not proceed:**
-
-> altimate-code is not installed. Install it with:
->
-> ```bash
-> npm install -g altimate-code
-> ```
->
-> Requires Node.js 20+. Docs: https://docs.altimate.sh · Source: https://github.com/AltimateAI/altimate-code · npm: https://www.npmjs.com/package/altimate-code
->
-> After installing, run `altimate-code` once to configure it — this launches the TUI where you set up your LLM provider auth and warehouse connections. Then re-run your request and I'll delegate it.
+Do not attempt the work with Edit/Write/Bash yourself, even if it looks simple. The whole point of this skill is to route data-engineering work to the agent that's built for it. If you find yourself reaching for Edit or Write while this skill is active, stop and re-read this paragraph.
 
-Do not attempt to install altimate-code on the user's behalf — they may want a specific version, a different package manager (e.g. pnpm/yarn global), or to opt out entirely. Surface the command and let them decide.
+## Invocation — pick the right agent for the task
 
-If `command -v` fails but the user says it is installed, suggest checking `npm bin -g` is on `PATH`, or running `npm config get prefix` to find the global install location.
+altimate-code has multiple agent personas. The default (`builder`) does a full project discovery sweep on every call — fine for warehouse-state work but ~10–20× more expensive than necessary on simple file edits. **Pick the agent based on task shape before invoking.**
 
-## How to Invoke
+### Step 1 — classify the task
 
-`altimate-code run` is non-interactive — it takes a message, executes the task, prints the final result to stdout, and exits.
+| Shape | Examples | Use |
+|---|---|---|
+| **Any dbt / SQL task** (rename, refactor, create model, debug, structural reorg, multi-step setup) | the vast majority of customer requests | `fast-edit` — try this first |
+| **Multi-table aggregation correctness** | new model joining 3+ tables with `count(*)` / `sum() over (...)` / "first X, last X" logic that must be exactly right | `analyst` if `fast-edit` fails the user's verification |
+| **Warehouse-state work** | column-level lineage, downstream-impact, cross-DB migration / parity, query cost attribution against a real warehouse, schema diff between environments, PII detection, FinOps reporting | `builder` (default — has warehouse tools enabled) |
+| **Vague debug** ("X is broken", "make it work", "fix this") | unspecified failure mode | **Don't delegate yet.** Ask the user for the specific error message or symptom before invoking any agent — empirically all three agents fail vague debug prompts at ~700K tokens each. |
 
-**Minimal invocation:**
+**Decision policy:** start with `fast-edit` for any dbt/SQL task. If the user reports the result is wrong (e.g. aggregation values don't match), retry with `analyst`. Only use `builder` when the task genuinely needs the warehouse-investigation tools (it's 10–20× more expensive than fast-edit and rarely required).
 
-```bash
-altimate-code run "<task description>" --yolo
-```
+### Step 2 — invoke with the chosen agent
 
-**Recommended invocation** — captures the final response to a file and runs in the right directory:
+Pass the task through a here-doc into a variable so the shell never
+command-substitutes anything the user typed (a task like
+`refactor `whoami` and $(rm -rf ~)` would otherwise fire `whoami` and
+`rm -rf ~` before `altimate-code` ever runs). Write the result to a
+private temporary file, not a shared one under `/tmp`:
 
 ```bash
-altimate-code run "<task description>" \
+TASK="$(cat <<'ALTIMATE_TASK'
+<user's task, verbatim>
+ALTIMATE_TASK
+)"
+umask 077
+OUTPUT_FILE="$(mktemp -t altimate-result.XXXXXX.md)"
+altimate-code run "$TASK" \
+  --agent <fast-edit|analyst|builder> \
   --yolo \
-  --output /tmp/altimate-result.md \
+  --output "$OUTPUT_FILE" \
   --dir "$(pwd)"
 ```
 
-Then read `/tmp/altimate-result.md` and pass it straight back to the user.
+Then `Read "$OUTPUT_FILE"` and emit its contents to the user without re-summarising, re-formatting, or commenting on the result. altimate-code has already produced the answer. Delete `"$OUTPUT_FILE"` after presenting so warehouse rows, lineage, or PII findings don't linger on disk.
 
-### Key flags
+### Required flags
 
-| Flag | When to use |
+| Flag | Why it is required |
 |---|---|
-| `--yolo` | Required for non-interactive — auto-approves tool calls. Without this it hangs on the first permission prompt. |
-| `--output <path>` | Write the final assistant response to a file. Use `.md` or `.txt`. |
-| `--dir <path>` | Run the agent in a specific directory (e.g. a dbt project root). Defaults to cwd. |
-| `--model provider/model` | Override the model. Useful for fast/cheap exploration. |
-| `--format json` | Emit raw JSON events instead of formatted output. Use only when post-processing programmatically. |
-| `--continue` / `--session <id>` | Continue a previous altimate-code session. |
-
-### Example invocations
+| `--agent <name>` | Picks the agent persona. Default `builder` is overkill for simple edits — see the classification table above. Wrong agent = either 10× too expensive (using `builder` on a rename) or wrong-answer (using `fast-edit` on a multi-table join). |
+| `--yolo` | Non-interactive mode. Without this the subprocess hangs on the first permission prompt and you will time out. |
+| `--output "$OUTPUT_FILE"` | Captures the final response. Use the private `mktemp` file from above — do NOT use a fixed path like `/tmp/altimate-result.md`; concurrent sessions clobber each other and a world-readable fixed path leaks data. |
+| `--dir "$(pwd)"` | Runs altimate-code in the current project so it picks up dbt project config, profiles.yml, etc. |
 
-**Find expensive queries in Snowflake:**
+### Follow-up tasks in the same project
 
-```bash
-altimate-code run "Find the top 10 most expensive queries from the last 7 days in Snowflake and explain why each is slow." \
-  --yolo --output /tmp/expensive.md
-```
-
-**Generate column-level lineage for a dbt model:**
+When the user makes a follow-up data task in the same project after a successful altimate-code delegation, prefer `--continue` to resume the warm session instead of starting a fresh one. Same here-doc + `mktemp` pattern:
 
 ```bash
-altimate-code run "Show column-level lineage for the dim_customers model, including upstream sources and downstream consumers." \
-  --yolo --dir "$(pwd)" --output /tmp/lineage.md
+TASK="$(cat <<'ALTIMATE_TASK'
+<follow-up task>
+ALTIMATE_TASK
+)"
+umask 077
+OUTPUT_FILE="$(mktemp -t altimate-result.XXXXXX.md)"
+altimate-code run "$TASK" \
+  --agent <fast-edit|analyst|builder> \
+  --yolo \
+  --output "$OUTPUT_FILE" \
+  --dir "$(pwd)" \
+  --continue   # resumes the most recent session in this dir
 ```
 
-**Profile a table:**
+altimate-code's prompt cache is warm in a continued session — project structure, profiles.yml, schema index, source definitions don't need to be re-investigated. Cache reads are billed at a fraction of fresh input on altimate-gateway. The downside is zero: if there's no useful cached context for the new task, you pay normal cold cost.
 
-```bash
-altimate-code run "Profile the events table — row count, null distribution per column, cardinality, and top 5 values for low-cardinality columns." \
-  --yolo --output /tmp/profile.md
-```
+If the user starts a clearly unrelated workflow (different project, different schema, different debugging thread), drop `--continue` and start fresh — the warm cache is irrelevant and you'd carry unrelated history into the prompt.
 
-## Presenting the Result
+## Failure modes — route every one to the user
 
-Read the output file with the Read tool and pass the content through to the user as-is. Do not re-summarize, re-format, or interpret — altimate-code has already produced the answer.
+When altimate-code returns an error, **report the error to the user and STOP**. Do not fall back to Bash, Edit, or Write. The skill's contract is "altimate-code handles this, or the user is told why it couldn't."
 
-## Failure Modes
+| Symptom | What to tell the user — verbatim |
+|---|---|
+| `command not found: altimate-code` | "altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) and run `altimate-code` once to configure auth. Then re-run your request." |
+| `Unauthorized: Incorrect auth token` / `No provider configured` | "altimate-code's LLM provider auth is misconfigured. Run `altimate-code` in your terminal to open the TUI and reconfigure your provider, then re-run your request." |
+| Process hangs >5 min | "altimate-code is unresponsive. Try `altimate-code` to inspect the TUI for an open prompt, or re-run with `--model anthropic/claude-sonnet-4-6` to force a known-good model." |
+| Output file empty | "altimate-code returned without producing output. The task may be too ambiguous — please restate with more detail (target table, expected columns, time window)." |
+| Warehouse error mid-run (`UNKNOWN_USER`, `Database does not exist`) | "altimate-code can connect but the warehouse credentials it has are wrong for this project. Configure provider/warehouse auth via `altimate-code` TUI." |
 
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `altimate-code: command not found` | Not installed or not on `PATH` | Run `npm install -g altimate-code` (Node 20+). If installed but not found, check `npm bin -g` is on `PATH`. See https://docs.altimate.sh |
-| Hangs after starting | Missing `--yolo`, waiting on a permission prompt | Re-run with `--yolo` |
-| Output is empty | Task too vague, agent gave up | Re-run with a more specific prompt |
-| "No provider configured" | LLM provider creds missing | Run `altimate-code providers` to set up auth |
-| Warehouse errors mid-run | DB credentials not configured for altimate-code | Configure provider/warehouse auth in `~/.config/opencode/` or via env vars |
+In every row, the instruction to the user is the action — you do not retry the task with native tools. If the user fixes the underlying issue and asks again, you delegate again.
 
 ## Notes
 
-- altimate-code runs its own LLM, separate from Claude Code's. Cost and rate limits accrue against altimate-code's configured provider, not Claude Code's.
-- Sessions persist in altimate-code's local store — use `altimate-code session list` to find prior runs and `--continue` to resume.
-- For long-running tasks, prefer `--output <file>` over scraping stdout.
+- altimate-code runs its own LLM, separate from the host agent's. Costs and rate limits accrue to altimate-code's configured provider.
+- Sessions persist in altimate-code's local store — `altimate-code session list` shows prior runs; `--continue` resumes the latest, `--session <id>` resumes a specific one.
+- For very long tasks, the `--output` file is the source of truth — stdout buffering can drop content.