agentleFS
AltimateAIAltimateAI/vscode-dbt-power-user/.claude/skills/dev-workflow/SKILL.md

dev-workflow

Skill586 starsChanged 7 months agoMITView on GitHub

End-to-end development workflow — build, deploy to Docker code-server, verify with Playwright, and iterate with hot-reload

  • Reads credentials
  • Installs packages

34 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use retrospective, brainstorm and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    retrospective

    Review how work went and improve the next round. USE WHEN asked for a retro, delays, or process lessons. DO NOT USE for code review or transcript replay.

    Also in 3 projects that use this

  • nicolasestremSkill

    brainstorm

    Structured idea generation and solution exploration with systematic analysis.

    Also in 4 projects that use this

  • GitHubSkill

    refactor

    Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.

    Also in 4 projects that use this

  • HashiCorpSkill

    changelog

    Add a `.changelog/<PR_NUMBER>.txt` entry for a GitHub Pull Request, commit, and push.

    Also in 3 projects that use this

  • VercelSkill

    deploy

    Deploy applications to Vercel. Use when the user says "deploy", "deploy to Vercel", "push to production", "deploy my app", or "go live".

    Also in 3 projects that use this

  • GoogleSkill

    improve-codebase-architecture

    Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. 0 are common, 14 are distinctive, and 11 are very specific to this project.

  • 0

    Common

    Most of the 24 edited versions we read keep these.

  • 14

    Distinctive

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the deploy script (runs in foreground with watch mode):

    line 20
  2. Very specific:

    Check docker-setup/.env exists (prompts for DBT_PROJECT_PATH if not)

    line 27
  3. Distinctive:

    Stop existing container, rebuild Docker image, start new container

    line 29
  4. Distinctive:

    Wait for code-server to be ready at http://localhost:3001

    line 30
  5. Very specific:

    Start yarn rspack build --watch for automatic recompilation

    line 31
  6. Distinctive:

    Use the Playwright MCP tools to verify the extension loads:

    line 40
  7. Distinctive:

    Wait 8 seconds for code-server to fully initialize

    line 43
  8. Distinctive:

    If a trust dialog appears ("Do you trust the authors?"), click "Yes, I trust the authors"

    line 44
  9. Distinctive:

    Verify the extension UI loads inside the iframe (look for heading text, buttons, etc.)

    line 48
  10. Distinctive:

    Look for log entries from the MCP engine

    line 53
  11. Very specific:

    Reload code-server using Playwright: use browser_navigate to http://localhost:3001/?folder=/home/coder/project — do NOT use the command …

    line 60
  12. Distinctive:

    Wait 8 seconds for re-initialization

    line 61
  13. Distinctive:

    Verify the change in the Output > Datamate channel or UI

    line 62
  14. Distinctive:

    IMPORTANT: Always reload by navigating to the URL again.

    line 64
  15. Very specific:

    When opening a folder in code-server for the first time, a "Do you trust the authors?" dialog appears.

    line 83
  16. Very specific:

    If port 3001 is already in use: yarn docker:stop first.

    line 92
  17. Very specific:

    After any rspack/webpack rebuild, always use docker compose up --build -d (or yarn docker:deploy), never docker compose restart.

    line 95
  18. Very specific:

    If changes don't appear after up --build, force a clean build:

    line 98
  19. Distinctive:

    When using Playwright MCP to verify the extension, follow this exact sequence to minimize tool calls:

    line 108
  20. Distinctive:

    When testing multiple branches simultaneously, each needs its own container:

    line 163
  21. Distinctive:

    After replacing the binary, you may need to clean stale state:

    line 221
  22. Very specific:

    Leave DBT_PROJECT_PATH unset and open the container copy directly:

    line 275
  23. Very specific:

    The volume-mount fallback doesn't land on a fixture: If DBT_PROJECT_PATH is unset, compose mounts a host path that usually doesn't exist, …

    line 295
  24. Very specific:

    Extension not loading in sandbox: Check symlink at ~/.local/share/code-server/extensions/vscode-dbt-power-user and that dist/extension.js …

    line 361
  25. Very specific:

    MCP server not starting: Verify altimate.onboardedMcpServer: true in code-server settings.

    line 363

