Add Claude Code plugin for agentic migrations (plan/build/review/fix, parity, Ralph loops) by KhaledAufDB · Pull Request #2670 · databrickslabs/lakebridge · GitHub
Skip to content

Add Claude Code plugin for agentic migrations (plan/build/review/fix, parity, Ralph loops) - #2670

Open
KhaledAufDB wants to merge 1 commit into
databrickslabs:mainfrom
KhaledAufDB:feature/claude-code-agentic-plugin
Open

KhaledAufDB wants to merge 1 commit into
databrickslabs:mainfrom
KhaledAufDB:feature/claude-code-agentic-plugin

Conversation

@KhaledAufDB

Copy link
Copy Markdown

Changes

What does this PR do?

Adds a Claude Code plugin for Lakebridge, installable straight from this repository:

/plugin marketplace add databrickslabs/lakebridge
/plugin install lakebridge@lakebridge

Lakebridge's transpilers handle most SQL deterministically. Procedural code — stored procedures with cursors, temp tables, multi-step MERGE logic, dynamic SQL — still needs someone to finish the conversion, validate it against the legacy system and chase data differences. This plugin automates that loop with AI agents that drive the existing databricks labs lakebridge and databricks CLIs.

Type Name Purpose
Subagents migration-planner, migration-builder, migration-reviewer, migration-fixer Plan (reads source + runs transpile), build/deploy/run, read-only risk-tiered review with PASS/FAIL, fix
Skill migrate-object Orchestrates plan → build → review → fix for one object, with bounded retries and resumable session files
Skill parity-fix Schema first (reconcile schema), then per-layer counts, then key-level diffs (reconcile data), then root cause and fix
Skill run-and-monitor Runs a job, classifies failures, applies safe fixes, repairs the run — at most 3 iterations
Commands init, prime, ralph Scaffold migration.config.yml + queue; load context and check auth; prepare Ralph loops
Experts expert-lakebridge, expert-databricks, expert-tsql-to-spark Reference for the Lakebridge CLI, runtime pitfalls in migrated code, and T-SQL conversion patterns
Loops migrate-queue, parity-sweep, stabilize-job Ralph loop prompts that work through a git-tracked queue one item per iteration

Plus a docs page: Agentic Migration with Claude Code (docs/lakebridge/docs/agentic_migration.mdx).

Relevant implementation details

  • Prompts only. Markdown commands, skills and subagents, one small init.sh that copies templates, and two JSON manifests. No Python, no new dependencies, no changes to src/, labs.yml or pyproject.toml.
  • All project-specific facts live in the user's migration/migration.config.yml (CLI profile, catalog/schemas, source folders, jobs, rules). The plugin never hard-codes workspace details, and the config refers to credentials only by profile or secret-scope name.
  • The patterns come from running a production SQL Server → Databricks migration this way: the reviewer runs in its own subagent so it judges the builder's output independently, validation always goes schema before data, loops keep their memory in committed files rather than the conversation, and a rule forbids copying legacy rows into the target to "fix" counts.
  • claude plugin validate . passes.

Caveats/things to watch out for when reviewing:

  • Location/naming: the plugin lives in claude-code-plugin/ with the marketplace manifest at .claude-plugin/marketplace.json (the path Claude Code looks for). Happy to move it (e.g. under docs/ or a contrib/ folder) or rename the plugin.
  • The plugin author is set to "Databricks Labs" to match the repository; change as preferred.
  • The Ralph loops depend on Anthropic's separate ralph-wiggum plugin; everything else works without it.
  • Agents act with the user's CLI credentials. The docs page has a Safety section recommending a dev catalog and a branch.

Linked issues

Functionality

  • added relevant user documentation
  • added new CLI command
  • modified existing command: databricks labs lakebridge ...
  • added a Claude Code plugin + marketplace manifest (no runtime code)

Tests

  • manually tested — claude plugin validate . passes; init.sh scaffolds and is idempotent; docs site builds
  • added unit tests — n/a (no Python)
  • added integration tests — n/a

🤖 Generated with Claude Code

Adds a prompts-only Claude Code plugin, installable from this repository's
marketplace manifest, that drives the Lakebridge and Databricks CLIs:

- plan/build/review/fix subagents orchestrated per legacy object
- parity-fix skill: schema first, per-layer counts, key-level diffs
- run-and-monitor skill: bounded self-healing job runs
- expert commands for the Lakebridge CLI, Databricks runtime pitfalls
  and T-SQL to Spark conversion
- Ralph loop templates (migrate queue, parity sweep, stabilize job)
- docs page: Agentic Migration with Claude Code

No Python code or dependencies are added.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@KhaledAufDB
KhaledAufDB requested a review from a team as a code owner September 24, 2026 12:04
@KhaledAufDB

Copy link
Copy Markdown
Author

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant