adding-workspace-apps

# Adding Workspace Apps ## Classify The Ask First When a user asks from Dispatch chat or through `@agent-native` in Slack or Telegram to create, build, make, scaffold, or generate an "agent", classify the ask first. Simple Dispatch-native behavior such as a reminder, digest, monitor, routing rule, saved instruction, or recurring workflow can stay in Dispatch as a recurring job/resource/destination. Robust unique products or teammates that need their own UI, data model, actions, integrations, or domain workflow should become a separate workspace app under `apps/<app-name>`, mounted at `/<app-name>`. ## Where The App Lives Do not implement a new app by adding a route, page, component, or file to `apps/chat` or another existing app unless the user explicitly asks to modify that existing app. ## Vault Access Dispatch vault access is workspace-wide by default: every saved vault key is available to every workspace app. Only create or request per-app vault grants when Dispatch's vault access setting is switched to manual mode. When an app needs a provider credential, use the app's scoped secret or workspace-connection resolver so Dispatch remains the source of truth. Do not ask a non-admin builder to add a key to local project settings or `.env`; use Dispatch's vault request workflow for a missing key and keep the value out of app code. ## Discovery, Links, And The UI Stack The local workspace gateway discovers apps from `apps/<app-name>/package.json`. Production Dispatch images that contain only `.output/` cannot scan those directories: set `AGENT_NATIVE_WORKSPACE_APPS_JSON` on the Dispatch service at runtime and the same `VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON` while building its client bundle. List only apps in that workspace, with each deployed `path` matching its `APP_BASE_PATH` and proxy route. Do not reuse another organization's manifest. Always save a concise, human-readable `description` in each package manifest; Dispatch and A2A connected-agent context use the app name plus description so agents know what it does. Use relative workspace links like `/<app-name>` and never hardcode `localhost`, `127.0.0.1`, `8080`, `8100`, or any dev port in app cards, instructions, redirects, or navigation; the active workspace gateway/browser origin owns the port. React Router apps must preserve `APP_BASE_PATH` / `VITE_APP_BASE_PATH` in `app/entry.client.tsx` via `appBasePath()` so the app hydrates correctly when mounted at `/<app-name>`. Use the framework/template UI stack for standard UI: shadcn/ui components and `@tabler/icons-react`. Do not add `lucide-react` or another icon library. Read `.agents/skills/shadcn-ui/SKILL.md` before adding, updating, or debugging shadcn components. ## App Data Goes Through Actions Normal app data must flow through actions. For CRUD that the agent can perform, create `defineAction` files in `actions/`, mark reads with `http: { method: "GET" }`, and call them from React with `useActionQuery` / `useActionMutation`. Do not add duplicate JSON CRUD routes under `/api/*` for the same data unless the route is for uploads, streaming, webhooks, OAuth, or another route-only concern. Do not add routes whose main job is to wrap, proxy, or re-export an action; the action endpoint already exists at `/_agent-native/actions/:name`. Action-backed UI is what makes agent-created or agent-edited records appear without a manual refresh. ## PostgreSQL Database App database code targets local PGlite and hosted Postgres. Define schemas with `@agent-native/core/db/schema` helpers and write app reads/writes with Drizzle's PostgreSQL query builder and `drizzle-orm` operators. Do not import raw schema drivers in app templates. Keep raw SQL for additive migrations, health checks, or carefully scoped maintenance. Do not use SQL as object storage; file bytes belong in upload/private-blob providers with only references saved to app tables. ## Scaffolding In local development, run `pnpm exec agent-native create <app-name> --template=<template>` from the workspace root. In production, Dispatch posts new-app requests to Builder branch creation; Builder should still scaffold the separate workspace app. The workspace dev gateway (`pnpm dev`) detects new `apps/<app-name>` directories automatically. Scaffolding the directory is not the app being live. Before saying the app is created, request `/<app-name>` on the running gateway and confirm it returns the new app, not a fallback route or another app's shell — then tell the user that exact path to open, since the preview root can still show a different app. If the preview/host isn't running the workspace gateway (root `pnpm dev`), say plainly that its run/dev command must point at the workspace root `pnpm dev` and name where to set it (Builder: project settings → dev command); the agent cannot change a host's run/dev command itself. Never report the app as created while the preview still shows something else. ## Finishing A Chat-Template App When using the chat template, treat it as scaffolding only. The finished app must be branded as the requested app, with its own home screen, navigation, package metadata, manifest, and domain workflow. Do not leave visible `Chat`, `Starter`, `Blank app`, `Start building`, or `New app` UI in a chat-derived app. ## Related Skills - **workspace-conventions** — Shared workspace rules this workflow assumes. - **actions** — How to define the app operations the agent and UI share. - **composable-mini-apps** — Splitting work across focused sibling apps. - **portability** — Keeping PostgreSQL and hosting assumptions explicit. - **shadcn-ui** — Adding and upgrading the UI primitives.