Explains SonicJS core architecture, configures Hono routes, sets up middleware chains, and organises project directory structure. Use when the user asks about overall SonicJS architecture, configuring Hono routing, wiring up middleware handlers, scaffolding project directories, or understanding the middleware execution order (Bootstrap → Logging → Security → Standard → Route-Specific → Handler).

D1 database, Drizzle ORM schemas, database migrations, and schema configurations for SonicJS. Use when defining table schemas, generating migration files, writing select/insert/update queries, applying D1 migrations, or setting up and configuring collections with Drizzle ORM.

Form.io integration, form creation, submission routing, shadow collections, and content mapping for SonicJS. Use when building form builders, querying form submissions, handling form data, working with form fields, or integrating the Form.io API in SonicJS.

Deploys SonicJS applications to Cloudflare Workers, runs Vitest unit and Playwright E2E test suites, executes Drizzle ORM database migrations, manages Cloudflare D1/KV/R2 resources, and configures secrets via Wrangler CLI. Use when deploying to Cloudflare Workers, running migrations against D1 databases, executing Vitest or Playwright test suites, setting up local development, or managing production secrets.

Extends SonicJS functionality via modular plugins including Authentication (OTP, Magic Link), Editor (EasyMDE, TinyMCE, Quill), and Utility types. Use when adding, activating, building, or configuring a plugin, extension, hook, or add-on within SonicJS — including enabling passwordless auth flows, registering editor middleware, managing plugin lifecycle and dependencies, or interacting with the plugin API.

Use when the user shares a Mermaid ER diagram, schema sketch, or relationship diagram and asks for review, feedback, validation, or critique — including phrases like "what do you think of this", "look at this diagram", "I have this in mind", "can we model it like this", or pastes any block starting with "erDiagram" or "classDiagram". Validates the diagram against the constitution, returns a five-section structured response (constitutional violations, counter-proposal with improved Mermaid, migration plan if existing schema applies, test surface, open questions), and never silently accepts a design that violates tenant isolation, eventing, or graph-RAG boundaries.

Use when designing or reviewing the eventing layer of the commerce platform — including transactional outbox tables, outbox relays, domain event catalogs, idempotency keys, audit logs, memento snapshots, event sourcing decisions, and Neo4j projection workers. Triggered by requests to design events, design integration with external systems, design notification flows, design data sync to Neo4j or analytics warehouses, decide between event sourcing and CRUD, or review existing outbox / audit / event-sourcing schemas.

Use when the agent needs to inspect the actual current state of a PostgreSQL database before answering a schema question — including before adding columns, before reviewing diagrams, before proposing migrations, or whenever the snapshot in .specify/memory/current-schema-state.md is stale. Connects via the configured Supabase MCP/read-only schema source, queries catalog metadata through list_tables or SELECT-only catalog SQL, and refreshes the snapshot file. Triggered by any "let me check what's already there", "what columns does X have", "what indexes exist on Y", "what does the schema look like", or by the snapshot being older than 24 hours.

Use when the user wants to add an attribute, modify an entity, or model a new concept on top of an existing PostgreSQL schema — including phrases like "add a column to", "track this on the product", "we need to store", "model this concept", "extend the order with", "where should this live", or "should this be a new table". Inspects current state via the postgres-schema-introspection skill, runs a five-placement analysis (new column / JSONB key / EAV row / new related table / wrong entity), maps blast radius across foreign keys, outbox events, Neo4j projections, RLS, and indexes, and produces an expand/contract migration plan with rollback and tests.

Use when repository changes are complete and you need to run and report the required validation gates for the applicable change class (`docs-only`, `terraform-module`, `example-terraform`, `ci-workflow`, or `mixed`).

Review completed implementation against approved specs to ensure all requirements are satisfied. Use after finishing implementation work, before marking a task as done, or when a stakeholder asks to verify deliverables against requirements. Produces a review summary with pass/fail per requirement. Common triggers: "review my work", "check against spec", "did I miss anything", "is implementation complete".

