// Top-level router for Rocky development tasks. Use this FIRST for any request to change Rocky — it points at the right subskill based on what's being touched. Also use for quick monorepo orientation (build, test, lint, install, where-is-what).
| name | rocky-dev |
| description | Top-level router for Rocky development tasks. Use this FIRST for any request to change Rocky — it points at the right subskill based on what's being touched. Also use for quick monorepo orientation (build, test, lint, install, where-is-what). |
Rocky is a monorepo with three shipping subprojects + a playground catalog. Most non-trivial changes cross subproject boundaries, and the cascade rules are easy to forget. Use this skill as a router.
| Path | Language | Ships as | Build | Test |
|---|---|---|---|---|
engine/ | Rust (22 crates) | rocky CLI binary | cargo build --release | cargo test |
integrations/dagster/ | Python | dagster-rocky wheel | uv build --wheel | uv run pytest |
editors/vscode/ | TypeScript | Rocky VSIX | npm run compile | npm run test:unit |
examples/playground/ | Config | (not published) | ./run.sh per POC | ./scripts/run-all-duckdb.sh |
Each has its own CLAUDE.md with subproject-specific coding standards and commands. Read the subproject CLAUDE.md before editing it — they're kept current.
just build # cargo build --release + uv build --wheel + npm compile
just test # cargo test + pytest + vitest (vscode unit tests only)
just lint # cargo clippy/fmt + ruff + eslint
just codegen # Rust → JSON schemas → Pydantic + TypeScript
just --list # all recipes
Each subproject's native tool (cargo, uv, npm) also works directly from inside the subproject dir. The justfile is convenience, not a requirement.
→ rocky-codegen skill. You'll edit Rust in engine/crates/rocky-cli/src/output.rs then run just codegen. The CI drift check will fail the PR if you skip this.
rocky <command> subcommand"→ rocky-new-cli-command skill. This is the superset that walks through engine impl + codegen + dagster resource method + vscode command registration.
.rocky files)"→ rocky-dsl-change skill. Lockstep change across engine/rocky-lang, engine/rocky-compiler, editors/vscode/syntaxes/rocky.tmLanguage.json, editors/vscode/snippets/rocky.json, and docs/src/content/docs/rocky-lang-spec.md.
→ rocky-new-adapter skill. New crate under engine/crates/rocky-<name>/, implementing traits from rocky-adapter-sdk, with conformance tests. Template crates: rocky-databricks, rocky-snowflake, rocky-duckdb, rocky-fivetran.
→ rocky-poc skill. Scaffold with examples/playground/scripts/new-poc.sh <category> <id-name>. Defaults to DuckDB; credential-gated POCs must fail fast. Do NOT duplicate anything from engine/examples/ (official starter set).
rocky.toml"→ rocky-config skill. Covers the 4 pipeline types (replication / transformation / quality / snapshot), adapter variants (duckdb / databricks / snowflake / fivetran), minimal-config defaults, env-var substitution (${VAR:-default}), governance, checks, contracts, state backends, hooks. Also lists the pre-Phase-2 legacy keys that no longer work ([source], [warehouse], [replication], [checks] at top level).
→ rocky-release skill. Tag-namespaced (engine-v*, dagster-v*, vscode-v*). All three artifacts are CI-driven — land a release PR with the version bump + CHANGELOG entry, tag the merged commit, push the tag, and the matching release workflow handles the build and publish. scripts/release.sh remains as a local-build hotfix fallback. Convenience recipes: just release-engine, just release-dagster, just release-vscode.
→ Use the databricks, fivetran, or engine-local rocky skills in engine/.claude/skills/ — they're activated automatically when you're in the engine directory and contain the REST API references.
→ Also install and use the dagster-expert Claude Code skill (marketplace). The integration at integrations/dagster/ leans on Dagster's current component/pipes/asset model, which evolves quickly.
When a change touches X, what else moves?
| You change | Also touch |
|---|---|
engine/crates/rocky-cli/src/output.rs (any *Output struct) | Run just codegen — auto-regenerates schemas/, integrations/dagster/.../types_generated/, editors/vscode/src/types/generated/. Then re-export in integrations/dagster/src/dagster_rocky/types.py and add a dispatch row in parse_rocky_output(). |
A .rocky keyword or operator | engine/rocky-lang/src/{token,parser,lower}.rs, engine/rocky-compiler/src/, editors/vscode/syntaxes/rocky.tmLanguage.json, editors/vscode/snippets/rocky.json, docs/src/content/docs/rocky-lang-spec.md |
| A new CLI command | Engine impl + rocky-cli/src/output.rs struct + rocky-cli/src/commands/export_schemas.rs registration + just codegen + dagster resource.py method + vscode src/commands/<group>.ts + package.json contribution |
| A new adapter | New crate in engine/crates/ + engine/Cargo.toml members + conformance test hookup + factory registration in rocky-core/src/config.rs |
rocky.toml config schema | engine/crates/rocky-core/src/config.rs + editors/vscode/schemas/rocky-config.schema.json (for IDE autocompletion) |
| Test fixture for dagster | just regen-fixtures (writes to integrations/dagster/tests/fixtures_generated/ for drift detection) or ./scripts/regen_fixtures.sh --in-place to promote to fixtures/ (destructive) |
just install-hooks
This sets core.hooksPath to .git-hooks/. The pre-commit hook runs just codegen and fails the commit if engine/crates/rocky-cli/src/output.rs, commands/doctor.rs, or commands/export_schemas.rs is staged and the regenerated bindings differ from what's staged — same invariant as the CI drift check, caught locally. Skip with ROCKY_SKIP_CODEGEN_HOOK=1 git commit … in emergencies.
*Output change without the regenerated bindings — codegen-drift.yml will fail the PR.Co-Authored-By trailers in commit messages. Use conventional commits (feat:, fix:, refactor:, test:, docs:, chore:), scoped by crate or subproject.format!() untrusted input into SQL — use rocky-sql/validation.rs to validate identifiers first.*/types_generated/ or */types/generated/ except the curated __init__.py / index.ts barrels (those are protected by git checkout in the codegen recipes).--no-verify). The dagster integration has git hooks under integrations/dagster/.git-hooks/ for ruff + conventional commit validation + pytest.Three artifacts, three tag namespaces, independent release schedules:
engine-v* → GitHub Releases (macOS + Linux local, Windows via engine-release.yml)dagster-v* → GitHub Releases + PyPI (with --publish)vscode-v* → GitHub Releases + VS Code Marketplace (with --publish)See the rocky-release skill for the full checklist.
CLAUDE.md (root) — monorepo-wide cascade rulesengine/CLAUDE.md — engine coding standards, JSON output schema table, Databricks SQL patterns, auth flowsintegrations/dagster/CLAUDE.md — dagster layer architecture, "Adding support for a new Rocky CLI command" 9-step checklisteditors/vscode/CLAUDE.md — vscode extension architecture, 50-command listexamples/playground/CLAUDE.md — POC authoring conventionsjustfile (root) — orchestration recipes (build, test, lint, codegen, release, fixtures).github/workflows/ — path-filtered CI per subprojectCanonical `rocky.toml` authoring reference. Use when writing or reviewing a Rocky pipeline config — covers the 4 pipeline types (replication, transformation, quality, snapshot), adapter variants (duckdb/databricks/snowflake/fivetran), minimal-config defaults, env-var substitution, governance, checks, hooks, and the ${VAR:-default} syntax.
Dagster integration test fixture lifecycle. Use when regenerating live-binary fixtures via `just regen-fixtures` / `scripts/regen_fixtures.sh`, debugging why a generated fixture differs across runs, or adding scenario data for new CLI commands. Covers determinism (zeroed timings, sentinel timestamps), the relationship between `tests/scenarios.py` and `tests/fixtures_generated/`, and the two POCs that back the corpus.
Using TailwindPlus Elements (@tailwindplus/elements) in the Rocky VS Code webviews. Use when building or upgrading an interactive webview component — a command palette / model search, a confirmation dialog, an autocomplete or select model picker, a dropdown/popover menu, a collapsible disclosure, or tabs. Covers the esbuild-bundle install (no CSP change vs the CDN), the --vscode-* theming + Tailwind v3.4 data-variant nuance, React 19 custom-element interop (boolean attrs, native events via ref, the elements:ready gate), and which element fits which Rocky surface.
Dependency hygiene for the Rocky engine workspace — how to add/update deps via [workspace.dependencies], MSRV 1.88 policy, cargo-audit / cargo-deny / cargo-machete usage, and how the weekly security audit surfaces advisories.
How an AI agent should author or modify a Rocky data model. Use when building, fixing, or evolving a model on behalf of a user — covers the inspect → sample → write SQL → compile-loop → plan → propose → review → apply workflow, the reconcile discipline (check the data, not just the schema), and the AI-authored-plan safety gate. SQL-first.
Rocky CLI JSON-output schema cascade. Use when editing any `*Output` struct in `engine/crates/rocky-cli/src/output.rs` (or `commands/doctor.rs`), adding a new CLI command schema, or when a change could affect `schemas/*.schema.json`, `integrations/dagster/src/dagster_rocky/types_generated/`, or `editors/vscode/src/types/generated/`. Also use when CI reports `codegen-drift`.
