feat: add automatic Altimate data workflow as an isolated pilot

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     "url": "https://altimate.ai"
   },
   "metadata": {
-    "description": "Altimate's Claude Code plugin — delegates dbt and warehouse work to the altimate-code CLI agent.",
+    "description": "Altimate's Claude Code plugin \u2014 delegates dbt and warehouse work to the altimate-code CLI agent.",
     "version": "1.1.1"
   },
   "plugins": [
@@ -15,6 +15,12 @@
       "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.",
       "source": "./plugins/altimate-code",
       "strict": false
+    },
+    {
+      "name": "altimate-code-experimental",
+      "description": "Experimental automatic data workflow: workspace context, native MCP and SQL results inside Claude Code.",
+      "source": "./plugins/altimate-code-experimental",
+      "strict": false
     }
   ]
 }

.gitignore

@@ -0,0 +1,3 @@
+# Pilot binaries are packaged locally, never committed.
+plugins/altimate-code-experimental/runtime/
+__pycache__/

CONTRIBUTING.md

@@ -86,3 +86,11 @@ claude plugin install altimate-code@altimate-claude-plugin
 ## Reporting bugs / requesting features
 
 Please open a GitHub issue on this repo. For security-sensitive reports, see [SECURITY.md](./SECURITY.md).
+
+## Automatic experimental pilot
+
+The original `plugins/altimate-code` is preserved. Make automatic UX changes in `plugins/altimate-code-experimental`; its only semantic routing skill and SessionStart guidance must agree. UI and lifecycle code live in `hooks/data-workspace.mjs` and `hooks/data-mode.mjs`. Reusable workspace behavior belongs in altimate-code.
+
+Run `claude plugin test ./plugins/altimate-code-experimental`, and strict validation for the marketplace and both plugin directories. `tests/resolve-cli.sh` still verifies the original plugin's resolver. Package the experimental listing with `scripts/package-experimental.py`; its source registration must remain unchanged in the bundle. Do not commit runtime binaries. See `docs/workspace-data-mode.md` for installation, behavior changes and outstanding live-client verification.
+
+Use `tests/mod-smoke.py --automatic-pilot /absolute/plugin/path` for the automatic synthetic SQL comparison. It deliberately isolates server registration for equal arms; use `tests/packaged-runtime-smoke.py` to verify unchanged packaged registration. Workspace fixture routing remains a historical prototype test.

PRIVACY.md

@@ -74,3 +74,11 @@ We will update this document in this repository and revise the effective date wh
 
 Altimate Inc. · 440 North Wolfe Road #150, Sunnyvale, CA 94085, USA · +1 (650) 254-6266
 Privacy & general: **info@altimate.ai** · Security: **security@altimate.ai** · Support: **support@altimate.ai**
+
+## Experimental workspace workflow
+
+The separate experimental plugin reads bounded workspace context only when relevant data work requests it, rather than on every user prompt. Context includes workspace summary, skill names and project memory; it is returned to Claude and cached for up to 30 seconds with identity checks. Named skills and knowledge are retrieved on demand. Workspace SQL goes to the selected engine and retains warehouse costs; knowledge requests may invoke backend models.
+
+The first-use panel lists workspaces visible to the signed-in account. Explicit selection links this project without uploading existing memory. Sign-in and optional engine installation require explicit panel actions and use the native CLI. Authentication output is not inserted into model context.
+
+Explicit workspace inspection exposes a memory-save form; the user-only `/altimate-remember` shortcut is also available. Only the supplied text is saved locally and publication attempted for the displayed project/workspace receipt. Publication may invoke backend models. Failed or uncertain publication is reported without automatic retry. Context retrieval does not delete local memory. Normal Claude transcripts, local memory files and service retention policies apply to their respective data.

README.md

@@ -4,6 +4,10 @@ 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.
 
+## Unpublished automatic pilot
+
+A separate [altimate-code-experimental](plugins/altimate-code-experimental/) listing adds automatic data routing, first-use workspace setup and SQL results inside Claude Code. The original plugin and its marketplace entry remain unchanged from main. The pilot requires a platform-specific bundle with its compatible CLI; the Git source listing alone lacks that runtime. See [packaging, installation and verification limits](docs/workspace-data-mode.md). No default release or public pilot artifact is published by this draft.
+
 ## Install
 
 From Anthropic's plugin directory:

docs/data-workspace-experiment.md

@@ -0,0 +1,50 @@
+> Historical manual-prototype notes. The current implementation is the separate automatic experimental listing; see [current behavior and rollout](workspace-data-mode.md). Paths to the original plugin below describe the earlier prototype, not the preserved main listing.
+
+# Claude Code data workspace experiment
+
+2026-10-22. Draft, stacked on the direct MCP integration experiment. No rollout or merge recommendation yet.
+
+The mod adds a user-opened results pane and an executable SQL command. Claude still reasons over Altimate's existing MCP tools for natural-language tasks. The mod observes the original tool execution once and preserves its result; it adds no model requests, tools, prompt rewrites, filesystem writes, network requests, shell processes, or automatic warehouse queries. Existing SQL execution safety checks and result linting remain in the server.
+
+## Acceptance and scope
+
+- Natural-language query: no pane → `/altimate-data` opens a pane showing the existing query, connection, result and backend findings.
+- Known SQL: Markdown handoff/model turn → `/altimate-query <connection> <SQL>` executes the MCP tool directly with normal Claude Code permissions, then returns its text.
+- Missing MCP: direct command reports recovery and runs no query; existing routing/delegation behavior remains available separately.
+- Source mutation: default server refuses it; the mod never approves or retries it.
+- No mod: existing MCP tools continue to work. No new tools or automatic queries are required for the pane.
+- History: latest eight calls, in-memory previews only, cleared by `/clear`, clear button, conversation end (including resume/logout), session start or module reload. Closing the pane hides it. These limits do not change model-visible results or normal transcript retention.
+
+This does not migrate Altimate workspace memory/skills into Claude, provide a connection picker, implement another agent loop, or replace backend authorization. It supports the plugin's existing scoped `sql_execute` tool name, not arbitrary MCP servers with a similarly named tool.
+
+## Measurements
+
+Claude Code 2.1.307, Sonnet 5.5 (`claude-sonnet-5-5` as reported by the CLI), medium effort, three trials each of two questions. All arms received the same prompt and used a synthetic local SQLite table of 60 orders. Plain Claude had Bash/Read and could query with a local client. MCP and mod arms also had the same five Altimate tools and plugin instructions. MCP-only differs from mod by the `modules` entry in a copied hooks manifest. The server was the unreleased `mcp serve` implementation at `6dd2f27cba1d7dfbbab26fa89507521d49338f4a`, run from source with Bun, local integrations and an explicit connections file.
+
+| Arm | Correct | Runs using Altimate tools | Mean list-price $/run | Mean input tokens including cache reads/writes | Mean model requests | Median end-to-end seconds |
+|---|---:|---:|---:|---:|---:|---:|
+| Plain Claude | 6/6 | 0/6 | 0.01214 | 30,698 | 2 | 5.384 |
+| MCP only | 6/6 | 6/6 | 0.01491 | 50,258 | 3 | 6.803 |
+| MCP plus mod | 6/6 | 6/6 | 0.01531 | 50,913 | 3 | 5.826 |
+
+Input-token breakdown (mean fresh/cache-read/cache-write): plain 4 / 28,751 / 1,944; MCP 6 / 48,362 / 1,889; mod 6 / 48,941 / 1,965. Dollars are the CLI's reported list-price `total_cost_usd`, not an additional invoice on a subscription. `num_turns` counts model requests in these runs, not six separate user conversations per task. Wall time includes process/MCP startup. Each trial used a fresh session. Arms ran with at most three concurrent processes, in rotated submission order, sharing the provider's prompt cache. Costs and latency are cache-sensitive; this is a small feasibility comparison, not a statistically powered benchmark.
+
+For the explicit SQL command, the paid-order aggregate returned `40 | 12000` in 3.051 seconds end-to-end, with zero input/output tokens, zero model requests and $0 model cost. This is **not** an apples-to-apples natural-language accuracy comparison: the human supplied SQL. It demonstrates the executable workflow opportunity. It still incurs any database query costs; this fixture was local SQLite.
+
+The same command's attempted `DELETE` was refused with `Permission denied: sql_execute_write`; an independent SQLite read confirmed all 60 rows remained. A missing-server test returned `No query was run` without delegation. Headless commands ran through real Claude Code and the real MCP server, not API stubs.
+
+In a real Claude Code 2.1.307 terminal session, `/altimate-query` returned the paid-order totals, `/altimate-data` opened the pane with the connection, SQL and `40 | 12000`, Escape closed it, and `/clear` followed by reopening the pane showed the empty-state instructions. The terminal ran with the Team-plan built-in guard and normal tool permissions. Desktop and VS Code element trees were checked with the test kit; their actual painting was not observed. An early lifecycle implementation using `classic.SessionStart` was skipped by that guard; the final mod clears on `command.run` for `/clear` and on `session.end`, which also covers resuming another conversation.
+
+## Interpretation
+
+The results do not show a reasoning-cost win from the mod. Both MCP arms needed three model requests versus two for plain Claude. The mod was about 2.7% more expensive than MCP-only in this sample, which is too small and cache-sensitive to establish a regression or improvement. Natural-language accuracy was at ceiling. The mod's lower observed median latency is not enough evidence of a speed improvement.
+
+The useful new behavior is direct SQL execution without a model request and a native place to inspect results. Keep the draft for usability testing; do not replace the integration architecture or market cost/accuracy gains on these results. The next evaluation should use realistic multi-step warehouse work and human tasks such as finding a previous query/result, alongside model and warehouse cost measurements.
+
+## Reproduce
+
+Run `claude plugin test ./plugins/altimate-code`, then strict validation of both the repository and plugin. The offline tests stub tools; they cover transparent forwarding, one execution, permissions/errors, preview bounds, unrelated tools/panes, clearing while a query is running, and terminal/Desktop/VS Code element trees. These tests do not verify the apps' painting or a real permission dialog.
+
+`python3 tests/mod-smoke.py --claude-bin /absolute/path/to/claude --server-command '["altimate-code","mcp","serve"]' --trials 3 --output /tmp/mod-results.json` performs the synthetic workflow and comparison. `--smoke-only` runs direct commands without model requests. `--server-command` accepts a JSON argv array so a source invocation can be substituted without a shell. The CLI must contain `mcp serve`; released builds without it cannot run this test.
+
+The harness isolates ordinary settings and ambient MCPs. It explicitly registers the plugin's scoped server because `--strict-mcp-config` excludes plugin registrations too. It never uses real warehouse credentials. Raw result JSON stays at the output path you choose; the disposable fixture and copied plugins are deleted afterwards.

