superset Agent Skills & AI Rules

# Superset Monorepo

Superset is an agent-first development platform, with an Electron desktop IDE, Next.js web apps, and an Expo mobile app as the main customer-facing surfaces. It's a Turborepo monorepo, deployed apps are in apps/ and supporting packages are in packages/, and we use tRPC for the api.

You're working inside a Superset workspace, an isolated checkout of this repo — a git worktree on a
machine someone owns, a plain clone at `/workspace` in a cloud workspace. "Workspace" in a user
message means that, not an editor workspace.

## Project Structure

All projects in this repo should be structured like this:

```
app/
├── page.tsx
├── dashboard/
│   ├── page.tsx
│   ├── components/
│   │   └── MetricsChart/
│   │       ├── MetricsChart.tsx
│   │       ├── MetricsChart.test.tsx      # Tests co-located
│   │       ├── index.ts
│   │       └── constants.ts
│   ├── hooks/                             # Hooks used only in dashboard
│   │   └── useMetrics/
│   │       ├── useMetrics.ts
│   │       ├── useMetrics.test.ts
│   │       └── index.ts
│   ├── utils/                             # Utils used only in dashboard
│   │   └── formatData/
│   │       ├── formatData.ts
│   │       ├── formatData.test.ts
│   │       └── index.ts
│   ├── stores/                            # Stores used only in dashboard
│   │   └── dashboardStore/
│   │       ├── dashboardStore.ts
│   │       └── index.ts
│   └── providers/                         # Providers for dashboard context
│       └── DashboardProvider/
│           ├── DashboardProvider.tsx
│           └── index.ts
└── components/
    ├── Sidebar/
    │   ├── Sidebar.tsx
    │   ├── Sidebar.test.tsx               # Tests co-located
    │   ├── index.ts
    │   ├── components/                    # Used 2+ times IN Sidebar
    │   │   └── SidebarButton/             # Shared by SidebarNav + SidebarFooter
    │   │       ├── SidebarButton.tsx
    │   │       ├── SidebarButton.test.tsx
    │   │       └── index.ts
    │   ├── SidebarNav/
    │   │   ├── SidebarNav.tsx
    │   │   └── index.ts
    │   └── SidebarFooter/
    │       ├── SidebarFooter.tsx
    │       └── index.ts
    └── HeroSection/
        ├── HeroSection.tsx
        ├── HeroSection.test.tsx           # Tests co-located
        ├── index.ts
        └── components/                    # Used ONLY by HeroSection
            └── HeroCanvas/
                ├── HeroCanvas.tsx
                ├── HeroCanvas.test.tsx
                ├── HeroCanvas.stories.tsx
                ├── index.ts
                └── config.ts

components/                                # Used in 2+ pages (last resort)
└── Header/
```

1. **One folder per component**: `ComponentName/ComponentName.tsx` + `index.ts` for barrel export
2. **Co-locate by usage**: If used once, nest under parent's `components/`. If used 2+ times, promote to **highest shared parent's** `components/` (or `components/` as last resort)
3. **One component per file**: No multi-component files
4. **Co-locate dependencies**: Utils, hooks, constants, config, tests, stories live next to the file using them

### Exception: shadcn/ui Components

The `src/components/ui/` and `src/components/ai-elements` directories contain shadcn/ui components. These use **kebab-case single files** (e.g., `button.tsx`, `base-node.tsx`) instead of the folder structure above. This is intentional—shadcn CLI expects this format for updates via `bunx shadcn@latest add`.

## Database

Drizzle ORM, schema in `packages/db/src/`. Follow `.agents/skills/db-migrations/SKILL.md` to generate
migrations and to clear its production safety checklist before opening the PR. Never hand-edit `packages/db/drizzle/` (SQL, `meta/_journal.json`, snapshots) without
explicit user confirmation, and never apply migrations against a shared or production database.

## Releases

Desktop, host-service, and cli share one version; cut releases on a dedicated branch. Runbook:
`scripts/release/README.md`. A *canary* is a separate thing: `bash scripts/release-canary.sh
[commit]` builds the rolling internal `desktop-canary` prerelease, not a versioned release.

## Plugins

First-party plugins live in `plugins/<name>/`: a `plugin.json` manifest and `skills/`. A plugin
ships no code — agents reach its tools through `/mcp/plugins/<marketplace>/<plugin>` on the API,
which proxies to the vendor's MCP server or, for the plugins named in the `SUPERSET_HOSTED_PLUGINS` constant,
serves them from `packages/trpc/src/router/plugins/servers/`. A release is the git tag
`<name>@<version>` on this repo — that tree is what a host
downloads — and `packages/shared/src/plugins/manifests.generated.ts` is the bundle the API resolves
against, which is generated and must never be hand-edited. Change the source, then
`superset plugins publish <name> --bump patch`, which rewrites the marketplace entry in
`.agent-marketplace.json` and the generated manifests; commit and tag to publish it. `bun run check:plugins` is what CI
runs to catch a change that skipped that step; run it before pushing.

