development - SKILL.md Agent Skill

name: development description: > Use for VBI monorepo development: apps, packages, practices, website documentation, repository-level workflows, generated artifacts, validation commands, source-of-truth decisions, software entropy control, maintainability, refactoring, dead-code deletion, and constraining messy LLM-generated code.

VBI Development Handbook

Repository-level rules for VBI work. Keep this file as the routing layer: use it for the non-negotiable principles, then load only the reference that matches the package, practice, or entropy risk in front of you.

Core Rules

Work from the owner and source of truth: DSL, Builder, Provider API, generator, example JSON, or local utility.
Reduce maintenance cost. Prefer deletion, simplification, extraction, or moving ownership over adding compatibility layers.
Use real needs to drive abstraction, deletion to fight entropy, and naming and boundaries to make code explain itself. See references/software-entropy.md#optimization-habits.
Builder owns DSL mutation. UI, CLI, agent, app, and practice code should use Builder or public package APIs instead of rebuilding internals.
Generated artifacts are outputs, not primary fixes. Change the source and regenerate when needed.
Do not cross ownership boundaries casually: packages must not depend on apps, and practices must not import another practice's private src/*.
For apps/vbi_be and apps/vbi_fe, use the Docker-only workflows in references/apps/vbi-be.md and references/apps/vbi-fe.md for runtime, debugging, validation, and build commands. Do not run those app workflows directly on the host unless the user explicitly overrides this rule.
When deleting or renaming, clean imports, calls, types, comments, tests, docs, generated references, and old names in the same change.

Ownership Map

packages/vbi: VBIChartDSL, Builder, dashboard/report/insight state, and collaborative editing.
packages/vquery: QueryDSL-to-SQL and query execution.
packages/vseed: VSeed examples, lowering, and rendering specs.
packages/vbi-agent: Builder Agent runtime and tool protocol.
packages/vbi-component: shared component layer for VBI.
packages/vbi-react: React integration.
apps/*: product applications, docs website, backend, provider, and CLI.
practices/*: independent practice examples. Treat practices/vbi-react-starter as the @visactor/vbi-react integration starter, separate from the self-contained practice apps.

Run repository-level commands from the repo root unless a package script requires otherwise.

References

Load only the relevant reference:

Keep generic guidance directly under references/. Put app-specific guidance under references/apps/, package-specific guidance under references/packages/, and practice-specific guidance under references/practices/.

references/software-entropy.md: maintainability, refactoring, cleanup, deletion, generated-surface control, and optimization habits.
references/apps/website.md: apps/website, Rspress docs, generated API/example docs, and multilingual documentation synchronization.
references/apps/vbi-be.md: apps/vbi_be, NestJS backend, Prisma, collaboration server, and Docker-only backend development workflow.
references/apps/vbi-fe.md: apps/vbi_fe, Next.js frontend, UI state, service clients, and Docker-only frontend development workflow.
references/packages/vbi.md: packages/vbi, VBI DSL, Builder/sub-builder design, headless logic boundaries, and TDD expectations.
references/packages/vquery.md: packages/vquery, QueryDSL-to-SQL, DuckDB execution, example-driven tests, and coverage expectations.
references/packages/vseed.md: packages/vseed, VSeed examples, and generated VSeed documentation.
references/practices/minimalist.md: practices/minimalist.
references/practices/standard.md: practices/standard.
references/practices/streamlined.md: practices/streamlined.
references/practices/professional.md: practices/professional.

Validation

Prefer the narrowest proving command first, then repository gates when practical:

For apps/vbi_be and apps/vbi_fe, use the in-container commands from references/apps/vbi-be.md and references/apps/vbi-fe.md instead of the host-local examples below.

pnpm --filter <package-name> run test
pnpm --filter <package-name> run lint
pnpm --filter <package-name> run typecheck
pnpm run lint:check
pnpm run typecheck

If generated artifacts are affected, run the generator first and inspect the generated diff. Report any validation that could not run and why.