“Common” is measured: kept by at least 6 in 10 of the 24 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Docker Testing Workflow

You are helping the user develop and test the Datamates VS Code extension. The workflow involves making code changes in either the extension or the MCP engine repo, auto-building via rspack watch mode, deploying to a Docker code-server container, and verifying changes using Playwright MCP.

Architecture

Two linked repositories:

  • vscode-dbt-power-user (this repo) — the VS Code extension

The extension is volume-mounted into the container (no VSIX). The repo is mounted read-only at /home/coder/extension-src, and a symlink connects it to the code-server extensions directory.

Step 1: Deploy

Run the deploy script (runs in foreground with watch mode):

yarn docker:deploy

This will:

  1. Check docker-setup/.env exists (prompts for DBT_PROJECT_PATH if not)
  2. Build the extension with yarn rspack build
  3. Stop existing container, rebuild Docker image, start new container
  4. Wait for code-server to be ready at http://localhost:3001
  5. Start yarn rspack build --watch for automatic recompilation

Since deploy enters watch mode, run it in the background when using Claude:

cd /Users/saravananshanmugam/Desktop/projects/altimate/vscode-dbt-power-user && yarn docker:deploy

Step 2: Verify with Playwright MCP

Use the Playwright MCP tools to verify the extension loads:

  1. Navigate to http://localhost:3001/?folder=/home/coder/project
  2. Wait 8 seconds for code-server to fully initialize
  3. If a trust dialog appears ("Do you trust the authors?"), click "Yes, I trust the authors"
  4. Click "Toggle Panel (⌘J)" button to open the bottom panel
  5. The "Datamates" tab may be under "Additional Views" overflow menu — check there if not visible
  6. Click the "Datamates" tab
  7. Verify the extension UI loads inside the iframe (look for heading text, buttons, etc.)

To check engine-side logs:

  1. Click the "Output" tab in the bottom panel
  2. Select "Datamate" from the output channel dropdown
  3. Look for log entries from the MCP engine

Step 3: Hot-Reload After Code Changes

The watcher automatically recompiles when files change in either repo (~350-400ms). To pick up changes in code-server:

  1. Save your code change (watcher auto-rebuilds)
  2. Reload code-server using Playwright: use browser_navigate to http://localhost:3001/?folder=/home/coder/project — do NOT use the command palette approach
  3. Wait 8 seconds for re-initialization
  4. Verify the change in the Output > Datamate channel or UI

IMPORTANT: Always reload by navigating to the URL again. Do NOT open the command palette to run "Developer: Reload Window" — it's slower and more fragile.

How It Works

  • No VSIX: The Dockerfile does not build or install a VSIX. The extension source is mounted as a Docker volume.
  • Volume mount: docker-compose.yml mounts the repo at /home/coder/extension-src:ro
  • Symlink: start-code-server.sh creates a symlink from /home/coder/.local/share/code-server/extensions/vscode-dbt-power-user → /home/coder/extension-src
  • Watch mode: deploy.sh enters yarn rspack build --watch after the container is ready, so code changes in either repo are auto-compiled
  • Settings injection: start-code-server.sh sets altimate.onboardedMcpServer: true in user settings to skip onboarding

Gotchas

Watch mode covers both repos

Changes to vscode-dbt-power-user trigger a rebuild. No need to rebuild manually.

Engine linking

The engine link requires modifications to rspack.config.js and tsconfig.json. See docs/development.md → "Manual" section for the exact diff. If these files revert to their normal state, the engine will be pulled from node_modules instead of the local path.

Trust dialog on first open

When opening a folder in code-server for the first time, a "Do you trust the authors?" dialog appears. You must accept it before extensions activate fully. The --disable-workspace-trust flag should suppress this, but check if it appears.

Datamates tab location

The Datamates tab may appear directly in the bottom panel tabs, OR it may be hidden under the "Additional Views" overflow menu (the ... button). Check both.

Container auth disabled

code-server runs with --auth none. Do not expose port 3001 on public networks.

Port conflict

If port 3001 is already in use: yarn docker:stop first.

CRITICAL: Always up --build, never restart

After any rspack/webpack rebuild, always use docker compose up --build -d (or yarn docker:deploy), never docker compose restart. code-server caches extension state in memory — restart reuses the stale cache and the new bundle won't take effect. This causes tests to pass/fail inconsistently and wastes debugging time.

Docker build cache

If changes don't appear after up --build, force a clean build:

cd docker-setup && docker compose build --no-cache && docker compose up -d

deploy.sh blocks the terminal

yarn docker:deploy enters watch mode and doesn't return. When running from Claude, use run_in_background: true on the Bash tool, then check output with TaskOutput.

Efficient E2E Testing with Playwright MCP

When using Playwright MCP to verify the extension, follow this exact sequence to minimize tool calls:

1. Verify bundle (1 call):

grep -c "myKeyFunction" dist/extension.js

2. Deploy + seed (1 call — combine with &&):

docker compose -f docker-setup/docker-compose.yml up --build -d && \
for i in $(seq 1 15); do curl -sf http://localhost:3001/healthz > /dev/null 2>&1 && break; sleep 2; done && \
CID=$(docker ps -q --filter "name=docker-setup-code-server") && \
docker exec $CID bash -c 'cd /home/coder/project && dbt seed && dbt run'

3. Check activation via logs (1 call — NOT by clicking through the UI):

CID=$(docker ps -q --filter "name=docker-setup-code-server")
latest=$(docker exec $CID bash -c 'ls -td /home/coder/.local/share/code-server/logs/*/ | head -1')
docker exec $CID grep "innoverio\|altimateai\|removed" "${latest}remoteagent.log"

4. Navigate + wait (2 calls):

browser_navigate → http://localhost:3001/?folder=/home/coder/project
browser_wait_for → 20 seconds

5. Open file + execute + screenshot (5 calls):