Installed plugins are recorded once per machine in
`$SUPERSET_HOME_DIR/plugins/installed_plugins.json` (`SUPERSET_HOME` is the CLI's install prefix and
means nothing here). Every provisioner reads that one file — the desktop at boot, `plugins sync`,
the host-service — because provisioning is declarative and reaps whatever is absent from the desired
set. A caller that passes its own list instead makes the last writer delete the others' skills.
Details: `docs/plugins.md`.

## Orchestrating agents and workspaces

When work wants a fresh isolated environment, a parallel agent, or a long-running job, reach for the
`superset` CLI instead of hand-rolling git worktrees or doing it all serially in this one. It's
already on `PATH` in Superset terminals, and we dogfood it.

Replace the capitalized placeholders before running these:

```bash
superset ws create --local --project PROJECT_ID --branch BRANCH --agent claude --prompt "..."
superset agents create --workspace WORKSPACE_ID --agent claude --prompt "..."
superset ws list --local
superset terminals read --workspace WORKSPACE_ID --terminal TERMINAL_ID
superset ws archive --local WORKSPACE_ID
```

In order: an isolated workspace with an agent already working in it, another agent in an existing
workspace, what's running, what an agent is doing right now, and cleanup when you're done.

Spawning several related workspaces? Add `--tag SOME_TAG` (repeatable) to `ws create` — tagged
workspaces group into a sidebar folder of that name automatically, so a batch files itself instead
of scattering across the project. `ws list --local --tag SOME_TAG` filters to them, and
`ws update WORKSPACE_ID --tag ...` retags (`--clear-tags` ungroups). Automation-created workspaces
are tagged `automation` by default and collect in an "automation" folder.

`superset schema` prints every command, option and argument as JSON; read it with `jq` to learn the
rest (tasks, automations, hosts, settings) instead of parsing `--help` text. To check only that a
command exists, the exit code of `superset <command> --help` is enough. Details and the version
caveat: `docs/agent-tooling.md`.

```bash
superset schema | jq '.commands[] | select(.path==["terminals"]) | .commands[] | {path, options: [.options[].name]}'
```

Pass `--json` for parsable output; it's on by default under agent environments.

## Internationalization

User-facing strings use Lingui macros with the English text as the message id —
`<Trans>Text</Trans>` or `useLingui()`'s `t({ message })` in React, `i18n._(msg({ message }))`
outside React (Electron main). Identical English with different meanings gets a `context`
so it translates separately. Numbers, currencies, and dates go through
`@superset/i18n/format` helpers, never `new Intl.*("en-US")` or `toLocale*` with a hardcoded
locale. After adding or changing strings, run `bun run check:i18n` (CI enforces it): it
regenerates the catalogs and lists every untranslated message per locale. Write those
translations yourself into each `locales/<locale>/messages.po` and commit the catalogs with
the change — nothing on CI fills translations for you. Conventions: `packages/i18n/README.md`;
terms that never translate: `packages/i18n/glossary.md`; strategy and phasing:
`plans/20260826-i18n-strategy.md`.
Directories listed in `packages/i18n/test/enforced-dirs.ts` must not contain hardcoded
JSX text — add a directory there once it is fully converted. `errorMessage()` output is potentially
translated and is display-only: logs, Sentry/PostHog, and error classification use
`rawErrorMessage()` or the error object (enforced by `packages/i18n/test/display-only.test.ts`).

**Shipping locales.** `SUPPORTED_LOCALES` in `packages/i18n/src/locales.ts` is the single
source of truth — adding a locale there is what makes it appear in the Settings picker and
the optional onboarding step, and what `lingui.config.ts` must list. Every enabled locale
must be **fully translated**: `compile --strict` fails the build on a missing message, so
finish a translation before adding its locale. Native language names live in `LOCALE_LABELS`
and are never translated — someone stuck in the wrong language has to recognize their own.
Relative times use `formatRelativeTime`/`formatCompactRelativeTime`, not hand-rolled
"3d ago" helpers; `Intl` already knows every locale's wording.

Three traps worth knowing before you touch catalogs:

- **Editing English copy re-keys the message.** The text is the id, so an edit creates a
  new entry that is empty in every locale and `check:i18n` lists it. If the edit was cosmetic,
  the old translations are still in `git diff` on the catalogs to copy from.
- **Regenerate from a clean tree.** `lingui.config.ts` keeps `messages.po` deterministic:
  `orderBy: "message"` fixes entry order, and `origins: false` drops the `#:` file
  references, whose order follows filesystem traversal and differs between macOS and
  Linux. A catalog regenerated on top of local experiments will still commit noise.
- **`bun test` runs uncompiled source.** The Lingui macro rewrites `` message: `${n} items` ``
  into a placeholder message plus values at build time, so the catalog stores `{n} items`.
  Tests see neither, which is why `apps/desktop/test-setup.ts` shims the macros and `i18n._`.
  Mock that module with a Proxy, never a spread — `i18n` is a class instance and a spread
  drops `load`/`activate`.

## Comments

Never comment unless the thing can never be self-describing in the code. Name it, structure it,
or type it first; a comment is the last resort for what the code genuinely cannot say — a
constraint that lives outside the repo, or a trap the next reader would walk into. Rationale goes
in the commit message and the PR.

## Tests

CI runs every suite on each push, and the whole run is meant to stay near two minutes. A test
earns its place by catching a regression quickly.

- **No real waiting.** A test that needs more than bun's default 5 s timeout is too slow. Do not
  raise the timeout: pass the delay, clock or retry count in and test with a small value. Never
  wait for a real network or process timeout to fire.
- **One test per behaviour.** Stress, fuzz and "adversarial" suites that build many real git
  repositories or processes do not go in the repo. When a probe finds a bug, keep the one
  regression test for it.
- **Any order, clean checkout.** Each package's suite runs in one process, in an order that differs
  between machines, with no root `.env`. Do not `mock.module` a module that other files import for
  real (`env`, a client, a logger). Give the code its input instead: a parameter, a placeholder in
  the package's test preload, or a local server.
- **A flaky test is a broken test.** Fix the cause or delete it. Do not add retries or longer
  timeouts.
- **Node-only suites** (real PTYs, `node:test`) are `*.node-test.ts` files run by a turbo task, so
  they run beside the bun suites and not after them.

## Further reading

- `.agents/skills/`: CDP UI verification, mobile simulator verification, DB migrations, tRPC
  compatibility, ticket format, and more. Read the matching `SKILL.md` when a task fits its
  description.
- `docs/agent-tooling.md`: where commands, skills, and per-agent-CLI config live.
- `docs/plugins.md`: authoring, publishing, and installing marketplace plugins — the manifest
  contract, the credential proxy, and which files are generated.
- `docs/environment-variables.md`: read before adding an environment variable. Five places,
  and missing one fails silently.
- `docs/deploy-workflows.md`: read before writing or testing a deploy workflow step. `run:` has
  no `pipefail` by default, and production secrets exist only in GitHub.
- `packages/trpc/AGENTS.md`: read before changing any tRPC procedure, in `packages/trpc` or
  `packages/host-service`. Released desktop, mobile, and CLI builds still call it.
- `apps/desktop/AGENTS.md`: desktop specifics (notices, persisted renderer state).
- `apps/mobile/AGENTS.md`: mobile structure and iOS-only scope.
- `docs/cloud-sandbox-mismatches.md`: where cloud workspace sandboxes don't fit assumptions the
  app makes about a machine someone owns. Read it before touching sandboxes, and add to it when
  you find a new one.
- `docs/cloud-sandbox-considerations.md`: what cloud sandboxes still owe before they leave the
  team — billing, credential blast radius, untested behaviour.

## Contributor responsibility

Contributors are responsible for every change they submit, including agent-generated code.
They must understand the changes, review the diff, and verify the behavior before requesting
review.

- Ask for clarification when a request lacks enough context to make a correct change.
- Explain changes and validation so the contributor can review and understand the result.
- Agents may write commit messages and PR descriptions, commit changes, push branches, create
  PRs, and address review feedback when authorized by the user.
- Only post replies to reviewers when the user explicitly authorizes it.
- Never claim that checks passed or behavior was verified unless it actually was.

## Code standards

- Keep code comments concise (usually 1-2 lines)
- Avoid redundant or excessive inline commentary
- Use ASD-STE100 Simplified Technical English, simple wordings

### Examples

```c++
  // Good (no comment)

  std::string module_name =
    fmt::format("{}_{:x}", name_, std::hash<std::string>{}(source_));

  // Bad (excessive comment for explicit code)

  // The module cache is keyed on this name, so it has to include the source:
  // two kernels sharing a name but not a body would otherwise both run
  // whichever was compiled first. Same fix as 3833 on the Metal side.
```