Use when a user wants to upgrade, update, or migrate a dbt-core project to the latest version — e.g. "upgrade my dbt project," "migrate this off dbt-core 1.5," "get this project running on the latest dbt," "bump the dbt-core version." Upgrades a dbt-core v1 project (on 1.3, 1.4, 1.5, 1.6, or 1.7) all the way to 1.12, applying the required breaking, behavior, and deprecated changes from a data-driven issue corpus. Inputs — starting_version (the project's current dbt-core minor, one of 1.3/1.4/1.5/1.6/1.7) and adapter_type (snowflake/redshift/bigquery/databricks/spark); both are normally supplied by the caller (e.g. the dbt VS Code extension), with fallbacks described in the skill.

Creates unit test YAML definitions that mock upstream model inputs and validate expected outputs. Use when adding unit tests for a dbt model or practicing test-driven development (TDD) in dbt.

Writes and executes SQL queries against the data warehouse using dbt's Semantic Layer or ad-hoc SQL to answer business questions. Use when a user asks about analytics, metrics, KPIs, or data (e.g., "What were total sales last quarter?", "Show me top customers by revenue"). NOT for validating, testing, or building dbt models during development.

Use when creating or modifying dbt Semantic Layer components — semantic models, metrics, dimensions, entities, measures, or time spines. Covers MetricFlow configuration, metric types (simple, derived, cumulative, ratio, conversion), and validation for both latest and legacy YAML specs.

Generates MCP server configuration JSON, resolves authentication setup, and validates server connectivity for dbt. Use when setting up, configuring, or troubleshooting the dbt MCP server for AI tools like Claude Desktop, Claude Code, Cursor, or VS Code.

Retrieves and searches dbt documentation pages in LLM-friendly markdown format. Use when fetching dbt documentation, looking up dbt features, or answering questions about dbt Cloud, dbt Core, or the dbt Semantic Layer.

Audits dbt documentation coverage and drafts missing model/column descriptions in the project's own house style, one folder at a time, for human review. Use when documenting undocumented models, backfilling missing YAML descriptions, auditing doc coverage, or keeping schema YAML in sync with model SQL — especially on multi-contributor projects where new models routinely land undocumented.

Formats and executes dbt CLI commands, selects the correct dbt executable, and structures command parameters. Use when running models, tests, builds, compiles, or show queries via dbt CLI. Use when unsure which dbt executable to use or how to format command parameters.

Diagnoses dbt Cloud/platform job failures by analyzing run logs, querying the Admin API, reviewing git history, and investigating data issues. Use when a dbt Cloud/platform job fails and you need to diagnose the root cause, especially when error messages are unclear or when intermittent failures occur. Do not use for local dbt development errors.

Builds and modifies dbt models, writes SQL transformations using ref() and source(), creates tests, and validates results with dbt show. Use when doing any dbt work - building or modifying models, debugging errors, exploring unfamiliar data sources, writing tests, or evaluating impact of changes.

Use when a user is enabling, configuring, optimizing, or debugging dbt State (the server-backed reuse mechanism that clones or skips nodes instead of rebuilding them). Use when they conflate dbt State with the `state:modified` selector or `--state` deferral. Use when asked about models rebuilding unexpectedly, views with `select *` rebuilding, volatile SQL (`current_timestamp()`, `random()`) rebuilding or not, cross-developer cloning, lag_tolerance.

Use when changing a dbt model in a way that could break its consumers — renaming, removing, or retyping a column, or changing a model that downstream models, exposures, dashboards, or BI tools depend on — to judge whether the change is breaking and who it affects. Also use when versioning a model (model versions, latest_version, latest_version_pointer, deprecation_date, migration windows), enforcing contracts, setting access or groups, or doing multi-project dbt Mesh work (cross-project refs via dependencies.yml, disambiguating similarly-named models, splitting a monolith). Covers single- and multi-project, and planning or advising as well as implementing.