Preferred: click file tree (Quick Open via Ctrl+P is unreliable in Playwright — sometimes the file doesn't open):

browser_evaluate →
  const items = document.querySelectorAll('[role="treeitem"]');
  const target = Array.from(items).find(i => i.getAttribute('aria-label') === 'test_query.sql');
  if (target) { target.click(); target.click(); } // double-click to pin tab
browser_wait_for → 2 seconds
browser_press_key → Control+Enter
browser_wait_for → 12 seconds
browser_take_screenshot

Fallback: Quick Open (retry if document title doesn't change):

browser_press_key → Control+P
browser_snapshot → find textbox ref
browser_type → ref=<textbox>, text='test_query.sql', submit=true
browser_press_key → Control+Enter (after 2s wait)
browser_take_screenshot (after 12s wait)

Total: ~10 tool calls per test, not 30+.

Multiple worktrees on same Docker setup

When testing multiple branches simultaneously, each needs its own container:

# Use -p for unique project names and different ports in docker-compose.override.yml
docker compose -p feature-a-e2e up --build -d  # port 3004
docker compose -p feature-b-e2e up --build -d  # port 3005

Without -p, containers from different worktrees share the same project name and collide.

Extension symlink gotchas

The symlink directory name must include the version suffix (e.g. innoverio.vscode-dbt-power-user-0.60.1). A bare name like innoverio.vscode-dbt-power-user gets re-marked as removed by code-server's obsolete scanner on every boot — even if extensions.json has the correct entry. The extensions.json registration is necessary but not sufficient without the versioned name.

Language mode timing

.sql files may open as "MS SQL" instead of "Jinja SQL" if the jinjahtml extension hasn't activated yet when the file opens. This is a race condition — jinjahtml maps .sql → jinja-sql but activation order varies. Workaround: reopen the file or manually switch language mode after extension activation.

Updating altimate-code in Docker

The Docker container installs @altimateai/altimate-code from npm. To test local changes from the altimate-code repo:

Build locally

cd /Users/saravananshanmugam/Desktop/projects/altimate/altimate-code

# Requires bun >= 1.3.10 (upgrade with: bun upgrade)
npx turbo build --filter=@altimateai/altimate-code

This produces platform-specific binaries in packages/opencode/dist/@altimateai/.

Replace binary in Docker

The installed binary is a compiled ELF at /usr/lib/node_modules/@altimateai/altimate-code/bin/.altimate-code. To replace it:

# 1. Copy the linux-arm64 binary (Docker runs on Colima aarch64)
docker cp /Users/saravananshanmugam/Desktop/projects/altimate/altimate-code/packages/opencode/dist/@altimateai/altimate-code-linux-arm64/bin/altimate docker-setup-code-server-1:/tmp/altimate-new

# 2. Kill running altimate-code processes (binary is "text file busy" otherwise)
docker exec -u root docker-setup-code-server-1 pkill -f 'altimate-code serve'

# 3. Remove old binary and copy new one
docker exec -u root docker-setup-code-server-1 bash -c "rm /usr/lib/node_modules/@altimateai/altimate-code/bin/.altimate-code && cp /tmp/altimate-new /usr/lib/node_modules/@altimateai/altimate-code/bin/.altimate-code && chmod +x /usr/lib/node_modules/@altimateai/altimate-code/bin/.altimate-code && rm /tmp/altimate-new"

# 4. Reload browser to restart extension (spawns new altimate-code process)

Note: The built binary altimate-code is a symlink to altimate — copy the altimate file, not the symlink.

Update from npm (no local changes)

docker exec -u root docker-setup-code-server-1 npm install -g @altimateai/altimate-code@latest

Clean state after update

After replacing the binary, you may need to clean stale state:

# Remove stale DB and config (fresh start)
docker exec docker-setup-code-server-1 rm -f \
  /home/coder/.local/share/altimate-code/opencode.db \
  /home/coder/.local/share/altimate-code/opencode.db-shm \
  /home/coder/.local/share/altimate-code/opencode.db-wal \
  /home/coder/project/config.json

Useful Commands

CommandDescription
yarn docker:deployFull build + deploy + watch mode
yarn docker:logsStream container logs
yarn docker:stopStop the container

Configuration

Stored in docker-setup/.env (gitignored):

VariableDescription
DBT_PROJECT_PATHAbsolute path to local dbt project directory, mounted at /home/coder/project. Leave unset to use the bundled test-fixtures/jaffle-shop-duckdb instead (see below).

To change: edit docker-setup/.env or delete it and run yarn docker:deploy to be re-prompted.

Test Fixtures

Two ready-to-use DuckDB projects are bundled in the repo under test-fixtures/:

FixtureProfileNotes
test-fixtures/jaffle-shop-duckdbjaffle_shopClassic dbt-labs jaffle-shop (customers, orders, payments)
test-fixtures/dbt-core-sample-duckdbdbt_core_sample_duckdbgo-sales sample with Python + SQL models, macros, snapshots

How the container uses them

start-code-server.sh copies both fixtures from the read-only /home/coder/extension-src mount into writable home dirs on first boot and runs dbt deps in each:

/home/coder/extension-src/test-fixtures/jaffle-shop-duckdb       →  /home/coder/jaffle-shop-duckdb
/home/coder/extension-src/test-fixtures/dbt-core-sample-duckdb   →  /home/coder/dbt-core-sample-duckdb

The Dockerfile pre-seeds ~/.dbt/profiles.yml with both profiles pointing at DuckDB files, so the fixtures work without any local setup — no warehouse credentials required.

Choosing which project to open

There are three common setups:

  1. Fastest smoke test — use a bundled fixture in-container (recommended for throwaway verification). Leave DBT_PROJECT_PATH unset and open the container copy directly:
    http://localhost:3001/?folder=/home/coder/jaffle-shop-duckdb
    http://localhost:3001/?folder=/home/coder/dbt-core-sample-duckdb
    Changes stay inside the container and are wiped when the volume is rebuilt.
  2. Point DBT_PROJECT_PATH at a fixture path on the host (when you want to edit the fixture and keep the change).
    # docker-setup/.env
    DBT_PROJECT_PATH=/absolute/path/to/vscode-dbt-power-user/test-fixtures/jaffle-shop-duckdb
    The fixture is mounted at /home/coder/project, so http://localhost:3001/?folder=/home/coder/project opens it. Edits land in the repo — commit or git checkout to reset.
  3. Point DBT_PROJECT_PATH at an unrelated real dbt project (for debugging user-reported issues). Same mechanism as #2 — the project is mounted at /home/coder/project.

Gotchas with fixtures

  • Fixture already has target/ committed. test-fixtures/jaffle-shop-duckdb/target/manifest.json is checked in so the extension has something to parse before the first dbt run. Running dbt will overwrite it; don't commit the churn.
  • dbt_core_sample_duckdb profile expects /home/coder/dbt-core-sample-duckdb/go_sales.db. That path only exists inside the container copy — running dbt against this fixture from the host mount (#2) will fail unless you also create go_sales.db locally.
  • The volume-mount fallback doesn't land on a fixture. If DBT_PROJECT_PATH is unset, compose mounts a host path that usually doesn't exist, and start-code-server.sh then opens /home/coder/jaffle_shop_duckdb (underscores), which also doesn't exist. Always either set DBT_PROJECT_PATH or navigate explicitly to /home/coder/jaffle-shop-duckdb (dashes).

Harness Sandbox Contract

This section is the machine-readable contract for the harness sandbox system. The CLI parses the YAML block below to render the pod template.

Two-phase sandbox lifecycle

PhaseMarker fileWhat's available
Phase 1: code-ready/workspace/.code-readySource code, node_modules, linters, tsc
Phase 2: server-ready/workspace/.server-readycode-server running on :3001, extension loaded

harness spawn returns at phase 1 (~5s with base image). Agent reads codebase while code-server starts (~30-60s for yarn compile + code-server boot).

repo: vscode-dbt-power-user
repo_url: https://github.com/AltimateAI/vscode-dbt-power-user.git
base_image: altimateacr.azurecr.io/vscode-dbt-power-user-base:latest
working_dir: /workspace/vscode-dbt-power-user
port: 3001
health_path: /healthz

provides:
  - name: CODE_SERVER_URL
    value: "http://sandbox-{{ sandbox_id }}.{{ namespace }}.svc.cluster.local:3001"

needs: []

sidecars: []

setup_commands:
  - name: enable-corepack
    cmd: corepack enable
  - name: install-root-deps
    cmd: yarn install --immutable 2>&1 | tail -5 || yarn install 2>&1 | tail -5
  - name: install-webview-deps
    cmd: cd webview_panels && (yarn install --immutable 2>&1 | tail -5 || yarn install 2>&1 | tail -5)
  - name: compile-extension
    cmd: yarn compile
  - name: setup-code-server-extension
    cmd: |
      EXT_DIR="$HOME/.local/share/code-server/extensions"
      mkdir -p "$EXT_DIR"
      ln -sf /workspace/vscode-dbt-power-user "$EXT_DIR/vscode-dbt-power-user"
  - name: setup-code-server-settings
    cmd: |
      SETTINGS_DIR="$HOME/.local/share/code-server/User"
      mkdir -p "$SETTINGS_DIR"
      if [ ! -f "$SETTINGS_DIR/settings.json" ]; then
        echo '{"altimate.onboardedMcpServer": true}' > "$SETTINGS_DIR/settings.json"
      fi

start_command: >
  code-server
  --bind-addr 0.0.0.0:3001
  --auth none
  --disable-telemetry
  --disable-workspace-trust
  --log debug

Sandbox troubleshooting

  • Extension not loading in sandbox: Check symlink at ~/.local/share/code-server/extensions/vscode-dbt-power-user and that dist/extension.js was built by yarn compile.
  • Slow phase 1: Base image may be stale. Rebuild with az acr build --registry altimateacr --image vscode-dbt-power-user-base:latest -f Dockerfile.base .
  • MCP server not starting: Verify altimate.onboardedMcpServer: true in code-server settings.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.