diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8a3dc75..7bee2a3 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,13 +6,13 @@ "url": "https://altimate.ai" }, "metadata": { - "description": "Altimate's Claude Code plugin — delegates dbt and warehouse work to the altimate-code CLI agent.", - "version": "1.1.1" + "description": "Altimate's Claude Code plugin — direct MCP data tools and CLI delegation for long dbt and warehouse jobs.", + "version": "1.2.0-experimental" }, "plugins": [ { "name": "altimate-code", - "description": "Delegates dbt and warehouse work 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, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB), and to the skills, knowledge and memory of a linked Altimate workspace.", + "description": "Use altimate-code data tools directly through MCP with Claude Code reasoning, or delegate long dbt and warehouse jobs to the altimate-code CLI agent.", "source": "./plugins/altimate-code", "strict": false } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 911bf60..1f1b7a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -Thanks for taking the time to contribute. This plugin lives in one repo (`AltimateAI/altimate-claude-plugin`) and ships a single Claude Code plugin (`altimate-code`) that delegates data-engineering tasks to the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI. +Thanks for taking the time to contribute. This plugin lives in one repo (`AltimateAI/altimate-claude-plugin`) and ships a single Claude Code plugin (`altimate-code`). It prefers direct MCP tools for data questions and delegates to the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI for other capabilities and long jobs. When MCP tools are unavailable, data questions also delegate, using the analyst persona. Both paths tell the user which is being used; delegation uses the CLI's separate configured LLM provider. ## Quick start @@ -28,9 +28,12 @@ altimate-claude-plugin/ │ └── altimate-code/ │ ├── .claude-plugin/ │ │ └── plugin.json # plugin manifest +│ ├── .mcp.json # local stdio MCP server registration │ ├── skills/ │ │ └── altimate-code/ -│ │ └── SKILL.md # delegation logic +│ │ └── SKILL.md # MCP/delegation routing and CLI invocation +│ ├── agents/ +│ │ └── analyst.md # read-only data analyst for the MCP tools │ ├── hooks/ │ │ └── hooks.json # SessionStart hook config │ ├── hooks-handlers/ @@ -49,6 +52,8 @@ altimate-claude-plugin/ ## What to change where - **Routing behavior** (when Claude picks up the skill): edit `plugins/altimate-code/skills/altimate-code/SKILL.md` frontmatter description and/or `plugins/altimate-code/hooks-handlers/session-start.sh` `additionalContext`. +- **Direct data-question analysis**: edit `plugins/altimate-code/agents/analyst.md` (the server instructions carry the method). +- **MCP server launch**: edit `plugins/altimate-code/.mcp.json` (`altimate-code mcp serve`, read-only by default). - **Explicit-invocation UX** (what `/altimate-code:altimate ` does): edit `plugins/altimate-code/commands/altimate.md`. - **CLI invocation details** (agent selection, flags, follow-up handling): edit the workflow section in `plugins/altimate-code/skills/altimate-code/SKILL.md`. @@ -79,9 +84,11 @@ claude plugin install altimate-code@altimate-claude-plugin ## Components -- **Skill** — `plugins/altimate-code/skills/altimate-code/SKILL.md` — the delegation logic (`altimate-code run "$USER_TASK"` and surface the result). +- **Routing skill** — `plugins/altimate-code/skills/altimate-code/SKILL.md` — prefer available MCP tools for data questions; otherwise delegate to `altimate-code run` with `analyst`. Delegate other capabilities and long jobs using the appropriate persona. +- **Analyst agent** — `plugins/altimate-code/agents/analyst.md` — read-only data analyst rules for the MCP tools. +- **MCP registration** — `plugins/altimate-code/.mcp.json` — launches the local stdio server; builds without `mcp serve` fail to start it and use delegation instead. - **Hook** — `plugins/altimate-code/hooks/hooks.json` + `plugins/altimate-code/hooks-handlers/session-start.sh` — SessionStart hook that describes the plugin's capabilities in the system prompt so Claude can route to it when the task shape fits. -- **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation. +- **Command** — `plugins/altimate-code/commands/altimate.md` — `/altimate-code:altimate` slash command follows the same MCP/delegation routing with agent-persona selection. ## Reporting bugs / requesting features diff --git a/PRIVACY.md b/PRIVACY.md index 47d28c0..46730a7 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -1,7 +1,7 @@ # Privacy Policy — Altimate Code plugin for Claude Code -**Effective date:** July 9, 2026 -**Applies to:** the `altimate-code` Claude Code plugin distributed from this repository, and the data flows it initiates through the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI. +**Effective date:** October 17, 2026 +**Applies to:** the `altimate-code` Claude Code plugin distributed from this repository, and the data flows it initiates through the [altimate-code](https://github.com/AltimateAI/altimate-code) MCP server and CLI. This policy supplements the Altimate AI [Privacy Policy](https://www.altimate.ai/privacy) and [Terms](https://www.altimate.ai/terms), which govern Altimate services generally. Where this document is silent, the master policy applies. Questions: **info@altimate.ai**. @@ -9,16 +9,27 @@ This policy supplements the Altimate AI [Privacy Policy](https://www.altimate.ai ## The short version -- The plugin itself collects **no data**. It is a routing layer (a skill, a slash command, and a static session hook) that tells Claude Code when to delegate a task to the altimate-code CLI installed on your machine. +- When the plugin is enabled, Claude Code launches a local `altimate-code mcp serve` process for direct data tools. This requires a build containing `mcp serve`; if the server cannot start or its tools are unavailable, data questions fall back to CLI delegation. +- MCP tool results, including sampled column values and query results, enter the Claude Code conversation and therefore reach your configured model provider. The local MCP server makes no separate LLM calls. - When a task **is** delegated, your task text is passed to the altimate-code CLI, which sends it to an LLM provider to plan and execute the work — the Altimate LLM Gateway by default, or a provider you configure (BYOK). - Warehouse queries, dbt commands, and file edits run **locally on your machine, under your credentials**. Your warehouse credentials are never sent to Altimate. - Installing the plugin is an explicit act — `/plugin marketplace add` does not install it, and `/plugin install` never auto-runs. Nothing is delegated until the plugin is installed and you send a task that matches the skill. ## What the plugin does and does not do -The plugin contains no executable service of its own. Its only runtime behavior is a SessionStart hook that prints a fixed, static text block describing the skill's capabilities. It does not read your files, does not phone home, and does not collect analytics. +The plugin registers a local stdio MCP server through `.mcp.json`, provides routing skills and slash commands, and runs a SessionStart hook that prints a fixed capability description. The server reads configured connections and runs data tools under your local credentials. The plugin adds no analytics of its own; CLI telemetry is described below. -Data leaves Claude Code's process only when the delegation skill or the `/altimate-code:altimate` command fires and invokes the locally installed altimate-code CLI. +## Data flows through MCP tools + +| Data | Where it goes | Retention | +|---|---|---| +| Database credentials and connection configuration | Read locally by the MCP server to connect to your databases | Local configuration; not included in tool results | +| Schema metadata, sampled column values, and query results returned by tools | Local MCP server → Claude Code conversation → your configured model provider | Governed by Claude Code and your model provider's policies | +| Scratch tables and spilled query results | Local session storage or spill files; any content Claude reads enters the conversation and reaches your model provider | Local artifacts; conversation copies follow Claude Code and provider policies | + +The MCP server makes no separate LLM calls. Delegation uses the separate provider path below. + +The delegation path below runs only when the delegation skill or the `/altimate-code:altimate` command fires and invokes the locally installed altimate-code CLI. ## Data flows when a task is delegated @@ -26,7 +37,7 @@ Data leaves Claude Code's process only when the delegation skill or the `/altima |---|---|---| | Your task prompt (verbatim) | Local altimate-code CLI → your configured LLM provider | Altimate LLM Gateway does not retain full prompts and responses after processing. BYOK providers: governed by that provider's policy — Altimate never sees this traffic. | | Warehouse credentials (`profiles.yml`, env vars) | Stay on your machine; used locally by the CLI | Never transmitted to Altimate | -| Warehouse query results, dbt output, file edits | Produced locally; written to a local output file surfaced back to Claude Code | Local only | +| Warehouse query results, dbt output, file edits | Produced locally; data supplied to the CLI agent reaches its configured LLM provider. Output read back into Claude Code reaches Claude Code's model provider. | Local output files; provider copies follow the applicable provider policies | | Schema metadata indexed by the CLI | Local index on your machine | Local only | **Bring Your Own Key (BYOK):** if you configure your own provider (Anthropic, OpenAI, Bedrock, Azure OpenAI, Ollama, and others), your prompts go directly from your machine to that provider. Altimate is not in the path. @@ -57,8 +68,8 @@ All data transmitted to Altimate services is encrypted in transit using TLS. Alt ## Your choices -- **Don't enable the plugin** — it ships disabled; nothing is delegated until you enable it. -- **Use BYOK** — route prompts directly to your own provider so Altimate never sees them. +- **Don't enable the plugin** — no plugin MCP server is launched and no tasks are delegated while it is disabled. +- **Use BYOK for delegation** — route CLI agent prompts directly to your own provider. MCP tool results are handled by Claude Code's configured model provider independently. - **Disable telemetry** — see above. - **Contact us** — for access, correction, or deletion requests, email **info@altimate.ai**. diff --git a/README.md b/README.md index 8cdb50d..61af2b5 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,24 @@ The Altimate marketplace of Claude Code plugins. -Currently ships one plugin: **[altimate-code](./plugins/altimate-code/)** — delegates dbt and warehouse work to the [altimate-code](https://github.com/AltimateAI/altimate-code) CLI agent. +Currently ships one plugin: **[altimate-code](./plugins/altimate-code/)** — gives Claude Code direct MCP data tools from [altimate-code](https://github.com/AltimateAI/altimate-code), with CLI delegation for long dbt and warehouse jobs. + +**Experimental: direct MCP use requires an altimate-code build with `mcp serve`.** +Released builds without `mcp serve` fail to start the MCP server; the plugin then +falls back to `altimate-code run` with the analyst persona for data questions, +using the CLI's configured LLM provider. The plugin tells you which path it uses. +With MCP available, Claude Code +supplies the reasoning and LLM cost for direct data questions; the MCP server +runs no LLM. Tools: `warehouse_list`, `warehouse_add`, `sql_execute` (with `tables` +for schemas and value profiles), `sql_materialize` (session-local scratch DuckDB for +cross-database joins) and `answer_commit`. + +Source queries are read-only by default: database-enforced on Postgres, SQLite, +and DuckDB; classification-only elsewhere, so use a read-only DB user. Connections +come from project/global `.altimate-code/connections.json` and +`ALTIMATE_CODE_CONN_*` environment variables, or an explicit `--connections ` +server argument. See the [plugin README](./plugins/altimate-code/README.md) for setup, +value profiles, result spill files, and the separate LLM billing for delegated jobs. ## Install diff --git a/plugins/altimate-code/.claude-plugin/plugin.json b/plugins/altimate-code/.claude-plugin/plugin.json index d74bcee..66e86b5 100644 --- a/plugins/altimate-code/.claude-plugin/plugin.json +++ b/plugins/altimate-code/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "altimate-code", "displayName": "Altimate Code", - "version": "1.1.1", - "description": "Delegates dbt and warehouse work 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, connectivity to Snowflake, BigQuery, Redshift, Databricks, Postgres, MySQL, DuckDB), and to the skills, knowledge and memory of a linked Altimate workspace.", + "version": "1.2.0-experimental", + "description": "Use altimate-code data tools directly through MCP with Claude Code reasoning, or delegate long dbt and warehouse jobs to the altimate-code CLI agent.", "author": { "name": "AltimateAI", "url": "https://altimate.ai" diff --git a/plugins/altimate-code/.mcp.json b/plugins/altimate-code/.mcp.json new file mode 100644 index 0000000..91038e3 --- /dev/null +++ b/plugins/altimate-code/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "altimate-code": { + "command": "altimate-code", + "args": ["mcp", "serve"] + } + } +} diff --git a/plugins/altimate-code/CHANGELOG.md b/plugins/altimate-code/CHANGELOG.md index 55a43e6..ca270c6 100644 --- a/plugins/altimate-code/CHANGELOG.md +++ b/plugins/altimate-code/CHANGELOG.md @@ -2,6 +2,19 @@ All notable changes to this plugin will be documented in this file. +## [1.2.0-experimental] — Unreleased — direct MCP use requires an altimate-code build with `mcp serve` + +### Added +- Stdio MCP registration for `altimate-code mcp serve`, without `--allow-write`. +- Direct data tools: `warehouse_list`, `warehouse_add`, `sql_execute` (`tables` returns schemas and value profiles in the same call), `sql_materialize` and `answer_commit`; `schema_inspect` and `sql_check` with `mcp serve --all-tools`. +- `analyst` agent with the rules for value-profile inspection, SQL analysis, cross-connection scratch joins, and correctness checks. `answer_commit` is optional; the analyst may end with a plain `FINAL ANSWER:` line. + +### Changed +- Routing skill and `/altimate-code:altimate` prefer MCP for data questions with Claude Code reasoning. If the MCP tools are unavailable, they fall back to CLI analyst delegation and tell the user which path is used. Released builds without `mcp serve` fail to start the MCP server and use this fallback. +- Long jobs and capabilities outside the five MCP tools retain CLI delegation and agent-persona guidance. +- Delegated runs use `builder` (no `fast-edit` persona) and the canonical-binary resolver from 1.1.x. +- Documentation covers experimental prerequisites, connection discovery, read-only enforcement limits, local result files, and separate reasoning/billing paths. + ## [1.1.1] — 2026-10-20 ### Fixed diff --git a/plugins/altimate-code/README.md b/plugins/altimate-code/README.md index 17af579..8ccea79 100644 --- a/plugins/altimate-code/README.md +++ b/plugins/altimate-code/README.md @@ -1,8 +1,15 @@ # Altimate Code — Claude Code plugin -Routes dbt + warehouse tasks from Claude Code to [altimate-code](https://github.com/AltimateAI/altimate-code), a specialized open-source CLI agent with 100+ deterministic data-engineering tools: SQL anti-pattern detection, column-level lineage, dbt build/test/run against real warehouses, FinOps and cost analysis, cross-dialect translation and data parity, and PII detection. +Use [altimate-code](https://github.com/AltimateAI/altimate-code) data tools directly +from Claude Code through MCP. **Claude Code does the reasoning and carries the +LLM cost** for data questions; the stdio MCP server runs no LLM. Long multi-step +jobs such as dbt project builds, migrations, and FinOps reports can still be +delegated to `altimate-code run`, which uses its own agent and configured provider. -**Why delegate?** General coding agents can edit SQL files; they can't inspect your live warehouse state. altimate-code gives Claude Code a deterministic data-engineering layer — indexed schemas, real query history, real cost data — instead of guesses. +**1.2.0-experimental: direct MCP use requires an altimate-code build with `mcp serve`.** +This server is in an unreleased branch. Released builds without `mcp serve` fail +to start the MCP server; the plugin falls back to `altimate-code run` with the +analyst persona for data questions. It tells you which path is being used. ## Install @@ -21,27 +28,77 @@ Or from this repository's marketplace: ## Prerequisites -The altimate-code CLI must be installed and configured on your PATH. Either install method works: +Put the CLI on PATH where Claude Code can launch it (it requires Node 20+). Either install method works: ```bash -npm install -g altimate-code # requires Node 20+; exposes `altimate` and `altimate-code` +npm install -g altimate-code # exposes `altimate` and `altimate-code` curl -fsSL https://www.altimate.sh/install | bash # standalone binary; exposes `altimate` -altimate # launch the TUI, then run /connect to configure your LLM provider ``` -The plugin invokes `altimate`, the CLI's canonical name, and falls back to `altimate-code` for npm installs older than v0.7.1, so standalone installs work without an `altimate-code` alias. +The delegation skill and commands invoke `altimate`, the CLI's canonical name, and fall back to `altimate-code` for npm installs older than v0.7.1. The MCP registration launches `altimate-code mcp serve`: for direct MCP use, install a build containing `mcp serve`. Check your build with `altimate-code mcp serve --help`; an unknown command means the MCP server cannot start and data questions use CLI delegation instead. Installing the latest published npm package alone does not provide the unreleased server. +Configure database connections as described below. Direct MCP use does **not** +require an altimate-code LLM provider or API key. For delegated jobs only, run +`altimate` to configure its provider (or use its provider environment settings, such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`). -Or configure a provider via environment variable (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and 20+ others — see the [altimate-code docs](https://docs.altimate.sh)). +## How it works -If altimate-code is not on PATH or not configured, the plugin surfaces the failure with fix instructions rather than silently falling back to Claude's native tools. +The plugin's `.mcp.json` registers the `altimate-code` stdio server by running +`altimate-code mcp serve`, without `--allow-write`. Claude calls these tools directly: -## How it works +| Tool | Purpose | +|---|---| +| `warehouse_list` | List available connections; for local databases also tables, columns and a sample row. | +| `warehouse_add` | Add a connection when none is configured or one is missing. | +| `sql_execute` | Execute SQL, read-only by default; `queries` batches independent queries and `tables` returns columns and value profiles (frequency-ranked values, distinct/null counts, unique-in-sample flags, value shapes, MongoDB nested paths) in the same call. Large results spill to a local file path. | +| `sql_materialize` | Copy a read-only query result from any connection into session-local `scratch` DuckDB for cross-database joins. | +| `answer_commit` | Finish a data question with one field per requested item. | + +`altimate-code mcp serve --all-tools` also exposes `schema_inspect` and `sql_check`. + +For a data question, Claude lists connections, inspects schemas and value profiles, +computes in SQL, checks correctness where needed, and returns the requested values +with a one-line basis. For cross-connection joins, it materializes the smaller +filtered side and other required inputs into `scratch`, then joins there. + +The routing skill and `/altimate-code:altimate ` prefer this direct +path for answers, numbers, and lists when the MCP tools are available in the +session. If the server is missing or fails to start, they delegate data questions +with `--agent analyst`. Long jobs and capabilities outside the five MCP tools use +`altimate-code run` with persona selection (`analyst` or `builder`) +and a private output file. The plugin tells you which path it uses. +Delegated jobs use the CLI's separate LLM provider, +costs, and rate limits. `/review` retains the specialized dbt/SQL reviewer. +A short SessionStart hook describes these capabilities to Claude. + +## Connections + +The server uses normal altimate-code discovery: project and global +`.altimate-code/connections.json` files, and `ALTIMATE_CODE_CONN_*` environment +variables. Launch Claude Code in the intended project and make any connection +environment variables available to its MCP subprocess. + +To select a connections file explicitly, change the server's `args` in +`plugins/altimate-code/.mcp.json` (or the installed plugin's `.mcp.json`) to: + +```json +["mcp", "serve", "--connections", "/absolute/path/to/connections.json"] +``` + +Use an absolute path to avoid working-directory ambiguity. Connection credentials +are database credentials; they are independent of an LLM provider configuration. -1. A **SessionStart hook** adds a static description of altimate-code's capabilities to the session, so Claude Code knows when a task fits. -2. When a data-engineering task fires the **skill** (or you invoke **`/altimate-code:altimate `** explicitly), Claude Code runs `altimate run ""` locally with its `builder` agent. -3. altimate-code plans and executes the task using your configured LLM provider. Warehouse queries, dbt commands, and file edits run **locally under your credentials**. -4. The result is written to a local output file and surfaced back in your Claude Code conversation. +## Read-only default + +The plugin does not pass `--allow-write`. Read-only execution is **database-enforced +on Postgres, SQLite, and DuckDB**. Elsewhere it is **SQL-classification-only**; +use a read-only DB user to enforce the boundary in the database. This default is +not a universal database permission guarantee. The CLI supports `--allow-write` +for explicitly enabling writes, but this plugin does not enable it. + +`sql_materialize` copies read-only source query results into session-local +`scratch` DuckDB; that local analytical storage does not modify the source +databases. Large results can also be written to local spill files. ## Use an Altimate workspace @@ -56,24 +113,33 @@ What altimate-code learns during these tasks is saved to the workspace's memory ## Example prompts -Once installed, try these in Claude Code (or prefix any of them with `/altimate-code:altimate`): - -1. **Column-level lineage** — *"Trace the `revenue_usd` column in `models/marts/fct_revenue.sql` back to its sources, and list every downstream model that would be affected if I change its rounding."* -2. **Warehouse cost analysis** — *"Give me a cost report for our Snowflake account: the ten most expensive queries this month and any warehouses that look over-provisioned."* -3. **Cross-dialect validation** — *"Compare `prod.orders` in Snowflake with `analytics.orders` in BigQuery row-by-row using `id` as the key, and summarize any mismatches."* -4. **dbt test generation** — *"Generate dbt tests for `models/staging/stg_orders.sql`, including unit tests for the CASE/WHEN logic."* +- "How many orders were completed last month? Return the count and total revenue." +- "Join customer activity across our two connections and list the ten most active customers." +- "/altimate-code:altimate Build and test a dbt staging project for these sources." +- "/altimate-code:altimate Produce a warehouse FinOps report with recommendations." +- "/review Review my dbt changes." ## Data handling -Delegating a task passes your prompt text to the altimate-code CLI, which sends it to your configured LLM provider — the Altimate LLM Gateway by default, or your own provider (BYOK), in which case Altimate never sees it. Warehouse credentials and query results stay on your machine. +MCP tools run locally under your database credentials. Tool results, including +sampled values and query results Claude reads, enter the Claude Code conversation +and are handled by Claude Code's configured model/provider. The MCP server makes +no separate LLM calls. Scratch data and spilled results are local artifacts. + +Delegation passes your task to `altimate-code run`; its own configured LLM +provider handles the task and any data supplied to that agent. This is a separate +provider and billing path from direct MCP use. -Full details: **[PRIVACY.md](../../PRIVACY.md)** · Security policy and disclosure: **[SECURITY.md](../../SECURITY.md)** · Terms: **[TERMS.md](../../TERMS.md)** +See **[PRIVACY.md](../../PRIVACY.md)** for MCP and delegation data flows; +**[SECURITY.md](../../SECURITY.md)** and **[TERMS.md](../../TERMS.md)** also apply. ## Troubleshooting | Symptom | Fix | |---|---| -| Neither `altimate-code` nor `altimate` on PATH | `npm install -g altimate-code` (Node 20+) or `curl -fsSL https://www.altimate.sh/install \| bash`, then run `altimate` once to configure your provider. | +| Neither `altimate-code` nor `altimate` on PATH | `npm install -g altimate-code` (Node 20+) or `curl -fsSL https://www.altimate.sh/install \| bash`, then run `altimate` once to configure your provider. Direct MCP tools additionally require a build with `mcp serve`. | +| Unknown `mcp` or `serve` command | The MCP server fails to start; data questions fall back to CLI analyst delegation. Configure the CLI's LLM provider for delegation, or use a build containing `mcp serve` for direct MCP tools. | +| No connections / database access error | Check project/global connection files, `ALTIMATE_CODE_CONN_*` environment variables, and database permissions. | | `Unauthorized` / `No provider configured` | Run `altimate` (`altimate-code` on npm installs older than v0.7.1) to open the TUI and reconfigure your provider via `/connect`, or set the provider API key env var. | | Task hangs for several minutes | Open `altimate` (`altimate-code` on npm installs older than v0.7.1) to check for a pending prompt in the TUI, or re-run specifying a known-good model. | | Empty result | The task may be too ambiguous — restate with the target table, expected columns, or time window. | @@ -86,9 +152,12 @@ Still stuck? See [Support](#support). ## Components -- **Skill** — `skills/altimate-code/SKILL.md` — delegation logic and workspace guidance -- **Command** — `commands/altimate.md` — `/altimate-code:altimate` slash command for explicit delegation -- **Hook** — `hooks/hooks.json` — SessionStart capability description (static text only) +- **MCP server** — `.mcp.json` — direct stdio data tools +- **Analyst agent** — `agents/analyst.md` — read-only data analyst for the MCP tools +- **Routing skill** — `skills/altimate-code/SKILL.md` — direct questions or CLI delegation, workspace guidance +- **Review skill** — `skills/review/SKILL.md` — specialized dbt/SQL review +- **Commands** — `commands/altimate.md` (`/altimate-code:altimate`) and `commands/review.md` +- **Hook** — `hooks/hooks.json` and `hooks-handlers/session-start.sh` ## Support diff --git a/plugins/altimate-code/agents/analyst.md b/plugins/altimate-code/agents/analyst.md new file mode 100644 index 0000000..a3e4829 --- /dev/null +++ b/plugins/altimate-code/agents/analyst.md @@ -0,0 +1,12 @@ +--- +name: analyst +description: Read-only data analyst. Use as the main agent (`claude --agent altimate-code:analyst`) to answer data questions over connected warehouses with the altimate-code MCP tools, ending with a FINAL ANSWER line. +--- + +You are a read-only data analyst using the altimate-code MCP tools; follow the server's analyst method. Do not modify source data or files. + +- The server lists its connections at startup (`warehouse_list` refreshes them). None you need: find its details in the project (config, `.env`, database files) and `warehouse_add` it. +- Check stored values (`sql_execute` `tables`) before filtering or joining; every condition must filter something. Compute in the database; chain dependent queries, even across connections, in one `sql_execute` call (`IN ({{label.column}})`). +- When a phrase has two readings, compute both and choose by the question's own definitions. +- When a policy or rule decides the answer, read its full text and check each condition against the row's own fields and dates. +- End with one line `FINAL ANSWER: ` giving every item the request asks for, in order (an entity and its related item or count are both given), and nothing else on that line. `answer_commit` is optional; if you use it, reply with exactly its `FINAL ANSWER:` text. diff --git a/plugins/altimate-code/commands/altimate.md b/plugins/altimate-code/commands/altimate.md index 9feea86..88e7330 100644 --- a/plugins/altimate-code/commands/altimate.md +++ b/plugins/altimate-code/commands/altimate.md @@ -1,18 +1,38 @@ --- -description: Delegate a task to altimate-code, the specialised data-engineering CLI agent (warehouse access, column-level lineage, cross-DB, FinOps, query optimization, your Altimate workspace's skills and knowledge) +description: Prefer altimate-code MCP for data questions; delegate when unavailable and for other dbt, warehouse and Altimate workspace jobs. argument-hint: --- -The user explicitly invoked `/altimate-code:altimate` to delegate this task to altimate-code. You MUST run the task via the `altimate-code` CLI — do NOT attempt the work with native `Bash`/`Edit`/`Write` tools, and do not read the project's files first: altimate-code investigates the project itself. +The user invoked `/altimate-code:altimate` to use altimate-code for this task. For a data +question requesting answers, numbers, or lists, prefer the `altimate-code` MCP +tools when available in the session and follow the server's analysis method. +Claude Code does the reasoning; this path needs no CLI LLM provider. If the tools +are unavailable (server missing or failed to start), use the delegation workflow +below with `--agent analyst`. Released builds without `mcp serve` can still +delegate. Tell the user which path is being used and, for fallback, that MCP is +unavailable and delegation uses the CLI's separate configured LLM provider. -Workflow (follow in order, no skipping): +For a long multi-step job needing altimate-code's own agent (such as a dbt project +build, migration, or FinOps report), or a capability outside the five MCP tools +listed in the `altimate-code` skill, use the delegation workflow below. Tell the +user that CLI delegation is being used. + +Delegation workflow (follow in order): 1. **Verify altimate-code is installed.** There is no separate check: the run command in step 3 resolves the CLI first, ignoring aliases and shell functions, and exits 127 with `altimate-code CLI not found` before doing anything else. The CLI ships under two names: npm and Homebrew installs expose both `altimate` and `altimate-code`, while older curl and PowerShell installs expose only `altimate`. Either one is fine. If the run exits with `altimate-code CLI not found`, stop and tell the user: > altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) or `curl -fsSL https://www.altimate.sh/install | bash`, then run `altimate` once to configure your provider/warehouse auth, then re-run `/altimate-code:altimate `. 2. **Vague debug** ("X is broken") with no failure named: **stop — ask the user for the specific error before delegating.** -3. **Run altimate-code with the `builder` agent**, which has the warehouse tools, workspace skills and memory. Pass `$ARGUMENTS` through a + Use `--agent analyst` for a data question when MCP tools are unavailable; otherwise use `--agent builder`, which has the warehouse tools, workspace skills and memory. + +3. **Run altimate-code with the chosen agent.** Generate a fresh delimiter per + call, such as `ALTIMATE_TASK_`, and check that it does not occur as + a standalone line in the complete task. Regenerate it if it does. Replace both + occurrences of `ALTIMATE_TASK_` in each template below with that + checked delimiter; keep the opening delimiter single-quoted (no shell + expansion). Insert the actual `$ARGUMENTS` text verbatim into the body before + execution. Pass it through a here-doc into a variable so the shell never command-substitutes anything the user typed, write the result to a private `mktemp` file (not a shared `/tmp/altimate-result.md` — concurrent invocations clobber each other and a @@ -20,9 +40,9 @@ Workflow (follow in order, no skipping): from `/dev/null` (`altimate-code run` reads piped stdin as part of the task, and this shell leaves stdin open): ```bash - TASK="$(cat <<'ALTIMATE_TASK' + TASK="$(cat <<'ALTIMATE_TASK_' $ARGUMENTS - ALTIMATE_TASK + ALTIMATE_TASK_ )" for ALTIMATE_NAME in altimate altimate-code; do ALTIMATE_BIN="$(unalias "$ALTIMATE_NAME" 2>/dev/null; unset -f "$ALTIMATE_NAME" 2>/dev/null; command -v "$ALTIMATE_NAME")" @@ -32,7 +52,7 @@ Workflow (follow in order, no skipping): umask 077 OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" "$ALTIMATE_BIN" run "$TASK" \ - --agent builder \ + --agent \ --yolo \ --output "$OUTPUT_FILE" \ --dir "$(pwd)" \ @@ -42,9 +62,9 @@ Workflow (follow in order, no skipping): **If this is a follow-up task in the same project** (the user invoked `/altimate-code:altimate` already in this conversation about the same dbt project / warehouse / data context), add `--continue` to resume the warm session — cache is hot, follow-on cost is materially lower: ```bash - TASK="$(cat <<'ALTIMATE_TASK' + TASK="$(cat <<'ALTIMATE_TASK_' $ARGUMENTS - ALTIMATE_TASK + ALTIMATE_TASK_ )" for ALTIMATE_NAME in altimate altimate-code; do ALTIMATE_BIN="$(unalias "$ALTIMATE_NAME" 2>/dev/null; unset -f "$ALTIMATE_NAME" 2>/dev/null; command -v "$ALTIMATE_NAME")" @@ -54,7 +74,7 @@ Workflow (follow in order, no skipping): umask 077 OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" "$ALTIMATE_BIN" run "$TASK" \ - --agent builder \ + --agent \ --yolo --output "$OUTPUT_FILE" --dir "$(pwd)" \ --continue \ < /dev/null @@ -68,4 +88,4 @@ Workflow (follow in order, no skipping): 5. **On any altimate-code error** (`Unauthorized`, `Token limit reached`, `No provider configured`, `Not signed in to Altimate`, warehouse credentials wrong, process timeout) — surface the error message to the user along with the fix from the skill body's failure-modes table. Do NOT fall back to native tools. The user invoked `/altimate-code:altimate` specifically to use altimate-code; falling back would defeat the purpose. -Task to delegate: $ARGUMENTS +Task: $ARGUMENTS diff --git a/plugins/altimate-code/hooks-handlers/session-start.sh b/plugins/altimate-code/hooks-handlers/session-start.sh index dd883a7..d6240d3 100755 --- a/plugins/altimate-code/hooks-handlers/session-start.sh +++ b/plugins/altimate-code/hooks-handlers/session-start.sh @@ -1,16 +1,11 @@ #!/usr/bin/env bash -# SessionStart hook for the altimate-code plugin. Emits a descriptive statement -# of the altimate-code skill's capabilities so Claude can route to it when the -# task shape fits. Deliberately descriptive rather than imperative — see the -# Claude plugin review-criteria checklist items on "avoid instructing Claude -# to call other tools" and "don't interfere with tool sequencing." -# -# Uses printf (not a here-doc) so the hook works in restricted sandboxes that -# refuse to create the temporary file a here-doc needs. +# Static SessionStart routing guidance. printf works in sandboxes that +# refuse the temporary files a here-doc can require. printf '%s\n' '{' printf ' "hookSpecificOutput": {\n' printf ' "hookEventName": "SessionStart",\n' -printf ' "additionalContext": "The altimate-code plugin ships two skills in this session. (1) The `altimate-code` skill routes data-engineering work to the altimate-code CLI — column-level lineage, downstream-impact, cross-database validation, FinOps, PII from sampled rows, query cost attribution, schema diffs, dev-vs-prod diffing. In a project linked to an Altimate workspace it also answers from the shared skills, knowledge and memory of that workspace, so questions about team conventions, standards or best practices fit it too. It is not well-suited for pure file/code edits to dbt models and SQL files that do not touch warehouse state — native Bash/Edit/Write handles those faster. (2) The `review` skill runs the altimate-code dbt PR reviewer on dbt project changes (models/**.sql, schema.yml, dbt_project.yml, sources.yml, macros, snapshots, seeds). It emits a signed verdict envelope with column lineage, query equivalence, dbt anti-pattern detection, and PII screening — none of which native tools or a generic code-review skill can compute. When the user asks to review dbt / SQL / warehouse changes, this is the specialized reviewer available. For non-dbt code review (TypeScript, Python, Go), the `review` skill declines."\n' +# shellcheck disable=SC2016 +printf ' "additionalContext": "altimate-code: answer data questions with its MCP tools yourself; for dbt/SQL edits, warehouse-state jobs, questions about the team'"'"'s Altimate workspace knowledge and conventions, or when MCP is unavailable, delegate with `altimate-code run` (altimate-code skill; /review for dbt/SQL PRs)."\n' printf ' }\n' printf '}\n' diff --git a/plugins/altimate-code/hooks/hooks.json b/plugins/altimate-code/hooks/hooks.json index 10999b0..e554842 100644 --- a/plugins/altimate-code/hooks/hooks.json +++ b/plugins/altimate-code/hooks/hooks.json @@ -1,5 +1,5 @@ { - "description": "SessionStart nudge directing the agent to delegate data-engineering tasks to altimate-code via the altimate-code skill. The UserPromptSubmit pre-run hook was removed because it double-invoked altimate-code (once at hook time, once when the model fired the skill), doubling token consumption on the altimate-gateway without improving delegation rate — the skill body + SessionStart directive already route the model to altimate-code reliably.", + "description": "SessionStart capability description: direct MCP tools for data questions, CLI delegation for long jobs, and the specialized dbt/SQL reviewer.", "hooks": { "SessionStart": [ { diff --git a/plugins/altimate-code/skills/altimate-code/SKILL.md b/plugins/altimate-code/skills/altimate-code/SKILL.md index 1537fcf..ade7e89 100644 --- a/plugins/altimate-code/skills/altimate-code/SKILL.md +++ b/plugins/altimate-code/skills/altimate-code/SKILL.md @@ -1,53 +1,73 @@ --- name: altimate-code 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. Also suited for questions about the team's own - data conventions, standards, best practices, knowledge base or shared - memory, and for anything the user calls their Altimate workspace: in a - project linked to an Altimate workspace, altimate-code answers from that - workspace's skills, knowledge and memory, which native tools cannot read. - The skill routes to a purpose-built CLI, so it covers workloads that touch - live data, lineage, warehouse state or team knowledge more directly than - native file-editing tools do. + Delegate long dbt and warehouse jobs to the altimate-code CLI (builds, migrations, FinOps, lineage, impact, schema diff, parity, PII, cost, SCD2 checks, docs, env diffs), questions about the team's Altimate workspace knowledge and conventions, or data questions when its MCP tools are unavailable. --- # altimate-code -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. - -## You MUST follow this workflow - -1. **Verify altimate-code is on PATH.** There is no separate check: the invocation below resolves the CLI first, ignoring aliases and shell functions, and exits 127 with `altimate-code CLI not found` before doing anything else. The CLI ships under two names: npm and Homebrew installs expose both `altimate` and `altimate-code`, while older curl and PowerShell installs expose only `altimate`. Either name is the same CLI. If the invocation exits with `altimate-code CLI not found`, jump to "Failure modes" 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. - -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. +Choose the path from the requested outcome, including when invoked via `/altimate-code:altimate`. + +## Data questions: prefer MCP tools, otherwise delegate + +For answers, numbers, or lists over warehouse data, use the `altimate-code` MCP +server yourself when its tools are available in the session; the server's +instructions give the analysis method. The tools are +`warehouse_list`, `warehouse_add`, `sql_execute` (with `tables` for schemas), `sql_materialize`, and `answer_commit` (optional). +Claude Code does the reasoning; this server runs no LLM and needs no separate +LLM-provider configuration. Tell the user that the MCP path is being used. + +The server is read-only by default for source databases. Postgres, SQLite, and +DuckDB enforce read-only access at the database level; other databases rely on +SQL classification, so use a read-only DB user. `sql_materialize` writes only to +session-local `scratch` DuckDB for analysis. Large query results may spill to a +local file path; read the needed results there before answering. + +If the MCP tools are unavailable in the session (server missing or failed to +start), tell the user that MCP is unavailable and that you are using CLI +delegation with its separate configured LLM provider. Follow the invocation +workflow below with `--agent analyst`. Released altimate-code builds without +`mcp serve` can still use this delegation path. If an available tool fails, +report that error; do not invent results. Use native file-reading tools as needed +to read local result files. + +## Other capabilities and long jobs: delegate to the CLI agent + +Use `altimate-code run` for long multi-step jobs needing its own agent, such as +building a dbt project, migrations, or a FinOps report. Also delegate capabilities +outside the five MCP tools: column-level lineage, downstream impact, schema diff, +data parity, PII detection, query cost attribution, query optimization, +incremental/SCD2 verification, model docs, and dev-vs-prod diffs. Questions about +the team's own conventions, standards, knowledge or shared memory, and anything the +user calls their Altimate workspace, also belong to the CLI: in a project linked to +an Altimate workspace it answers from that workspace's skills, knowledge and memory, +which native tools cannot read. Tell the user that CLI delegation is being used. +Pass the user's task verbatim using the safe invocation below, then read and +present the output. Delegation uses altimate-code's own configured LLM provider, +costs, and rate limits. ## Invocation +There is no separate install check: the invocation below resolves the CLI first, ignoring aliases and shell functions, and exits 127 with `altimate-code CLI not found` before doing anything else. The CLI ships under two names: npm and Homebrew installs expose both `altimate` and `altimate-code`, while older curl and PowerShell installs expose only `altimate`. Either name is the same CLI. If the invocation exits with `altimate-code CLI not found`, jump to "Failure modes" below and stop. + **Vague debug** ("X is broken", "make it work", "fix this") with no failure named: **don't delegate yet.** Ask the user for the specific error message or symptom first. -Otherwise, run the task with the `builder` agent. It has the warehouse tools, loads the linked workspace's skills and saves to its memory. +Pick the agent: `analyst` for a data question when the MCP tools are unavailable; otherwise `builder`, which has the warehouse tools, loads the linked workspace's skills and saves to its memory. -Pass the task through a here-doc into a variable so the shell never +Generate a fresh delimiter per call, such as `ALTIMATE_TASK_`, and +check that it does not occur as a standalone line in the complete task. Regenerate +it if it does. Replace both occurrences of `ALTIMATE_TASK_` in each +template below with that checked delimiter; keep the opening delimiter +single-quoted (no shell expansion). Pass the task through a quoted 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 -TASK="$(cat <<'ALTIMATE_TASK' +TASK="$(cat <<'ALTIMATE_TASK_' -ALTIMATE_TASK +ALTIMATE_TASK_ )" for ALTIMATE_NAME in altimate altimate-code; do ALTIMATE_BIN="$(unalias "$ALTIMATE_NAME" 2>/dev/null; unset -f "$ALTIMATE_NAME" 2>/dev/null; command -v "$ALTIMATE_NAME")" @@ -57,7 +77,7 @@ done umask 077 OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" "$ALTIMATE_BIN" run "$TASK" \ - --agent builder \ + --agent \ --yolo \ --output "$OUTPUT_FILE" \ --dir "$(pwd)" \ @@ -70,7 +90,7 @@ Then `Read "$OUTPUT_FILE"` and emit its contents to the user without re-summaris | Flag | Why it is required | |---|---| -| `--agent builder` | The agent with the warehouse tools, workspace skills and memory. Other agents lack some of these. | +| `--agent ` | `analyst` for the MCP-unavailable data-question fallback, `builder` for everything else (it has the warehouse tools, workspace skills and memory). | | `--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, the linked workspace, etc. | @@ -83,9 +103,9 @@ Each Bash call starts a fresh shell, so keep the `ALTIMATE_BIN` resolver loop in 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 -TASK="$(cat <<'ALTIMATE_TASK' +TASK="$(cat <<'ALTIMATE_TASK_' -ALTIMATE_TASK +ALTIMATE_TASK_ )" for ALTIMATE_NAME in altimate altimate-code; do ALTIMATE_BIN="$(unalias "$ALTIMATE_NAME" 2>/dev/null; unset -f "$ALTIMATE_NAME" 2>/dev/null; command -v "$ALTIMATE_NAME")" @@ -95,7 +115,7 @@ done umask 077 OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" "$ALTIMATE_BIN" run "$TASK" \ - --agent builder \ + --agent \ --yolo \ --output "$OUTPUT_FILE" \ --dir "$(pwd)" \ @@ -103,9 +123,7 @@ OUTPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/altimate-result.XXXXXX")" < /dev/null ``` -`--continue` resumes the most recent session in this directory. 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. - -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. +`--continue` resumes the most recent session in this directory. 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. If the user starts a clearly unrelated workflow (different project, different schema, different debugging thread), drop `--continue` and start fresh. ## Altimate workspaces @@ -131,13 +149,14 @@ Commands the user types after `!` use `altimate`; on npm installs older than v0. What altimate-code learns during delegated tasks is saved to the workspace's memory and shared with the team in the CLI, the IDE and Studio. -## Failure modes — route every one to the user +## Failure modes -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." +If `altimate-code run` fails, report the error and stop that delegation; do not +silently replace it with native edits or warehouse commands. -| Symptom | What to tell the user — verbatim | +| Symptom | What to tell the user | |---|---| -| `altimate-code CLI not found` (neither `altimate` nor `altimate-code` on PATH) | "altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) or `curl -fsSL https://www.altimate.sh/install \| bash`, then run `altimate` once to configure auth. Then re-run your request." | +| `altimate-code CLI not found` (neither `altimate` nor `altimate-code` on PATH; MCP tools additionally need a build with `mcp serve`) | "altimate-code is not installed. Install with `npm install -g altimate-code` (Node 20+) or `curl -fsSL https://www.altimate.sh/install \| bash`, then run `altimate` 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` (`altimate-code` on npm installs older than v0.7.1) in your terminal to open the TUI and reconfigure your provider, or sign in to Altimate with `altimate auth login -p altimate-backend --method 'Altimate LLM Gateway'`, then re-run your request." | | `Not signed in to Altimate` | "altimate-code is not signed in to Altimate, so it cannot reach your workspace. Run `! altimate auth login -p altimate-backend --method 'Altimate LLM Gateway'` (`altimate-code` on npm installs older than v0.7.1), sign in in the browser, then re-run your request." | | `not in the workspace yet` (stderr) | Present the result as usual, then add: "altimate-code saved what it learned on this machine, but it has not reached your workspace yet. Run `! altimate workspace sync` (`altimate-code` on npm installs older than v0.7.1) to send it." | @@ -146,10 +165,10 @@ When altimate-code returns an error, **report the error to the user and STOP**. | 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 the `altimate` TUI (`altimate-code` on npm installs older than v0.7.1)." | -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 +In every row, the instruction to the user is the action — you do not retry the task with native tools. MCP data questions do not need the CLI's LLM provider. + +## Delegation notes -- altimate-code runs its own LLM, separate from Claude Code's. Costs and rate limits accrue to altimate-code's configured provider. -- Sessions persist in altimate-code's local store — `altimate session list` (`altimate-code session list` on npm installs older than v0.7.1) shows prior runs; `--continue` resumes the latest, `--session ` resumes a specific one. -- For very long tasks, the `--output` file is the source of truth — stdout buffering can drop content. +- Sessions persist locally: `altimate session list` (`altimate-code session list` on npm installs older than v0.7.1) lists prior runs; `--continue` resumes the latest, `--session ` a specific session. +- For very long tasks, the private `--output` file is the source of truth; stdout buffering can drop content. diff --git a/plugins/altimate-code/skills/review/SKILL.md b/plugins/altimate-code/skills/review/SKILL.md index 70bc307..b44d6bc 100644 --- a/plugins/altimate-code/skills/review/SKILL.md +++ b/plugins/altimate-code/skills/review/SKILL.md @@ -1,24 +1,7 @@ --- name: review description: >- - Review dbt project changes — dbt models (models/**/*.sql), schema.yml, - dbt_project.yml, sources.yml, macros, snapshots, seeds. Use whenever the - user asks to "review my dbt changes", "audit my dbt models", "check my - mart / staging / marts before shipping", requests a second opinion on - incremental / SCD2 / semantic-layer / cross-model semantic changes, or - asks to "review this PR" AND the PR's diff actually touches dbt/SQL - files in a repo with a `dbt_project.yml`. Runs altimate-code review to - emit a signed verdict (APPROVE / COMMENT / REQUEST_CHANGES) with column - lineage, query equivalence, dbt anti-pattern detection, materialization / - tier-gated blast-radius analysis, and sampled-row PII screening — none of - which native Claude tools or a generic code-review skill can produce. - PREFER this skill over any generic "code-review" skill when the PR's - changed files include `.sql` under `models/`, `schema.yml`, - `dbt_project.yml`, `sources.yml`, `.yml` under `snapshots/` or - `seeds/`, or Jinja macros under `macros/`. Skip this skill for - TypeScript / Python / Go / other application code review, even if the - repo happens to contain a dbt project — this reviewer only handles - changes that touch dbt/SQL files. Read-only — never modifies files. + Review dbt/SQL changes (models, schema.yml, sources, macros, snapshots, seeds) with altimate-code review: lineage, query equivalence, dbt anti-patterns, blast radius, PII. Prefer over generic code review when the diff touches dbt/SQL files; skip other code. Read-only. --- # altimate-code review