docs/workspace-data-mode-plan.md

@@ -0,0 +1,30 @@
+> Historical manual-prototype notes. The current implementation is the separate automatic experimental listing; see [current behavior and rollout](workspace-data-mode.md). Paths to the original plugin below describe the earlier prototype, not the preserved main listing.
+
+# Workspace data mode
+
+Extend the experimental plugin with an opt-in data mode. Claude remains the reasoning model; this work must not start `altimate run` or a second agent/model loop. Keep both product PRs draft.
+
+## Behavior changes
+
+1. `/altimate-mode on|off|status` opts the current conversation into routing data work through Altimate MCP. Ordinary prompts retain their text and attachments; a bounded context block describes the tools and current workspace. Mode starts off and resets on conversation end, resume, logout and `/clear`. Background notifications and subagent prompts are not rewritten.
+2. `/altimate-workspace` shows the current workspace and available workspaces. Selecting an existing workspace uses the existing link operation, with memory backfill disabled for that command. No workspace creation, replacement of an existing link, shared-memory upload or installation happens automatically. A failed or unsupported CLI gives recovery instructions rather than delegating to a model.
+3. An opt-in `mcp serve --workspace-tools` exposes workspace context, a named skill reader and the workspace engine's known read operations. The default five-tool server stays unchanged. The engine is pinned to the resolved workspace; account or binding changes invalidate its tools until restart. Knowledge queries use the existing engine's `ask_knowledge_base` capability, rather than a new knowledge implementation. Missing engine/authentication is reported independently of local SQL availability.
+4. Workspace context uses existing account-scoped summaries, skills and memory hydration. Context has hard size bounds. Retrieved content is data, not authority to change tools or publish memory. Skills are fetched on demand rather than injected in bulk.
+5. `/altimate-remember <id> <text>` is the explicit shared-memory action. It passes text as stdin to a new workspace CLI action; model tools cannot invoke this command through the mod. The CLI requires the expected workspace identity, saves one project memory using the existing store/sync path, and reports local persistence separately from cloud confirmation. No bulk sync is introduced.
+6. The existing SQL pane and zero-model direct SQL command keep their permission, single-execution, error and lifecycle behavior. Workspace context appears in the data-mode status output; results stay in the existing pane.
+
+## Repository split
+
+Claude commands, prompt routing and display belong in `altimate-claude-plugin`, extending PR #9. Reusable workspace context/skill/memory operations and MCP adapters belong in an isolated `altimate-code` worktree, stacked on PR #1543 because its MCP server is required. No changes to the dirty main checkout or another owner's branch.
+
+## Verification
+
+- Event tests: opt-in only; prompt/attachment/origin preservation; no routing of notifications; lifecycle resets; late asynchronous completions cannot restore context from an old conversation; absent MCP/old CLI errors; model cannot publish memory; explicit command content stays data.
+- Core tests: account/workspace changes refuse stale reads/calls/writes; invalid skill names and symlinks refused; context caps; missing/off/unlinked states; memory reports local/cloud results accurately; read engine allowlist excludes all mutations.
+- Existing mod suite and strict root/plugin validation.
+- Real Claude + synthetic SQLite smoke and natural-language routing/adoption measurement. Report accuracy, list-price cost, tokens, turns and wall time; do not claim a cost win from a warm-cache comparison.
+- Live workspace verification only if authenticated disposable workspace access is available. No production binding or memory writes as a test. Missing live proof remains an explicit limitation.
+
+## Cost and rollout
+
+No new automatic model calls. Enabling data mode adds bounded context and one workspace read per user turn, so it can add latency and tokens; measure these. Explicit warehouse and knowledge queries retain their service costs. An explicit memory save uses the existing backend memory extraction/sync path, which may invoke a backend model; call that out in documentation. All behavior remains experimental and opt-in.