build-an-app

# Build an App Done means one useful domain workflow with a designed route, shared UI/agent actions, correct access, agent context, and a smoke run that proves its key rule. Finish a narrow slice before expanding it. This skill edits source files. If this session cannot write files (a deployed app's runtime agent), say the change needs a code session and stop. The four-area parity rule from `adding-a-feature` (UI, action, instructions, application state) applies to everything you add. This skill supplies the order and decisions; use the edit-point reference for the scaffold you have. ## 1. Orient Read `AGENTS.md`, this skill, and only the files you will edit. Skip broad repo surveys, `README.md`, and `DESIGN.md`. Use the bundled docs/source commands in `AGENTS.md` only to answer a concrete API question; do not web-research framework APIs. ## 2. Decide Choose these six things before writing code: 1. **Slice**: the one workflow that proves the app. For a booking app: create a booking, reject an overlap, cancel, weekly grid per room. Name what you are deferring (recurrence, notifications, roles, integrations) unless requested. 2. **Who sees each table**: pick one row of the access table in `references/data-and-access.md`: private, team-visible, shared on invite, or a child that inherits its parent's access. Making a team resource private per user is the usual wrong turn. Everyone then sees an empty list, and no conflict check can see anyone else's rows. Give each table `owner_email` and/or `org_id`, directly or via `ownableColumns()`; `org_id` alone passes `[db-tool-scoping]`. Doctor checks the schema marker, not query authorization; never denylist or opt out `rooms` or `bookings`. 3. **Invariants**: rules that must hold under concurrent requests (no overlap, stock never negative, unique slug). Enforce them in a write action inside a transaction or with a database constraint; the UI alone is insufficient. 4. **Actions**: `list-<things>`, `create-<thing>`, a single `update-<thing>` patch per resource, and the domain verbs (`cancel-booking`). Fewer, orthogonal tools make the agent choose better. 5. **Route**: give the domain its own route (for example, `/rooms`). Preserve existing routes and set `app.homePath` so sign-in lands on the domain when that is the requested home screen. 6. **Agent context**: URL ids and filters (for example `roomId`, `week`) that belong in `navigation`. ## 3. Build: write everything, then verify once In a generated app, read `package.json` at `["agent-native"].scaffold.template` and choose the matching reference: - `chat`: `references/edit-points-chat.md` - `default`: `references/edit-points-default.md` - workspace root: use `adding-workspace-apps` to create an app, then follow the new app's own `AGENTS.md` and scaffold reference. - another domain template: use its `AGENTS.md` and `adding-a-feature`; do not apply Chat or default shell instructions to it. If metadata is absent, inspect the actual route, layout, plugin, and navigation files before choosing an edit point. Do not infer a shell from the app name. Write the UI, actions, instructions, and state before running the verification steps below. Do not leave placeholder or comment-only screens. `references/rooms-example.md` gives a booking slice to adapt. It was verified against the Chat starter; use the selected edit-point reference for the shell. Use `frontend-design` for a deliberate visual direction and finish the requested screens and interactions. ### Data - Use PostgreSQL only, and keep migrations additive: new columns are nullable or have a default, and nothing is dropped or renamed. Never edit an applied entry; append a new named one. - Set `ownerEmail` from `ctx.userEmail` and `orgId` from `ctx.orgId` on inserts where those columns exist. Never rely on a development identity fallback. - Ids are text from `crypto.randomUUID()`. - Bound every list (a time range or `.limit()`), select only the columns it renders, and index the columns it filters and sorts on. - Store normalized UTC ISO timestamps; collect/display local times in the user's timezone. Validate offsets at the action boundary before parsing. The access table, the concurrency pattern, and the security rules are in `references/data-and-access.md`. ### Actions - `schema` is zod, with `.describe()` on every field stating its units and format (for example, "ISO 8601 date-time with offset"). - Reads use `http: { method: "GET" }` and `readOnly: true`. Leave writes on the default POST so `useActionMutation` needs no `method`. - Reject with `fail(message, { errorCode, statusCode })` from `@agent-native/core/action`: 409 for a conflict, 404 for not found, 403 for forbidden. A returned `{ error }` is counted as success everywhere, and a bare `throw` reaches the browser as a generic 500. - Return plain objects that include the `id`. Keep LLM calls out of actions; AI-shaped work belongs in the agent chat. - When the request is batch-shaped ("add these 20"), write one action that takes an array and writes it in one transaction. ### UI - Load and write data with `useActionQuery` and `useActionMutation` from `@agent-native/core/client/hooks`. No `fetch`, and no `/api/*` routes for app data. Those routes are only for uploads, webhooks, OAuth callbacks, and streaming. - While data loads, show a `Skeleton` in the shape of the final layout, not a spinner or "Loading…". - Writes should feel instant. In `onMutate`, update `["action", "<name>", params]` with `setQueryData`; in `onError`, roll back and show `toast.error(actionErrorMessage(error) ?? "<fallback>")`. - Import controls from `@/components/ui/*`. When one is missing (dialog, select, skeleton, alert-dialog), add a one-line re-export like `button.tsx`: `export * from "@agent-native/toolkit/ui/dialog";`. - Use Tabler icons only. Confirm with `AlertDialog`; never use `window.confirm`, `alert`, or `prompt`. - Don't add a page title that repeats the nav item, a subtitle under a title, or a stats strip. The data is the page. For visual direction, see `frontend-design`. - Follow the app's existing localization pattern for user-facing copy. - Add a pure `link` builder with `buildDeepLink()` to actions that create or list navigable resources; see `adding-a-feature` for the shape. ### Agent instructions Append one section of about 1,500 characters at most to `AGENTS.md`. The runtime prompt cuts the file off at 6,000 characters. Cover: - a one-line purpose with the routes - the invariants, and how to report a rejection - time and format conventions - the new `navigation` fields - an action table with unpadded cells Keep the action table aligned with the scaffold's primary tool list when one exists; other actions should remain discoverable through `tool-search`. Leave unrelated AGENTS.md sections, README, and DESIGN.md as they are. ### Real-time Agent writes need no wiring, because the chat run refreshes action queries after each tool. Add `useDbSync({ realtime: { reason } })` to a page only when other people change its data while it is open and the user must see the change before refreshing. A booking grid doesn't qualify: the server rejects bookings made from a stale view. See `real-time-sync`. ## 4. Verify, once, in this order 1. Start `pnpm exec agent-native dev` in the background, without `--open`, and wait for the ready URL. Startup regenerates `.generated/action-types.d.ts` and the actions registry, so a typecheck run before this is meaningless. On loopback, automatic dev sign-in works when the local database has no real users. If the sign-in page appears, use an existing local account or switch to a separate disposable local database; do not create accounts or set `AUTH_DISABLED`. 2. Run `pnpm typecheck`, then `pnpm agent-native:doctor`. Plain `pnpm doctor` runs pnpm's own command and exits 0 without running Agent-Native Doctor. Fix every finding, then rerun only what failed. 3. Check the agent path. Call a guarded write twice with the same input via `pnpm action <name> --key value`. The second call must fail with the expected message; read back the saved state through the matching list/get action. The CLI prints the failure message, not its structured `errorCode`, so also verify any code-specific behavior in the action contract or browser. 4. Run one browser smoke on the domain route: - create a record - trigger the rejection: a toast appears and nothing is written - cancel or undo, repeat the previously rejected write, and confirm it succeeds Inspect console and network failures. Fix errors from the new route or actions and identify existing scaffold messages separately. The only expected 4xx/5xx is the rejection being tested. Capture the finished workflow. 5. Stop the dev server and close the tab. Skip the production build, unrelated test suites, and README or DESIGN rewrites. To triage failures, see `references/verification.md`. ## 5. Report State what works and the proof, what you deferred, and anything the user still has to do (for example, set `DATABASE_URL` before deploying). Never report a check you didn't run. ## Related - `adding-a-feature`: the parity checklist for each later feature in this app. - `frontend-design`, `actions`, `sharing`, `real-time-sync`, and `security`: go deeper on one area when the references aren't enough.