Initial commit from agent-native create
This commit is contained in:
agent-native
@@ -0,0 +1,512 @@
|
||||
---
|
||||
name: actions
|
||||
description: >-
|
||||
How to create and run agent actions. Actions are the single source of truth
|
||||
for app operations — the agent calls them as tools and frontend code calls
|
||||
them through client hooks. Use when creating a new action, adding an API
|
||||
integration, or wiring up frontend data fetching.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Agent Actions
|
||||
|
||||
## Rule
|
||||
|
||||
Actions in `actions/` are the **single source of truth** for app operations. The agent calls them as tools, and the frontend calls them through `useActionQuery` / `useActionMutation`. The framework owns the HTTP transport behind those hooks. No duplicate `/api/` routes needed.
|
||||
|
||||
Before creating any custom REST/API route for app data, inspect `actions/` and the action table in `AGENTS.md`. If an action already exists, call it directly from the agent or with `useActionQuery` / `useActionMutation` from the UI. If the capability is missing, create or update a `defineAction`. Do not add `/api/*`, `server/routes/*`, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.
|
||||
|
||||
## Why
|
||||
|
||||
Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
|
||||
|
||||
## Keep the Action Surface Small and Orthogonal
|
||||
|
||||
Every agent-exposed action is a tool in the model's context window. There is a real cost to each one: more tools means more for the model to read, disambiguate, and choose between, which degrades tool-selection quality. Treat the action list like an API you have to maintain — add the fewest, most orthogonal actions that cover the capability, not one per UI affordance.
|
||||
|
||||
- **Prefer one CRUD-style `update` over N per-field actions.** A single `update-<thing>` that takes a patch of optional fields beats `update-<thing>-name`, `update-<thing>-order`, `update-<thing>-color`, … The agent (and the UI) pass only the fields that change. Same for `create`/`delete` — one orthogonal action per resource, not one per code path.
|
||||
- **Reach for a generic query / escape hatch before minting a new read action.** If the agent needs more or different data, do not add `get-<thing>-by-x`, `list-<thing>-filtered-by-y`, etc. For provider data, expose the shared `provider-api-catalog` / `provider-api-docs` / `provider-api-request` trio (see `templates/dispatch/actions/`) so the agent can hit any endpoint or filter without a new action each time. For app data in dev, the `db-query` tool already answers arbitrary read questions.
|
||||
- **Hide UI-only or purely programmatic actions from the model with `agentTool: false`.** An action that only the frontend or an HTTP/cron caller needs should not spend a slot in the model's tool list. `agentTool: false` keeps it callable from `useActionMutation` / `callAction` / `/_agent-native/actions/<name>` while removing it from every agent tool surface (in-app assistant, MCP, A2A).
|
||||
- **`agentTool: false` is NOT `toolCallable: false`.** They are different switches:
|
||||
- `agentTool: false` → hidden from the **model entirely** (it is no longer a tool the agent can see or call). Still frontend/HTTP-callable.
|
||||
- `toolCallable: false` → only blocks the **sandboxed extension ("tools") iframe bridge** (`appAction(...)`). The action stays fully visible to the model, the UI, the CLI, MCP, and A2A. Use it for high-blast-radius operations (account/org/auth changes), not for trimming the tool list.
|
||||
- **Remove or hide stale actions.** When the UI stops using an action, delete it or set `agentTool: false` — do not leave it exposed to the model as dead tool weight. The advisory audit below helps you spot these.
|
||||
|
||||
### Audit Script (Advisory)
|
||||
|
||||
`pnpm actions:audit [template ...]` (or `node scripts/audit-template-actions.mjs`) statically scans a template's `actions/` and prints two kinds of suggestions:
|
||||
|
||||
1. **Likely UI-dead** — HTTP-exposed mutating actions whose name is never referenced under `app/` (candidates to delete or mark `agentTool: false`).
|
||||
2. **Likely redundant clusters** — groups like `update-foo-name` / `update-foo-order` that could collapse into one orthogonal `update-foo`.
|
||||
|
||||
It is **advisory only**: it always exits 0, never fails CI, and uses conservative heuristics, so expect some false positives (e.g. an action the agent calls but the UI doesn't). Use it as a prompt to review, not a gate.
|
||||
|
||||
## How to Create an Action
|
||||
|
||||
Use `defineAction` with a Zod schema (required for new actions):
|
||||
|
||||
```ts
|
||||
// actions/list-meals.ts
|
||||
import { z } from "zod";
|
||||
import { defineAction } from "@agent-native/core/action";
|
||||
import { getDb } from "../server/db/index.js";
|
||||
import { meals } from "../server/db/schema.js";
|
||||
|
||||
export default defineAction({
|
||||
description: "List all meals",
|
||||
schema: z.object({
|
||||
date: z.string().describe("Filter by date (YYYY-MM-DD)"),
|
||||
}),
|
||||
http: { method: "GET" },
|
||||
run: async (args) => {
|
||||
// args is fully typed: { date: string }
|
||||
const db = getDb();
|
||||
const rows = await db.select().from(meals);
|
||||
return rows; // Return objects/arrays, NOT JSON.stringify()
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
The `schema` field accepts a Zod schema (or any Standard Schema-compatible library). It provides runtime validation with clear error messages (400 for HTTP, error result for agent), full TypeScript type inference for `run()` args, and auto-generated JSON Schema for the agent's tool definition. `zod` is a dependency of all templates.
|
||||
|
||||
When an action reads or writes app data, use Drizzle's query builder and portable operators from `drizzle-orm`. Do not use raw SQL, `getDbExec()`, or dialect-specific schema imports in normal actions unless there is a documented reason Drizzle cannot express the query.
|
||||
|
||||
When an action calls an external service, never hardcode API keys, bearer
|
||||
tokens, webhook URLs, signing secrets, OAuth refresh tokens, private
|
||||
Builder/internal data, or customer data. Read user/org/workspace credentials
|
||||
from `readAppSecret`, `resolveCredential`, OAuth token helpers, or the provider
|
||||
API credential adapter. Use `process.env` only for explicitly deploy-level
|
||||
configuration, and keep examples to obvious placeholders.
|
||||
|
||||
Tips:
|
||||
- Use `.describe()` for parameter descriptions
|
||||
- Use `.optional()` for optional params
|
||||
- Use `z.coerce.number()` for numeric params that arrive as strings from HTTP.
|
||||
For booleans, use an explicit string parser/helper instead of
|
||||
`z.coerce.boolean()` because JavaScript treats any non-empty string,
|
||||
including `"false"`, as truthy.
|
||||
- Use `z.enum(["draft", "published"])` for constrained values
|
||||
|
||||
The legacy `parameters` field (plain JSON Schema object) still works as a fallback but does not provide runtime validation or type inference.
|
||||
|
||||
## Decision Order
|
||||
|
||||
When you need app data or a mutation:
|
||||
|
||||
1. **Use an existing action** if one already performs the operation.
|
||||
2. **Create or extend a `defineAction`** when the agent and UI both need a new operation.
|
||||
3. **Create a custom route only for route-only concerns** such as uploads, streaming, webhooks, OAuth callbacks, or a non-JSON protocol.
|
||||
|
||||
Do not build an umbrella REST API to make actions "easier" to call. Actions are already callable by agents, CLIs, React hooks, HTTP, MCP/A2A exposure, and external hosts through the framework.
|
||||
|
||||
## Flexible Provider APIs
|
||||
|
||||
For provider integrations used in ad hoc analysis, querying, reporting, or
|
||||
cross-source research, do not hardcode every provider endpoint as a separate
|
||||
rigid action and do not encode one lookback window, filter shape, or pagination
|
||||
strategy as the only path the agent can take. Expose the shared provider API
|
||||
action trio instead:
|
||||
|
||||
- `provider-api-catalog`: lists provider base URLs, auth style, credential keys,
|
||||
docs/spec URLs, placeholders, and examples without exposing secrets.
|
||||
- `provider-api-docs`: fetches public provider docs/spec/changelog URLs when
|
||||
the exact endpoint, filter operator, payload shape, or pagination contract is
|
||||
uncertain. Registered docs URLs are curated starting points. Use
|
||||
`responseMode: "markdown"` for clean readable docs, or
|
||||
`responseMode: "matches"` with `search: { query | terms | regex }` for
|
||||
compact snippets instead of flooding context with raw HTML.
|
||||
- `provider-api-request`: makes a constrained authenticated HTTP request to the
|
||||
provider host, injects configured credentials, blocks private/internal URLs,
|
||||
and redacts secrets.
|
||||
|
||||
Use `@agent-native/core/provider-api` as the shared substrate, and build these
|
||||
actions as thin factory imports rather than copying `defineAction` schemas and
|
||||
handlers into each template:
|
||||
|
||||
```ts
|
||||
import {
|
||||
createProviderApiCatalogAction,
|
||||
createProviderApiDocsAction,
|
||||
createProviderApiRequestAction,
|
||||
} from "@agent-native/core/provider-api/actions/provider-api";
|
||||
import {
|
||||
createDeleteStagedDatasetAction,
|
||||
createListStagedDatasetsAction,
|
||||
createQueryStagedDatasetAction,
|
||||
} from "@agent-native/core/provider-api/actions/staged-datasets";
|
||||
```
|
||||
|
||||
Pass the app's existing provider runtime to the provider factories, and pass
|
||||
its app id to the staged-dataset factories. Keep app-specific descriptions,
|
||||
provider allow-lists, HTTP/tool-callability settings, and credential adapters
|
||||
as factory options. Only add a thin credential adapter when the app has
|
||||
app-specific credential lookup rules. If the app stores a built-in provider's
|
||||
OAuth grant under a narrower local provider id, use the runtime's
|
||||
`oauthProviderOverrides` instead of duplicating provider config. If credentials
|
||||
are stored on shareable/resource rows rather than in the shared credential or
|
||||
OAuth-token stores, build a resolver that enforces those access checks before
|
||||
exposing raw provider requests. Keep `provider-api-request` `http: false`
|
||||
unless a separate UI permission model authorizes arbitrary provider writes.
|
||||
Specific actions such as `search-records`, `search-emails`, or `sync-source`
|
||||
are convenience shortcuts, not capability limits; agents should fall back to
|
||||
the provider API trio when a question requires an endpoint or filter that the
|
||||
shortcut does not model.
|
||||
|
||||
This is a framework tenet. The safety boundary should be provider host
|
||||
allow-listing, credential scoping, auth injection, private-network blocking,
|
||||
secret redaction, and user/org access checks, not an artificially small set of
|
||||
hand-authored read actions. If the upstream provider API supports a capability,
|
||||
the agent should normally be able to reach it through `provider-api-request`
|
||||
with the user's configured credentials. For large responses, expose staging
|
||||
(`stageAs`, `itemsPath`, pagination, and `query-staged-dataset`) or sandboxed
|
||||
code execution so the agent can reduce data without flooding context.
|
||||
|
||||
For broad provider questions, cross-source joins, corpus-wide mention/search
|
||||
work, classification, or any answer where absence matters, design the action
|
||||
surface for full coverage instead of convenience-only samples. The agent should
|
||||
be able to fetch every relevant page or an explicitly bounded cohort, stage or
|
||||
save the raw provider response outside chat, and then use
|
||||
`query-staged-dataset`, `run-code`, or provider-side search to count, join,
|
||||
grep, classify, and aggregate. Tool descriptions and AGENTS.md guidance should
|
||||
teach agents to report source, filters, time window, row/record counts,
|
||||
pagination status, truncation, failed pages, and uncovered gaps. They must not
|
||||
turn default limits, sampled rows, truncated excerpts, or aborted calls into a
|
||||
confident "none found", "all records", or exhaustive conclusion.
|
||||
|
||||
For public web pages and docs, prefer the token-efficient path: `web-search`
|
||||
to find likely URLs, `web-request` or `provider-api-docs` with clean
|
||||
`responseMode` output to read a page, and `run-code` with `webRead()` /
|
||||
`webFetch()` when you need to grep, aggregate, or compare many pages before
|
||||
returning a small result.
|
||||
|
||||
For LONG compute, `run-code` supports durable background executions: pass
|
||||
`background: true` and the code is enqueued to a `sandbox_executions` row and
|
||||
executed out-of-band with a generous budget (default 10 min), surviving the
|
||||
hosted agent run's ~40s soft timeout. The call returns
|
||||
`{ executionId, status: "queued" }` immediately with polling guidance; check
|
||||
progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
|
||||
where registered) — results persist after completion. Use background for big
|
||||
cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
|
||||
keep quick scripts in the default foreground mode. Agents should continue
|
||||
other work between polls, and on `failed`/`timed_out` split the computation or
|
||||
persist intermediate progress with `workspaceWrite` and re-run.
|
||||
|
||||
### The `http` Option
|
||||
|
||||
Controls how the action is exposed as an HTTP endpoint:
|
||||
|
||||
| Value | Behavior | Use for |
|
||||
| ------------------------- | ----------------------------------------------------------- | -------------------------------- |
|
||||
| _(omitted)_ | Auto-exposed as `POST /_agent-native/actions/:name` | Write operations (default) |
|
||||
| `{ method: "GET" }` | Auto-exposed as `GET /_agent-native/actions/:name` | Read-only queries |
|
||||
| `{ method: "PUT" }` | Auto-exposed as `PUT /_agent-native/actions/:name` | Update operations |
|
||||
| `{ method: "DELETE" }` | Auto-exposed as `DELETE /_agent-native/actions/:name` | Delete operations |
|
||||
| `{ method: "GET", path: "custom" }` | Auto-exposed as `GET /_agent-native/actions/custom` | Custom route path |
|
||||
| `false` | Agent-only, never exposed as HTTP | `navigate`, `view-screen`, internal actions |
|
||||
|
||||
### Screen Refresh (automatic)
|
||||
|
||||
The framework auto-refreshes the UI after any successful mutating action. On completion of a non-`GET` action, the framework emits a change event with `source: "action"` that the client's `useDbSync` picks up and uses to invalidate `["action"]` React Query keys — so `list-*` / `get-*` hooks refetch without a full page reload. In-process calls emit directly; dev-mode `pnpm action ...` calls also write a durable marker so the web server sees child-process action changes.
|
||||
|
||||
Rules:
|
||||
|
||||
- `http: { method: "GET" }` → read-only, does NOT trigger a refresh (inferred automatically).
|
||||
- Any other action (default `POST`, `PUT`, `DELETE`, or `http: false`) → treated as mutating, triggers a refresh on success.
|
||||
- To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
|
||||
- To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
|
||||
|
||||
Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
|
||||
|
||||
### Return Values
|
||||
|
||||
Actions should return **structured data** (objects, arrays) — not `JSON.stringify()`. The framework serializes the response automatically. If you return a string, the framework tries to parse it as JSON for a clean response.
|
||||
|
||||
```ts
|
||||
// Good — return structured data
|
||||
run: async (args) => {
|
||||
const events = await fetchEvents(args.from, args.to);
|
||||
return events;
|
||||
}
|
||||
|
||||
// Bad — don't stringify
|
||||
run: async (args) => {
|
||||
const events = await fetchEvents(args.from, args.to);
|
||||
return JSON.stringify(events, null, 2);
|
||||
}
|
||||
```
|
||||
|
||||
### Returning Images the Agent Can See (`_agentImages`)
|
||||
|
||||
An action's return object may include the well-known optional field
|
||||
`_agentImages` to attach vision images (screenshots, chart previews, rendered
|
||||
designs) to the tool result. The agent literally sees them — enabling visual
|
||||
self-review loops — while the field itself is stripped from the JSON text the
|
||||
model reads.
|
||||
|
||||
```ts
|
||||
run: async ({ dashboardId }) => {
|
||||
const shot = await renderDashboardPng(dashboardId); // Buffer
|
||||
return {
|
||||
dashboardId,
|
||||
panelCount: 6,
|
||||
_agentImages: [
|
||||
// Either a public https URL (preferred — the provider fetches it)…
|
||||
{ url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
|
||||
// …or base64 without a data: prefix (mediaType required; a full
|
||||
// data:image/png;base64,… URL in `data` is also accepted and parsed).
|
||||
{ data: shot.toString("base64"), mediaType: "image/png" },
|
||||
],
|
||||
};
|
||||
},
|
||||
```
|
||||
|
||||
Rules and limits:
|
||||
|
||||
- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
|
||||
Each entry needs `url` (https only) **or** `data`. Supported media types:
|
||||
`image/jpeg`, `image/png`, `image/gif`, `image/webp`.
|
||||
- Caps: max **4 images** per result; max **~2MB of base64** per image.
|
||||
Over-cap or invalid entries never fail the call — they become text notes in
|
||||
the result telling the model what was dropped and why.
|
||||
- Persistence: the run ledger stores only the string result plus compact
|
||||
`[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
|
||||
never the payload. Images are re-attached only for the live turn; replayed
|
||||
history is text-only, so prefer stable `url` images the model can re-request.
|
||||
- Engine support: native Anthropic and vision-capable AI-SDK providers
|
||||
(anthropic, openai, google, openrouter) receive real image blocks; other
|
||||
paths (Builder gateway, non-vision providers) degrade to the text notes.
|
||||
- External MCP tools need no changes — standard MCP `image` content parts are
|
||||
converted automatically under the same caps.
|
||||
|
||||
### Validating Return Values (`outputSchema`)
|
||||
|
||||
`schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.
|
||||
|
||||
```ts
|
||||
export default defineAction({
|
||||
description: "Summarize a thread.",
|
||||
schema: z.object({ threadId: z.string() }),
|
||||
outputSchema: z.object({ summary: z.string(), messageCount: z.number() }),
|
||||
outputErrorStrategy: "warn", // default; "strict" | "fallback"
|
||||
// outputFallback: { summary: "", messageCount: 0 }, // used only by "fallback"
|
||||
run: async ({ threadId }) => {
|
||||
/* ... */
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
- `"warn"` (default) — `console.warn` the issues and return the **original** result unchanged. Non-breaking.
|
||||
- `"strict"` — throw a clear error so a buggy action surfaces loudly.
|
||||
- `"fallback"` — return `outputFallback` in place of the invalid result.
|
||||
|
||||
On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
|
||||
|
||||
### Human-in-the-Loop Approval (`needsApproval`)
|
||||
|
||||
For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:
|
||||
|
||||
```ts
|
||||
export default defineAction({
|
||||
description: "Send an email via Gmail.",
|
||||
schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
|
||||
needsApproval: true, // boolean, or (args, ctx) => boolean | Promise<boolean>
|
||||
run: async (args) => {
|
||||
/* ...actually send... */
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
|
||||
|
||||
**Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.
|
||||
|
||||
## Frontend Hooks
|
||||
|
||||
The frontend calls actions using React Query hooks from `@agent-native/core/client`. Components should not hand-write `fetch("/_agent-native/actions/...")`; add or reuse a client hook/helper instead. Use `callAction` from the same package for imperative cases that do not fit a hook, such as debounced search, prefetching, or non-React event handlers.
|
||||
|
||||
### `useActionQuery` — for GET actions
|
||||
|
||||
```ts
|
||||
import { useActionQuery } from "@agent-native/core/client/hooks";
|
||||
|
||||
function MealList() {
|
||||
// Types are auto-inferred from the action's schema + return type — no manual generic needed
|
||||
const { data: meals } = useActionQuery("list-meals", {
|
||||
date: "2025-01-01",
|
||||
});
|
||||
return <ul>{meals?.map((m) => <li key={m.id}>{m.name}</li>)}</ul>;
|
||||
}
|
||||
```
|
||||
|
||||
### `useActionMutation` — for POST/PUT/DELETE actions
|
||||
|
||||
```ts
|
||||
import { useActionMutation } from "@agent-native/core/client/hooks";
|
||||
|
||||
function AddMealButton() {
|
||||
// Types are auto-inferred — no manual generic needed
|
||||
const { mutate } = useActionMutation("log-meal");
|
||||
return (
|
||||
<button onClick={() => mutate({ name: "Salad", calories: 350 })}>
|
||||
Log Meal
|
||||
</button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Do NOT use manual type generics** like `useActionQuery<Meal[]>(...)`. Types are inferred automatically from `.generated/action-types.d.ts`, which is auto-generated by a Vite plugin.
|
||||
|
||||
Mutations automatically invalidate all `["action"]` query keys on success, so GET queries refetch.
|
||||
|
||||
### `callAction` — for imperative client code
|
||||
|
||||
```ts
|
||||
import { callAction } from "@agent-native/core/client/hooks";
|
||||
|
||||
const people = await callAction("search-people", { query }, { method: "GET" });
|
||||
```
|
||||
|
||||
Prefer hooks in React data flows. Use `callAction` when a hook would be awkward;
|
||||
do not hand-write action route fetches in components.
|
||||
|
||||
## How to Run (Agent)
|
||||
|
||||
```bash
|
||||
pnpm action my-action --input data/source.json --output data/result.json
|
||||
```
|
||||
|
||||
## Action Dispatcher
|
||||
|
||||
The default template uses core's `runScript()` in `actions/run.ts`:
|
||||
|
||||
```ts
|
||||
import { runScript } from "@agent-native/core";
|
||||
runScript();
|
||||
```
|
||||
|
||||
This is the canonical approach for new apps. Action names must be lowercase with hyphens only (e.g., `my-action`).
|
||||
|
||||
## When You Still Need Custom `/api/` Routes
|
||||
|
||||
Most operations should be actions. You only need custom routes in `server/routes/api/` for:
|
||||
|
||||
- **File uploads** — actions receive JSON params, not multipart form data
|
||||
- **Streaming responses** — SSE or chunked responses that need direct H3 control
|
||||
- **Webhooks** — external services POST to a specific URL
|
||||
- **OAuth callbacks** — redirect-based flows that need specific URL patterns
|
||||
|
||||
When the agent needs a durable image or file URL, call the core `upload-image`
|
||||
action or use `uploadFile()` in server code. Do not write base64 into SQL,
|
||||
markdown, deck/design JSON, or action results. `_agentImages` on action results
|
||||
is for ephemeral vision previews only, not persistence.
|
||||
|
||||
If it's a standard CRUD operation, data query, or a wrapper around an action, use the action instead.
|
||||
|
||||
## Legacy Pattern (bare export)
|
||||
|
||||
Older actions use a bare async function export with `parseArgs`:
|
||||
|
||||
```ts
|
||||
import { parseArgs, loadEnv, fail } from "@agent-native/core";
|
||||
|
||||
export default async function myAction(args: string[]) {
|
||||
loadEnv();
|
||||
const parsed = parseArgs(args);
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all new actions.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **One action, one job.** Keep actions focused on a single operation. The agent composes multiple action calls for complex operations.
|
||||
- **Return structured data.** Return objects/arrays, not `JSON.stringify()`.
|
||||
- **Use `http: { method: "GET" }`** for read-only actions. Default is POST.
|
||||
- **Use `http: false`** for agent-only actions (`navigate`, `view-screen`).
|
||||
- **Use `agentTool: false`** for UI-only / programmatic actions that should NOT be a tool in the model's context window. It stays frontend/HTTP-callable but is hidden from the agent. Distinct from `toolCallable: false`, which only blocks the sandboxed extension iframe bridge.
|
||||
- **Document reusable actions.** If a new action should be called by agents outside one narrow screen, update `AGENTS.md` with when to use it, important args, and which return fields to preserve.
|
||||
- **Promote workflow-heavy actions to skills.** If the action is part of a provider-backed, cross-app, MCP/A2A, or multi-step workflow, create or update a skill in `.agents/skills/` and add app-skill visibility (`internal`, `exported`, or `both`) when it should ship through a marketplace.
|
||||
- **Use `loadEnv()`** only for deploy-level configuration. User/org/workspace
|
||||
credentials belong in the encrypted secrets/credential/OAuth stores, never as
|
||||
hardcoded literals or shared env fallbacks.
|
||||
- **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
|
||||
- **Import action primitives from `@agent-native/core/action`** and CLI helpers such as `parseArgs()` from `@agent-native/core` — do not redefine framework utilities locally.
|
||||
- **Do not re-export actions as REST.** The mounted `/_agent-native/actions/:name` endpoint is the REST surface; duplicating it under `/api/*` creates drift and hides the operation from agents.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
**Read action (GET):**
|
||||
|
||||
```ts
|
||||
import { z } from "zod";
|
||||
import { defineAction } from "@agent-native/core/action";
|
||||
|
||||
export default defineAction({
|
||||
description: "List calendar events",
|
||||
schema: z.object({
|
||||
from: z.string().describe("Start date"),
|
||||
to: z.string().describe("End date"),
|
||||
}),
|
||||
http: { method: "GET" },
|
||||
run: async (args) => {
|
||||
return await fetchEvents(args.from, args.to);
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**Write action (POST, default):**
|
||||
|
||||
```ts
|
||||
import { z } from "zod";
|
||||
import { defineAction } from "@agent-native/core/action";
|
||||
|
||||
export default defineAction({
|
||||
description: "Log a meal",
|
||||
schema: z.object({
|
||||
name: z.string().describe("Meal name"),
|
||||
calories: z.coerce.number().describe("Calorie count"),
|
||||
}),
|
||||
run: async (args) => {
|
||||
// args.calories is a number — z.coerce.number() handles string-to-number conversion from HTTP
|
||||
const meal = await insertMeal(args);
|
||||
return meal;
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**Agent-only action:**
|
||||
|
||||
```ts
|
||||
import { z } from "zod";
|
||||
import { defineAction } from "@agent-native/core/action";
|
||||
|
||||
export default defineAction({
|
||||
description: "Navigate the UI to a view",
|
||||
schema: z.object({
|
||||
view: z.string().describe("Target view"),
|
||||
}),
|
||||
http: false,
|
||||
run: async (args) => {
|
||||
await writeAppState("navigate", { command: "go", view: args.view });
|
||||
return "Navigated";
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Action not found** — Check that the filename matches the command name exactly. `pnpm action foo-bar` looks for `actions/foo-bar.ts`.
|
||||
- **Args not parsing** — Ensure args use `--key value` or `--key=value` format. Boolean flags use `--flag` (sets value to `"true"`).
|
||||
- **Frontend getting 405** — The action's `http.method` doesn't match the hook. Use `useActionQuery` for GET actions, `useActionMutation` for POST/PUT/DELETE.
|
||||
- **Frontend getting undefined** — Make sure the action returns structured data, not `JSON.stringify()`.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **storing-data** — Actions read/write data in SQL
|
||||
- **delegate-to-agent** — The agent invokes actions via `pnpm action <name>`
|
||||
- **real-time-sync** — Database writes from actions trigger change events to update the UI
|
||||
- **adding-a-feature** — Actions are area 2 of the four-area checklist
|
||||
- **client-methods** — Client code uses named helpers/hooks instead of raw REST calls
|
||||
@@ -0,0 +1,189 @@
|
||||
---
|
||||
name: adding-a-feature
|
||||
description: >-
|
||||
The four-area checklist every new feature must complete. Use when adding any
|
||||
feature, integration, or capability to ensure the agent and UI stay in parity.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Adding a Feature — The Four-Area Checklist
|
||||
|
||||
## Rule
|
||||
|
||||
Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
|
||||
|
||||
## Why
|
||||
|
||||
Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.
|
||||
|
||||
## The Checklist
|
||||
|
||||
When you add a new feature, work through these four areas in order:
|
||||
|
||||
### 1. UI Component
|
||||
|
||||
Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations. Do not create a custom REST endpoint just so React can call action-backed data; the action endpoint already exists.
|
||||
|
||||
**Auto-refresh on agent writes is non-negotiable** — when the agent mutates data, the UI must reflect the change without a manual refresh. There are two paths, and you must pick the right one:
|
||||
|
||||
- **`useActionQuery` / `useActionMutation`** — covered automatically. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches on agent activity. No extra wiring required. **Prefer this path.**
|
||||
- **Raw `useQuery` with custom keys** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `action` source is the reliable signal (the agent runner emits it after every successful tool call); the resource-specific source (`"dashboards"`, `"analyses"`, `"settings"`, etc.) is bonus when emitted. Without this wiring, agent writes will be invisible until manual refresh — that breaks the framework's #1 promise.
|
||||
|
||||
```tsx
|
||||
import { useChangeVersions } from "@agent-native/core/client/hooks";
|
||||
import { useQuery } from "@tanstack/react-query";
|
||||
|
||||
const v = useChangeVersions(["dashboards", "action"]);
|
||||
useQuery({
|
||||
queryKey: ["dashboard", id, v],
|
||||
queryFn: () => fetchDashboard(id),
|
||||
placeholderData: (prev) => prev, // no flicker on refetch
|
||||
});
|
||||
```
|
||||
|
||||
See the `real-time-sync` skill for the full pattern and source catalog.
|
||||
|
||||
### 2. Action
|
||||
|
||||
Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the UI calls it through `useActionQuery` / `useActionMutation` while the framework owns the HTTP transport. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
|
||||
|
||||
Before adding a new route or endpoint, inspect the existing actions. Reuse an
|
||||
action if it already covers the business operation, extend it if the shared
|
||||
contract is incomplete, or create a new `defineAction` if the agent and UI both
|
||||
need the capability. Do not add pass-through `/api/*` routes that re-export
|
||||
actions. If client code needs a new framework/app route, expose a named helper
|
||||
or hook first and use that helper from components and docs.
|
||||
|
||||
For provider-backed analysis/query/reporting integrations, do not turn every
|
||||
provider endpoint or filter into a rigid action. Prefer the shared
|
||||
`provider-api-catalog` / `provider-api-docs` / `provider-api-request` pattern
|
||||
from `@agent-native/core/provider-api`, then add narrow convenience actions only
|
||||
for workflows that truly deserve a first-class shortcut. Treat this as a
|
||||
capability requirement, not a nice-to-have: convenience actions must not become
|
||||
the ceiling of what the agent can ask the provider to do. Pair broad provider
|
||||
access with staging or sandboxed code execution when responses may be too large
|
||||
for chat context. If provider credentials live on resource/share rows, add the
|
||||
scoped resolver first so broad access preserves the same ownership boundary as
|
||||
the app UI.
|
||||
|
||||
If the feature needs credentials, design the credential path in the same change.
|
||||
Never hardcode API keys, tokens, webhook URLs, signing secrets, private
|
||||
Builder/internal data, or customer data in the action, UI, seed data, fixtures,
|
||||
docs, prompts, or generated extension/app content. Register required secrets,
|
||||
use OAuth helpers, or read scoped values from the vault/credential store.
|
||||
|
||||
If the feature involves attachments, images, recordings, screenshots, exports,
|
||||
or other file-like payloads, design the upload path in the same change:
|
||||
provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary
|
||||
columns or stuff files into `application_state`.
|
||||
|
||||
**If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
|
||||
|
||||
### 3. Skills / Instructions
|
||||
|
||||
Update `AGENTS.md` and/or create a skill in `.agents/skills/` if the feature introduces patterns the agent needs to know. At minimum, add the new actions to the action table in the template's `AGENTS.md`.
|
||||
|
||||
Reusable actions are part of the app contract, not just implementation detail. When an action is useful outside one screen, update agent instructions in the same change so app agents know when to call it, which arguments matter, and what output to preserve. If the capability is workflow-heavy, cross-app, provider-backed, or has a non-obvious sequence of actions, add or update a skill instead of burying the behavior in one long `AGENTS.md` paragraph.
|
||||
|
||||
Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
|
||||
placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
|
||||
real keys, internal data, or customer data into instructions as examples.
|
||||
|
||||
If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
|
||||
states, or formatting, read `internationalization` and update the app's i18n
|
||||
catalogs in the same change.
|
||||
|
||||
For app-backed skills, declare skill visibility in the app-skill manifest:
|
||||
|
||||
- `internal` — only the app's own agents should use it.
|
||||
- `exported` — marketplace installs receive it, but the app does not need it loaded internally.
|
||||
- `both` — shared between the app's internal agents and exported marketplace bundles.
|
||||
|
||||
### 4. Application State Sync
|
||||
|
||||
Expose navigation and selection state so the agent knows what the user is looking at. Write to the `navigation` app-state key on route changes. Update the `view-screen` action to fetch relevant data for the new feature. Add a `navigate` command if the agent needs to open the new view.
|
||||
|
||||
## Examples
|
||||
|
||||
### Adding "compose email" to a mail app
|
||||
|
||||
| Area | What to build |
|
||||
| --------------- | ---------------------------------------------------------------------------------------- |
|
||||
| UI | Compose panel with tabs, to/cc/bcc fields, body editor. Use `useActionQuery`/`useActionMutation` for data. |
|
||||
| Action | `manage-draft` action (create/update/delete drafts), `send-email` action |
|
||||
| Skills/AGENTS | Document compose state shape, draft lifecycle, action args in AGENTS.md |
|
||||
| App-state sync | `compose-{id}` keys for each draft tab, `navigation` includes compose state |
|
||||
|
||||
### Adding "create form" to a forms app
|
||||
|
||||
| Area | What to build |
|
||||
| --------------- | ---------------------------------------------------------------------------------------- |
|
||||
| UI | Form builder page with drag-and-drop fields, preview, settings. Use `useActionQuery` for lists. |
|
||||
| Action | `create-form` action, `update-form` action, `list-forms` action (GET) |
|
||||
| Skills/AGENTS | Document form schema shape, field types, validation rules in AGENTS.md |
|
||||
| App-state sync | `navigation` includes `{ view: "form-builder", formId: "..." }`, `view-screen` fetches form data |
|
||||
|
||||
### Adding "chart type" to an analytics app
|
||||
|
||||
| Area | What to build |
|
||||
| --------------- | ---------------------------------------------------------------------------------------- |
|
||||
| UI | New chart component, chart type selector in dashboard |
|
||||
| Action | `create-chart` or `update-dashboard` action that sets chart type and config |
|
||||
| Skills/AGENTS | Document supported chart types, config options, data requirements |
|
||||
| App-state sync | `navigation` includes selected chart/dashboard, `view-screen` returns chart config |
|
||||
|
||||
## Adding a new route
|
||||
|
||||
Templates are single-page apps with client-side routing. The app shell (AgentSidebar + top-level nav) MUST persist across navigation — it is mounted once, either in `root.tsx` around `<Outlet />` or via a pathless `_app.tsx` layout route that all authed routes nest under.
|
||||
|
||||
**Never wrap each new route in its own `<AppLayout>` / `<Layout>`.** That causes React to unmount the entire app shell on every navigation, reloading the agent sidebar and destroying in-progress work.
|
||||
|
||||
- If the template has `<AppLayout>` in `root.tsx` — just render page content in your new route file, nothing else.
|
||||
- If the template has `app/routes/_app.tsx` (pathless layout) — name your new route `_app.<segment>.tsx` to inherit the shell, or bare `<segment>.tsx` for public routes that should NOT have the shell.
|
||||
- If a page needs per-route data (e.g. highlighting the active item in the sidebar), read it in the layout from `useParams()` / `useLocation()`. Don't pass it as a prop through every route file.
|
||||
|
||||
See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- **Per-route `<AppLayout>` wrappers** — Every route file wraps its content in `<AppLayout>` or `<Layout>`. React sees a different component at the outlet on each nav and unmounts the whole shell, causing the agent sidebar to reload on every click. Mount the shell once above `<Outlet />` (root.tsx or `_app.tsx` pathless layout).
|
||||
- **UI without actions** — The user can create forms but the agent cannot. The agent says "I don't have access to that" when it should be able to do it.
|
||||
- **Actions without AGENTS.md** — The actions exist but the agent doesn't know about them because they're not documented. The agent reinvents solutions instead of using the actions.
|
||||
- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle, including pass-through routes that just call or repackage an action. Use `useActionQuery`/`useActionMutation` instead.
|
||||
- **Raw client route calls** — Teaching or adding `fetch("/_agent-native/...")`,
|
||||
`fetch(agentNativePath(...))`, or template `/api/*` calls in components for
|
||||
normal app work. Add a named client helper/hook and call that instead.
|
||||
- **Features without app-state** — The agent cannot see that the user is looking at a specific form, email, or chart. It asks "which one?" instead of acting on the current selection.
|
||||
- **Actions without UI** — The agent can do something the user cannot. This is less common but still breaks parity.
|
||||
|
||||
## Verification
|
||||
|
||||
After completing all four areas, verify:
|
||||
|
||||
1. Can the user perform the operation from the UI?
|
||||
2. Can the agent perform the same operation via actions?
|
||||
3. Does `pnpm action view-screen` show the relevant state when the user is using the feature?
|
||||
4. Can the agent navigate to the feature view via the `navigate` action?
|
||||
5. Is the feature documented in AGENTS.md with action names and args?
|
||||
6. Are credentials and sensitive data supplied only through approved runtime
|
||||
channels, with no hardcoded real keys, tokens, webhook URLs, Builder/internal
|
||||
data, or customer data?
|
||||
|
||||
## One more area — sharing
|
||||
|
||||
If the feature stores **user-authored resources** (documents, dashboards, forms, decks, etc.), make them ownable so they get private-by-default semantics and a share dialog for free. See the `sharing` skill.
|
||||
|
||||
TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
|
||||
- **context-awareness** — How to expose UI state to the agent (area 4 in detail)
|
||||
- **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)
|
||||
- **external-agents** — Add a `link` builder so external agents (MCP/A2A) get an "Open in … →" deep link
|
||||
- **create-skill** — How to create skills for new patterns (area 3 in detail)
|
||||
- **storing-data** — Where to store the feature's data
|
||||
- **real-time-sync** — How the UI stays in sync when the agent writes data
|
||||
- **internationalization** — How to update localized UI copy and catalogs
|
||||
@@ -0,0 +1,115 @@
|
||||
---
|
||||
name: agent-native-docs
|
||||
description: >-
|
||||
How to find version-matched Agent Native framework docs and source bundled in
|
||||
node_modules. Use before implementing or answering questions about
|
||||
@agent-native/core APIs, generated apps, workspaces, templates, or advanced
|
||||
features.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Agent Native Docs Lookup
|
||||
|
||||
## Rule
|
||||
|
||||
Before implementing or explaining non-trivial Agent Native behavior, read the
|
||||
version-matched docs installed with `@agent-native/core`. When examples,
|
||||
imports, or implementation details matter, inspect the packaged source corpus
|
||||
too.
|
||||
|
||||
## Why
|
||||
|
||||
Generated apps and workspaces may be on a different framework version than the
|
||||
public docs or model memory. The installed package is the source that matches
|
||||
the app in front of you. It also includes a source-only corpus of core and
|
||||
first-party templates so agents can replicate current best-practice patterns
|
||||
without needing the framework monorepo checkout.
|
||||
|
||||
## How
|
||||
|
||||
From a generated app directory:
|
||||
|
||||
```bash
|
||||
pnpm action docs-search --query "<feature>"
|
||||
pnpm action docs-search --slug <slug>
|
||||
pnpm action docs-search --list
|
||||
pnpm action source-search --query "<pattern>"
|
||||
pnpm action source-search --path templates/plan/AGENTS.md
|
||||
pnpm action source-search --path toolkit/src/index.ts
|
||||
pnpm action source-search --list
|
||||
```
|
||||
|
||||
The headless `pnpm agent` loop and built-in app agent also expose a read-only
|
||||
`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
|
||||
read-only `source-search` tool with `query`, `path`, and `list`.
|
||||
|
||||
If the action runner is unavailable, search the package directly:
|
||||
|
||||
```bash
|
||||
rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
|
||||
rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
|
||||
```
|
||||
|
||||
Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
|
||||
under `node_modules/@agent-native/core/docs/content/`. For source examples,
|
||||
read files under `node_modules/@agent-native/core/corpus/core/` or
|
||||
`node_modules/@agent-native/core/corpus/templates/`.
|
||||
|
||||
Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
|
||||
readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
|
||||
`customizing-agent-native` before taking ownership of a shared component: inspect package
|
||||
source as a read-only reference, then configure, compose, or eject the smallest
|
||||
supported unit into app-owned source. Preserve public actions, application
|
||||
state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
|
||||
deep-import its private source. Manual copying is only the fallback described by
|
||||
an unknown third-party package's add-style blueprint.
|
||||
|
||||
## Reuse Proven Patterns (rg + cp)
|
||||
|
||||
Version-matched installed source outranks web docs or memory: it is the exact
|
||||
code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
|
||||
holds source for every first-party template, not just the one this app started
|
||||
from, so a pattern from the mail template is fair game for a tasks app. Grep
|
||||
across it, then copy a whole file as a starting point instead of writing the
|
||||
pattern from scratch:
|
||||
|
||||
```bash
|
||||
# Find how other templates solved a similar problem
|
||||
rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
|
||||
|
||||
# Grab a proven action file as a starting point, then adapt names/schema
|
||||
cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
|
||||
actions/archive-item.ts
|
||||
|
||||
# Read the full framework source behind an API, not just the corpus copy
|
||||
rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
|
||||
```
|
||||
|
||||
Copying template-level app code (actions, components, skill files) is the
|
||||
expected reuse path — templates exist to be forked. This is different from
|
||||
copying `core`/`toolkit` **runtime internals**: for those, follow
|
||||
`customizing-agent-native`'s configure/compose/eject ladder instead of
|
||||
hand-duplicating framework logic.
|
||||
|
||||
## Useful Slugs
|
||||
|
||||
| Need | Slugs |
|
||||
| ------------------------------ | ------------------------------------------------------------- |
|
||||
| Actions and typed client calls | `actions`, `client` |
|
||||
| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
|
||||
| UI state visible to the agent | `context-awareness` |
|
||||
| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
|
||||
| Automations and schedules | `automations`, `recurring-jobs` |
|
||||
| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
|
||||
| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
|
||||
|
||||
## Don't
|
||||
|
||||
- Do not rely on memory for framework APIs when package docs are present.
|
||||
- Do not add custom REST wrappers for app data before reading `actions`.
|
||||
- Do not add inline LLM calls before reading `using-your-agent` and
|
||||
`agent-surfaces`.
|
||||
- Do not copy framework runtime internals when a public API or narrow UI copy
|
||||
will do; read `customizing-agent-native` for the supported override ladder.
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
name: agent-native-toolkit
|
||||
description: >-
|
||||
Inventory and ownership rules for shared Agent Native workspace UI. Use
|
||||
before building app chrome, settings, navigation, sharing, collaboration,
|
||||
setup, history, comments, chat rails, agent UX, or repeated workspace behavior.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Agent-Native Toolkit
|
||||
|
||||
Use this skill when deciding whether app chrome, settings, collaboration,
|
||||
sharing, navigation, organization, setup, history, comments, or agent UX should
|
||||
be built app-locally or moved into reusable framework/toolkit pieces.
|
||||
|
||||
## Core Rule
|
||||
|
||||
Apps own domain models, domain actions, and product-specific workflows. The
|
||||
framework and `@agent-native/toolkit` own repeated workspace behavior users
|
||||
expect to work the same everywhere.
|
||||
|
||||
Move behavior into shared toolkit primitives when it is:
|
||||
|
||||
- workspace-wide, such as settings, nav, search, org membership, or setup
|
||||
- agent-visible, such as context, actions, run progress, or proof-of-done
|
||||
- governed, such as secrets, permissions, sharing, audit, or billing
|
||||
- repeated by two or more apps
|
||||
- not tied to one domain model
|
||||
|
||||
Keep behavior app-local when the abstraction would hide important domain
|
||||
language or make a simple app-specific workflow harder to understand.
|
||||
|
||||
## Discover Before Building
|
||||
|
||||
Before creating an app-local version of repeated workspace or agent UI:
|
||||
|
||||
1. Check the reusable kits below and the installed package documentation.
|
||||
2. Search installed public components and source with `docs-search` and
|
||||
`source-search`.
|
||||
3. Run `agent-native eject --list` to see the version-matched units published
|
||||
by the packages installed in this app.
|
||||
4. Read `customizing-agent-native` and configure, compose, or eject the
|
||||
smallest unit instead of recreating shared behavior from memory.
|
||||
|
||||
Use public package exports at runtime. Published source and ejection manifests
|
||||
are discovery and ownership-transfer mechanisms, not private runtime APIs.
|
||||
|
||||
## Design-System Boundary
|
||||
|
||||
Every app keeps an explicit design-system seam in `app/design-system.ts` using
|
||||
`defineDesignSystem` from `@agent-native/toolkit/design-system`, and supplies it
|
||||
to `ToolkitProvider`. The semantic contract contains:
|
||||
|
||||
- nine leaf components: `ActionButton`, `IconButton`, `TextField`, `TextArea`,
|
||||
`Spinner`, `Skeleton`, `Status`, `Surface`, and `Avatar`
|
||||
- eight behavior components: `Tooltip`, `Menu`, `Popover`, `Dialog`, `Picker`,
|
||||
`Checkbox`, `Switch`, and `Tabs`
|
||||
|
||||
These are semantic contracts, not styling contracts. An adapter may use
|
||||
Tailwind/shadcn, MUI-style theme providers, React Aria, CSS modules, CSS-in-JS,
|
||||
or another React design system. Do not assume CVA, utility classes, or even a
|
||||
`className`; behavior adapters may supply their overlay and focus
|
||||
implementation wholesale while honoring portal, focus-restoration, keyboard,
|
||||
dismissal, ARIA, and z-index interoperability.
|
||||
|
||||
Pages, routes, and domain components import ordinary controls through the app's
|
||||
local adapter layer, usually `@/components/ui/*`. They must not import
|
||||
`@agent-native/toolkit/ui/*` directly. Toolkit feature exports are still the
|
||||
right home for shared workspace behavior; their presentation flows through the
|
||||
registered semantic components, feature controller, and product-level slots.
|
||||
|
||||
Customer adapter packages are normal npm packages imported explicitly by the
|
||||
app. Never auto-detect them or load React components from JSON. Run the adapter
|
||||
against `@agent-native/toolkit/conformance` in customer CI before adopting it.
|
||||
|
||||
## Settings Direction
|
||||
|
||||
Durable settings belong in the Settings app or a registered settings route. The
|
||||
agent sidebar should not become a second settings app. It can show contextual
|
||||
quick controls and deep links such as:
|
||||
|
||||
- `/settings/ai`
|
||||
- `/settings/connections`
|
||||
- `/settings/secrets`
|
||||
- `/settings/usage`
|
||||
- `/settings/apps/:appId`
|
||||
|
||||
The shared Account section is the canonical profile surface at
|
||||
`/settings#account`. It owns the editable display name and existing avatar
|
||||
control through the authenticated `get-user-profile` and `update-user-profile`
|
||||
actions. Shared workspace chrome such as `OrgSwitcher` should link to this
|
||||
surface rather than creating an app-local profile page.
|
||||
|
||||
When adding a new API key, OAuth grant, provider connection, model selector, app
|
||||
preference, notification preference, or usage/billing surface, register it as a
|
||||
settings tab or app settings panel first. Only add sidebar UI when it is needed
|
||||
in the moment of agent use.
|
||||
|
||||
## Reusable Kits
|
||||
|
||||
- **Settings kit**: a searchable settings page with account, workspace, AI
|
||||
models, LLM keys, connections, secrets, usage, notifications, changelog, and
|
||||
app-specific panels. Search is on by default; register a `SettingsSearchEntry`
|
||||
per control so users find settings by name across tabs.
|
||||
- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
|
||||
remote selections, recent edit highlights, real-time sync indicators, and
|
||||
undo/redo grouping.
|
||||
- **Sharing kit**: private/workspace/org/public-link access, invites, roles,
|
||||
expirations, agent-readable links, and resource registration.
|
||||
- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,
|
||||
command palette entries, recent resources, pinned resources, and global search.
|
||||
- **Organization kit**: folders, tags, favorites, archive, trash, ownership,
|
||||
membership, and common resource metadata.
|
||||
- **Setup and connections kit**: declarative setup requirements, model readiness,
|
||||
missing-secret states, OAuth grants, and provider connection health.
|
||||
- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
|
||||
approval, generative UI, progress, and screen-state exposure.
|
||||
- **Chat history kit**: presentational chat lists and recent-chat rails belong
|
||||
in Toolkit; Core keeps thread persistence, agent execution, transport, and
|
||||
page-to-sidebar handoff. Use Toolkit's `ChatHistoryRail` for the standard
|
||||
five-item sidebar preview and a footer row with New chat followed by an
|
||||
ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
|
||||
actions.
|
||||
- **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
|
||||
`@agent-native/core/client`) with Context, Files, Connections, Jobs, and
|
||||
Access tabs plus a Personal/Organization scope toggle. The canonical home
|
||||
for context transparency, MCP servers, A2A remote agents, recurring
|
||||
jobs/automations, and external-client connect flows. See the `agent-page`
|
||||
skill.
|
||||
- **History and recovery kit**: audit log, activity feed, version history,
|
||||
checkpoints, undo, redo, restore, and proof-of-done.
|
||||
- **Comments and review kit**: anchored comments, pins, mentions, review
|
||||
requests, resolved threads, agent follow-up tasks, and notifications.
|
||||
- **Workflow and observability kit**: notifications, approvals, scheduled work,
|
||||
background runs, recurring jobs, traces, evals, feedback, and run timelines.
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
When adding or refactoring one of these areas:
|
||||
|
||||
1. Search existing framework and template code for duplicated UI or actions.
|
||||
2. Decide the shared contract: data shape, action API, feature-level headless
|
||||
controller, default view, semantic components, and product-level render
|
||||
slots.
|
||||
3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
|
||||
4. Expose the same capability to the UI and agent through actions or documented
|
||||
client helpers.
|
||||
5. Register app-specific labels, routes, resource adapters, and settings panels
|
||||
instead of hardcoding app names in core UI.
|
||||
6. Update docs and relevant skills so future apps discover the shared path.
|
||||
7. Keep the component easy to adopt piecemeal: expose props/slots first and
|
||||
ship readable source plus a complete ejection unit so apps can take ownership
|
||||
of the smallest feature when needed. See `customizing-agent-native` for the
|
||||
configure → compose → eject → propose seam ladder.
|
||||
8. Keep one controller as the source of truth for the default and custom render
|
||||
paths. A custom design must not fork actions, analytics, async state, or
|
||||
accessibility behavior.
|
||||
9. Verify the default adapter and at least one non-Tailwind adapter with the
|
||||
conformance kit, including focus and portal stacking across mixed overlay
|
||||
implementations.
|
||||
|
||||
## Related Skills
|
||||
|
||||
Read these alongside this skill when the work touches the specific area:
|
||||
|
||||
- `sharing`
|
||||
- `real-time-collab`
|
||||
- `real-time-sync`
|
||||
- `client-side-routing`
|
||||
- `context-awareness`
|
||||
- `onboarding`
|
||||
- `secrets`
|
||||
- `audit-log`
|
||||
- `observability`
|
||||
- `frontend-design`
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: capture-learnings
|
||||
description: >-
|
||||
Capture and apply accumulated knowledge via structured memory. Use when the
|
||||
user gives feedback, shares preferences, corrects a mistake, or when you
|
||||
discover something worth remembering for future conversations.
|
||||
user-invocable: false
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Capture Learnings
|
||||
|
||||
This is background knowledge, not a slash command. **Organization learnings and your personal memory index are loaded at the start of every conversation, including Slack/integration turns.** Capture durable context proactively when you learn something worth remembering.
|
||||
|
||||
## How to Read & Write Memories
|
||||
|
||||
Memories are stored as **resources** in the SQL database, not as files on disk.
|
||||
|
||||
- **Team/organization knowledge:** shared `LEARNINGS.md`. Read it first, merge the new fact, then write the full updated file with the `resources` tool using `scope: "shared"`. Shared scope resolves to the active organization; it must never leak to another organization in the same deployment.
|
||||
- **Personal knowledge:** `memory/MEMORY.md` plus `memory/<name>.md`, written with `save-memory`.
|
||||
|
||||
- **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."`
|
||||
- **Read a memory:** `resource-read --path memory/<name>.md`
|
||||
- **Delete a memory:** `delete-memory --name <name>`
|
||||
- **List all memories:** `resource-list --prefix memory/`
|
||||
|
||||
## Memory Types
|
||||
|
||||
| Type | Use for |
|
||||
|------|---------|
|
||||
| `user` | Preferences, role, personal context, contacts |
|
||||
| `feedback` | Corrections, confirmed approaches, things to avoid or repeat |
|
||||
| `project` | Ongoing work context, decisions, deadlines, status |
|
||||
| `reference` | Pointers to external systems, URLs, API details |
|
||||
|
||||
## When to Capture
|
||||
|
||||
### Team and organization knowledge (`LEARNINGS.md`, shared scope)
|
||||
- Canonical destinations and workflows (for example, which Content database receives a type of Slack request)
|
||||
- Required intake fields, ownership, prioritization conventions, metric definitions, and approved terminology
|
||||
- Durable external references that the whole team needs, including the canonical page/database URL
|
||||
- Corrections or decisions that should affect every organization member's future Slack and app conversations
|
||||
|
||||
Store the fact and a concise provenance link when available. Do not paste full private conversations, customer data, credentials, or secrets into learnings. Put stable always-on policy in shared `AGENTS.md`; put learned facts and evolving conventions in shared `LEARNINGS.md`.
|
||||
|
||||
### User Preferences & Memory (`user`)
|
||||
- **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short"
|
||||
- **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone")
|
||||
- **Workflow preferences** — "always CC my assistant", "I like to review before sending"
|
||||
- **Role and expertise** — "I'm a data scientist", "new to React"
|
||||
|
||||
### Feedback & Corrections (`feedback`)
|
||||
- **Corrections** — user says "no, do it this way" → capture the right way
|
||||
- **Confirmed approaches** — user validates a non-obvious choice ("yes, that's perfect")
|
||||
- **Repeated friction** — you hit the same issue twice; save it
|
||||
|
||||
### Project Context (`project`)
|
||||
- **Ongoing work** — who is doing what, why, by when
|
||||
- **Decisions** — why something is done a certain way
|
||||
- **Status** — current state of initiatives
|
||||
|
||||
### References (`reference`)
|
||||
- **External systems** — "bugs are tracked in Linear project INGEST"
|
||||
- **URLs** — dashboards, documentation, tools
|
||||
- **API quirks** — undocumented behavior, version-specific gotchas
|
||||
|
||||
### Don't Capture
|
||||
- Things obvious from reading the code
|
||||
- Standard language/framework behavior
|
||||
- Temporary debugging notes
|
||||
- Anything already in AGENTS.md, shared LEARNINGS.md, or skills
|
||||
- Ephemeral task details (use tasks/plans instead)
|
||||
|
||||
## Key Rules
|
||||
|
||||
1. **Save proactively — don't ask permission.** When you learn something durable, save it immediately at the correct scope.
|
||||
2. **Choose scope by audience.** Organization workflow or reference → shared `LEARNINGS.md`; one person's preference/context → personal memory.
|
||||
3. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
|
||||
4. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
|
||||
5. **Keep descriptions concise** — the index is loaded every conversation
|
||||
6. **Memories are SQL-backed** — they persist across sessions and are not in git; still minimize sensitive content
|
||||
|
||||
## Graduation
|
||||
|
||||
When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill:
|
||||
- Saving a personal memory is lightweight (auto-apply, personal scope)
|
||||
- Shared LEARNINGS.md is the lightweight organization knowledge layer
|
||||
- Updating AGENTS.md or a skill is heavier (affects all users/agents)
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: create-skill
|
||||
description: >-
|
||||
How to create new skills for an agent-native app. Use when adding a new
|
||||
skill, documenting a pattern the agent should follow, or creating reusable
|
||||
guidance for the agent.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Create a Skill
|
||||
|
||||
## When to Use
|
||||
|
||||
Create a new skill when:
|
||||
|
||||
- There's a pattern the agent should follow repeatedly.
|
||||
- A multi-step workflow needs reliable, step-by-step guidance.
|
||||
- You want to scaffold files from a template.
|
||||
|
||||
Don't create a skill when:
|
||||
|
||||
- The guidance already exists in another skill — extend it instead.
|
||||
- You're documenting something the agent already knows (e.g., how to write
|
||||
TypeScript).
|
||||
- It's a one-off — put it in `AGENTS.md` (for everyone) or `memory/MEMORY.md`
|
||||
(personal, per-user). See **capture-learnings**.
|
||||
|
||||
## Interview
|
||||
|
||||
Before writing the skill, answer these:
|
||||
|
||||
1. **What should this skill enable?** — The core purpose in one sentence.
|
||||
2. **Which of the four areas does it serve?** — UI, actions, skills/instructions,
|
||||
or application state (see the **adding-a-feature** skill). Most skills are
|
||||
about how to touch one or more of these correctly.
|
||||
3. **When should it trigger?** — Describe the situations in natural language.
|
||||
Be slightly pushy — over-triggering is better than under-triggering.
|
||||
4. **Does it involve context awareness?** — Does the agent need to know what the
|
||||
user is looking at? If so, reference the `navigation` application-state key and
|
||||
the `view-screen` action pattern. See the **context-awareness** skill.
|
||||
5. **What type of skill?** — Pattern, Workflow, or Generator (see below).
|
||||
6. **Does it need supporting files?** — References (read-only context) or none.
|
||||
Keep it minimal; push depth into `references/`.
|
||||
|
||||
## Skill Types and Templates
|
||||
|
||||
### Pattern (architectural rule)
|
||||
|
||||
For documenting how things should be done:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-pattern
|
||||
description: >-
|
||||
[Under 40 words. What it covers AND when it should trigger.]
|
||||
---
|
||||
|
||||
# [Pattern Name]
|
||||
|
||||
## Rule
|
||||
|
||||
[One sentence: what must be true]
|
||||
|
||||
## Why
|
||||
|
||||
[Why this rule exists]
|
||||
|
||||
## How
|
||||
|
||||
[How to follow it, with code examples]
|
||||
|
||||
## Don't
|
||||
|
||||
[Common violations]
|
||||
|
||||
## Related Skills
|
||||
|
||||
[Which skills compose with this one]
|
||||
```
|
||||
|
||||
### Workflow (step-by-step)
|
||||
|
||||
For multi-step implementation tasks:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-workflow
|
||||
description: >-
|
||||
[Under 40 words. What it covers AND when it should trigger.]
|
||||
---
|
||||
|
||||
# [Workflow Name]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
[What must be in place first]
|
||||
|
||||
## Steps
|
||||
|
||||
[Numbered steps with code examples]
|
||||
|
||||
## Verification
|
||||
|
||||
[How to confirm it worked]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
[Common issues and fixes]
|
||||
|
||||
## Related Skills
|
||||
```
|
||||
|
||||
### Generator (scaffolding)
|
||||
|
||||
For creating files from templates:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-generator
|
||||
description: >-
|
||||
[Under 40 words. What it covers AND when it should trigger.]
|
||||
---
|
||||
|
||||
# [Generator Name]
|
||||
|
||||
## Usage
|
||||
|
||||
[How to invoke — what args/inputs are needed]
|
||||
|
||||
## What Gets Created
|
||||
|
||||
[List of files and their purpose]
|
||||
|
||||
## Template
|
||||
|
||||
[The template content with placeholders]
|
||||
|
||||
## After Generation
|
||||
|
||||
[What to do next — wire up sync, add routes, register the action, etc.]
|
||||
|
||||
## Related Skills
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
- Hyphen-case only: `[a-z0-9-]`, max 64 characters.
|
||||
- Pattern skills: descriptive names (`storing-data`, `delegate-to-agent`).
|
||||
- Workflow/generator skills: verb-noun (`create-skill`, `capture-learnings`).
|
||||
- The directory name must match the `name` in frontmatter.
|
||||
|
||||
## Skill Scope (runtime vs dev)
|
||||
|
||||
An optional `scope` frontmatter field controls which agent loads the skill:
|
||||
|
||||
- `both` (default when omitted) — loaded by connected repo agents and the
|
||||
in-app runtime agent. Use for any skill both audiences should follow.
|
||||
- `runtime` — loaded only by the in-app runtime agent.
|
||||
- `dev` — meant for the human's coding agent (e.g. Claude Code) only. **Excluded
|
||||
from the runtime agent everywhere**: not in the system-prompt skills block and
|
||||
not in `docs-search` results.
|
||||
|
||||
Use `scope: dev` for internal-only skills that should guide connected repo
|
||||
agents such as Codex or Claude Code, but should not affect the deployed
|
||||
production agent. Do not use `metadata.internal` for runtime visibility; that
|
||||
field is catalog/package metadata and is intentionally not treated as
|
||||
production exclusion.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: release-checklist
|
||||
description: >-
|
||||
Steps for cutting a release. Use when preparing or publishing a new version.
|
||||
scope: dev
|
||||
---
|
||||
```
|
||||
|
||||
Leave `scope` off for normal skills — the default (`both`) keeps them loading at
|
||||
runtime, so this is fully backward compatible. To make a dev-only skill visible
|
||||
to your coding agent but hidden from the runtime agent, mark it `scope: dev` and
|
||||
optionally mirror it under `.claude/skills/<name>/SKILL.md` (Claude Code reads
|
||||
`.claude/skills/` independently of the runtime's `.agents/skills/`).
|
||||
|
||||
## Tips
|
||||
|
||||
- **Keep descriptions under 40 words** — they load into context on every
|
||||
conversation. State what the skill does AND when to trigger it.
|
||||
- **Keep SKILL.md lean (under ~500 lines)** — move detailed content to
|
||||
`references/` files (progressive disclosure).
|
||||
- **Use standard markdown headings** — no XML tags or custom formats.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- **Inline LLM calls** — skills must not call LLMs directly. All AI work goes
|
||||
through the agent chat (see **delegate-to-agent**).
|
||||
- **Introducing databases** — data lives in SQL via Drizzle (see **storing-data**).
|
||||
- **Ignoring sync** — if a skill creates data, mention wiring `useDbSync` /
|
||||
`useActionQuery` so the UI updates (see **real-time-sync**).
|
||||
- **Vague descriptions** — "Helps with development" won't trigger. Be specific
|
||||
about _when_.
|
||||
- **Pure documentation** — skills should guide action, not just explain concepts.
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
.agents/skills/my-skill/
|
||||
├── SKILL.md # Main skill (required)
|
||||
└── references/ # Optional supporting context
|
||||
└── detailed-guide.md
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **adding-a-feature** — The four-area model every skill ultimately serves.
|
||||
- **writing-agent-instructions** — How to write AGENTS.md and skills well for
|
||||
apps and templates you ship to others.
|
||||
- **capture-learnings** — When a learning graduates to reusable guidance, create
|
||||
a skill; one-offs go to `AGENTS.md` or `memory/MEMORY.md`.
|
||||
- **self-modifying-code** — The agent can create new skills (Tier 2 modification).
|
||||
@@ -0,0 +1,220 @@
|
||||
---
|
||||
name: customizing-agent-native
|
||||
description: >-
|
||||
How to configure, compose, or eject Agent Native features into app-owned
|
||||
code. Use when overriding shared components or integrations, customizing a
|
||||
template, adding UI to chat or headless apps, or inspecting package source.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Customizing Agent Native
|
||||
|
||||
## Rule
|
||||
|
||||
Start with the app's registered design system and local UI adapters, then use
|
||||
the public feature's props, semantic components, controller, product slots,
|
||||
and callbacks. If those seams are not enough, use the eject CLI to transfer
|
||||
the smallest supported feature into the app and make that copy app-owned.
|
||||
Never edit `node_modules`, deep-import a private source file at runtime, or
|
||||
patch an `@agent-native/*` package.
|
||||
|
||||
Use this order:
|
||||
|
||||
1. Set brand tokens with the build-time theme configuration when tokens are
|
||||
enough.
|
||||
2. Register company components in `app/design-system.ts` with
|
||||
`defineDesignSystem`, then pass that definition to `ToolkitProvider`.
|
||||
3. Configure a public feature through its semantic components, headless
|
||||
controller, and product-level render slots.
|
||||
4. Compose app primitives behind the app's local UI adapter layer.
|
||||
5. Eject the smallest feature into app-owned source.
|
||||
6. Propose a new Toolkit seam when the same override is useful in two apps.
|
||||
|
||||
Ejection is for intentional product customization, not for hiding an upgrade
|
||||
failure or replacing Core runtime behavior.
|
||||
|
||||
## Use A Company Design System
|
||||
|
||||
Keep the explicit, typed registration seam in `app/design-system.ts`:
|
||||
|
||||
```tsx
|
||||
import { defineDesignSystem } from "@agent-native/toolkit/design-system";
|
||||
import {
|
||||
AcmeActionButtonAdapter,
|
||||
AcmeDialogAdapter,
|
||||
} from "./design-system/acme-adapter";
|
||||
|
||||
export const designSystem = defineDesignSystem({
|
||||
name: "Acme",
|
||||
components: {
|
||||
ActionButton: AcmeActionButtonAdapter,
|
||||
Dialog: AcmeDialogAdapter,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Adapters translate the semantic Toolkit contract into company component props.
|
||||
They are ordinary React components and may use MUI-style providers, React Aria,
|
||||
CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
|
||||
optional interoperability hooks, not Tailwind or CVA requirements.
|
||||
|
||||
The contract has nine leaf components (`ActionButton`, `IconButton`,
|
||||
`TextField`, `TextArea`, `Spinner`, `Skeleton`, `Status`, `Surface`, `Avatar`)
|
||||
and eight behavior components (`Tooltip`, `Menu`, `Popover`, `Dialog`,
|
||||
`Picker`, `Checkbox`, `Switch`, `Tabs`). `Picker` covers select and combobox
|
||||
behavior, not date picking. Behavior adapters own their portal, focus,
|
||||
keyboard, dismissal, and stacking implementation while honoring the semantic
|
||||
props and `portalContainer` interop contract.
|
||||
|
||||
App product code imports standard controls from its local adapter path, usually
|
||||
`@/components/ui/*`. Do not import `@agent-native/toolkit/ui/*` directly from
|
||||
pages, routes, or domain components. That bypasses the app seam and makes a
|
||||
future design-system replacement incomplete. Toolkit feature packages remain
|
||||
valid imports; configure their presentation through the registered semantic
|
||||
components, controller, and product slots.
|
||||
|
||||
Run the published conformance kit against a complete adapter in its own CI:
|
||||
|
||||
```tsx
|
||||
import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
|
||||
import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
|
||||
|
||||
await assertDesignSystemConformance({
|
||||
adapterName: "Acme",
|
||||
components,
|
||||
contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
|
||||
});
|
||||
```
|
||||
|
||||
New components and optional props are minor contract changes. Required props,
|
||||
removed APIs, or behavioral changes require a new contract major.
|
||||
|
||||
## Customize A Shared Feature
|
||||
|
||||
Prefer feature-level headless controllers over rebuilding individual widgets.
|
||||
One controller must power both the Toolkit default view and every custom render
|
||||
path so behavior, actions, analytics, accessibility state, and error handling
|
||||
cannot drift. Use a product-level render slot to replace the view while keeping
|
||||
that controller. Eject only when the controller and slots cannot express the
|
||||
required product behavior.
|
||||
|
||||
## Eject A Feature
|
||||
|
||||
Discover and inspect the ejection units published by installed first-party
|
||||
packages before changing source:
|
||||
|
||||
```bash
|
||||
agent-native eject --list
|
||||
agent-native eject inspect <unit>
|
||||
agent-native eject <unit> --app <app>
|
||||
agent-native eject <unit> --app <app> --apply
|
||||
```
|
||||
|
||||
The command is dry-run by default. It prints the file closure, consumer import
|
||||
rewrites, protected package contracts, and verification commands before
|
||||
writing. `--apply` copies the package-version-matched source into the app and
|
||||
rewrites only imports covered by the unit manifest.
|
||||
|
||||
Every first-party public ejection unit must have a complete manifest. If one is
|
||||
missing, treat that as a framework coverage bug instead of inventing a copy
|
||||
recipe. For an unknown third-party package, use the emitted add-style blueprint
|
||||
as a starting point. Protected runtime behavior is never copied; follow the
|
||||
reported configuration, adapter, or extension seam instead.
|
||||
|
||||
Applied ejections are recorded in the committed
|
||||
`agent-native.ejections.json`, including package version, manifest digest,
|
||||
target hashes, and import rewrites. Use the recorded state to review drift or
|
||||
undo an unchanged ejection:
|
||||
|
||||
```bash
|
||||
agent-native eject diff <unit> --app <app>
|
||||
agent-native eject restore <unit> --app <app>
|
||||
agent-native eject restore <unit> --app <app> --apply
|
||||
```
|
||||
|
||||
Restore is hash-gated. It refuses to remove locally edited files or reverse
|
||||
changed imports and prints their diff instead. Keep an edited ejection as
|
||||
app-owned code, or reconcile those edits before restoring it.
|
||||
|
||||
## Find The Installed Implementation
|
||||
|
||||
Use the source that matches the installed package version:
|
||||
|
||||
```bash
|
||||
pnpm action docs-search --query "<component or feature>"
|
||||
pnpm action source-search --query "<component or symbol>"
|
||||
rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
|
||||
rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
|
||||
```
|
||||
|
||||
- Toolkit publishes readable TypeScript under
|
||||
`node_modules/@agent-native/toolkit/src/` for selective UI adoption.
|
||||
- Core and first-party template source lives under
|
||||
`node_modules/@agent-native/core/corpus/core/` and
|
||||
`node_modules/@agent-native/core/corpus/templates/`.
|
||||
- Treat those trees as read-only references. Prefer `agent-native eject` so the
|
||||
package manifest selects the complete source closure and rewrites imports.
|
||||
Manual inspection is still useful for deciding whether to configure,
|
||||
compose, eject, or propose a shared seam.
|
||||
|
||||
Do not manually guess at sibling dependencies. The ejection manifest owns the
|
||||
required file closure and keeps protected contracts on public package imports.
|
||||
|
||||
## Preserve The Agent-Native Contract
|
||||
|
||||
UI ownership may change; product contracts should not:
|
||||
|
||||
- Keep app operations in `defineAction` actions and call them through
|
||||
`useActionQuery`, `useActionMutation`, or another named client helper.
|
||||
- Keep navigation, selection, and focused-object state visible through the
|
||||
existing application-state keys.
|
||||
- Keep AI work in the shared agent chat instead of adding direct LLM calls.
|
||||
- Keep auth, access checks, persistence, chat transport, and agent execution in
|
||||
Core. Do not copy those runtimes into the app.
|
||||
- Keep local adapters narrow so package upgrades still improve every surface
|
||||
the app has not intentionally taken ownership of.
|
||||
- Keep page, route, and domain code on local UI adapter imports. Never reach
|
||||
around the registered design system with direct Toolkit UI primitive imports.
|
||||
|
||||
## App Shapes
|
||||
|
||||
- **Template app:** begin with `app/design-system.ts`, its local UI adapters,
|
||||
and domain UI. Use Toolkit features for repeated workspace behavior; eject
|
||||
only the unit being customized.
|
||||
- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
|
||||
Core. Compose or eject Toolkit presentation such as chat-history UI around it.
|
||||
- **Headless app:** stay action-first while no UI is needed. When adding a UI,
|
||||
use the Chat template as the on-ramp or add Toolkit components without
|
||||
replacing the existing actions.
|
||||
- **Workspace:** put one-app overrides in that app. Promote a local component
|
||||
to `packages/shared` only when multiple workspace apps use it.
|
||||
|
||||
## After Ejecting
|
||||
|
||||
- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
|
||||
- Remove unused dependencies and imports from the ejected files.
|
||||
- Keep visible text in the app's localization catalogs.
|
||||
- Run the manifest verification commands plus the app's formatter, typecheck,
|
||||
and focused tests.
|
||||
- Re-check the installed source during future package upgrades; the app-owned
|
||||
ejection does not receive upstream fixes automatically. Use `eject diff` to
|
||||
distinguish recorded output from subsequent local edits.
|
||||
|
||||
## Don't
|
||||
|
||||
- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
|
||||
- Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
|
||||
- Don't copy Core auth, DB, action, agent-loop, or transport internals.
|
||||
- Don't manually copy a first-party unit with a missing recipe; fix its manifest.
|
||||
- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
|
||||
- Don't fork feature state into a custom view; consume the feature's controller.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `agent-native-docs` — version-matched docs and source lookup
|
||||
- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
|
||||
- `self-modifying-code` — safe app source edits
|
||||
- `upgrade-agent-native` — supported package upgrade path
|
||||
- `adding-a-feature` — UI/action/instructions/application-state parity
|
||||
@@ -0,0 +1,263 @@
|
||||
---
|
||||
name: delegate-to-agent
|
||||
description: >-
|
||||
How to delegate all AI work to the agent chat. Use when delegating AI work
|
||||
from UI or scripts to the agent, when a user asks for agent behavior or
|
||||
LLM-powered features, when tempted to add inline LLM calls, or when sending
|
||||
messages to the agent from application code.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Delegate All AI to the Agent
|
||||
|
||||
## Rule
|
||||
|
||||
The UI never calls an LLM directly. Product workflows are delegated to the
|
||||
agent through the chat bridge so users can see, steer, and audit the work.
|
||||
Server-side one-shot model calls are an explicit escape hatch for narrow text
|
||||
transforms only; use `completeText()` from `@agent-native/core/server` when the
|
||||
work intentionally does not need tools, chat history, or run state.
|
||||
|
||||
## Why
|
||||
|
||||
The agent is the single AI interface. It has context about the full project, can read/write any file, and can run scripts. Inline LLM calls bypass this — they create a shadow AI that doesn't know what the agent knows and can't coordinate with it.
|
||||
|
||||
## How
|
||||
|
||||
**From the UI (client):**
|
||||
|
||||
```ts
|
||||
import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
|
||||
|
||||
sendToAgentChat({
|
||||
message: "Generate a summary of this document",
|
||||
context: documentContent, // optional hidden context (not shown in chat UI)
|
||||
submit: true, // auto-submit to the agent
|
||||
});
|
||||
```
|
||||
|
||||
**From the UI, in the background:**
|
||||
|
||||
```ts
|
||||
import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
|
||||
|
||||
sendToAgentChat({
|
||||
message: "Analyze this import and create any missing records",
|
||||
context: `Import batch id: ${batchId}`,
|
||||
submit: true,
|
||||
newTab: true,
|
||||
background: true,
|
||||
openSidebar: false,
|
||||
});
|
||||
```
|
||||
|
||||
This is still a full agent run: tools, actions, thread state, and run tracking
|
||||
all remain active. It simply does not focus or open the sidebar.
|
||||
|
||||
**From scripts (Node):**
|
||||
|
||||
```ts
|
||||
import { agentChat } from "@agent-native/core";
|
||||
|
||||
agentChat.submit("Process the uploaded images and create thumbnails");
|
||||
```
|
||||
|
||||
**For narrow server-side text transforms:**
|
||||
|
||||
```ts
|
||||
import { completeText } from "@agent-native/core/server";
|
||||
|
||||
const result = await completeText({
|
||||
systemPrompt: "Return exactly one sentiment label.",
|
||||
input: messageBody,
|
||||
maxOutputTokens: 12,
|
||||
temperature: 0,
|
||||
});
|
||||
```
|
||||
|
||||
Wrap user-facing uses in actions so the UI and agent share the same operation.
|
||||
Do not call provider SDKs directly.
|
||||
|
||||
**From the UI, detecting when agent is done:**
|
||||
|
||||
```ts
|
||||
import { useAgentChatGenerating } from "@agent-native/core/client/agent-chat";
|
||||
|
||||
function MyComponent() {
|
||||
const isGenerating = useAgentChatGenerating();
|
||||
// Show loading state while agent is working
|
||||
}
|
||||
```
|
||||
|
||||
## `submit` vs Prefill
|
||||
|
||||
The `submit` option controls whether the message is sent automatically or placed in the chat input for user review:
|
||||
|
||||
| `submit` value | Behavior | Use when |
|
||||
| -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| `true` | Auto-submits to the agent immediately | Routine operations the user has already approved |
|
||||
| `false` | Prefills the chat input for user review | High-stakes operations (deleting data, modifying code, API calls with side effects) |
|
||||
| omitted | Uses the project's default setting | General-purpose delegation |
|
||||
|
||||
```ts
|
||||
// Auto-submit: routine operation
|
||||
sendToAgentChat({ message: "Update the project summary", submit: true });
|
||||
|
||||
// Prefill: let user review before sending
|
||||
sendToAgentChat({
|
||||
message: "Delete all projects older than 30 days",
|
||||
submit: false,
|
||||
});
|
||||
```
|
||||
|
||||
## Capture user input first when generating from a prompt
|
||||
|
||||
Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
|
||||
|
||||
**Bad** — auto-submits a placeholder message; the user never said what they wanted:
|
||||
|
||||
```tsx
|
||||
<Button
|
||||
onClick={() =>
|
||||
sendToAgentChat({ message: "make a design", submit: true })
|
||||
}
|
||||
>
|
||||
New Design
|
||||
</Button>
|
||||
```
|
||||
|
||||
**Good** — Popover anchored to the button captures the prompt, then submits it:
|
||||
|
||||
```tsx
|
||||
<Popover open={open} onOpenChange={setOpen}>
|
||||
<PopoverTrigger asChild>
|
||||
<Button>New Design</Button>
|
||||
</PopoverTrigger>
|
||||
<PopoverContent className="w-96">
|
||||
<Textarea
|
||||
autoFocus
|
||||
value={prompt}
|
||||
onChange={(e) => setPrompt(e.target.value)}
|
||||
placeholder="What do you want to design?"
|
||||
/>
|
||||
<Button
|
||||
onClick={() => {
|
||||
sendToAgentChat({ message: prompt, submit: true });
|
||||
setOpen(false);
|
||||
setPrompt("");
|
||||
}}
|
||||
>
|
||||
Create
|
||||
</Button>
|
||||
</PopoverContent>
|
||||
</Popover>
|
||||
```
|
||||
|
||||
**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
|
||||
|
||||
**Auto-submit without input is fine when intent is unambiguous:**
|
||||
|
||||
- "Try to fix" on a tool error — submits the error details with a clear fix instruction
|
||||
- "Retry the last operation" after a transient failure
|
||||
- Single-purpose buttons where there is nothing meaningful for the user to add
|
||||
|
||||
If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
|
||||
|
||||
## Delegating to a Sub-Agent (Agent Teams)
|
||||
|
||||
`sendToAgentChat()` delegates from app code _to_ the agent. The other axis of
|
||||
delegation is the agent handing work _to a sub-agent_ through the Agent Teams
|
||||
run-manager. The main chat stays the orchestrator: it spawns sub-agents, then
|
||||
reads and integrates their results.
|
||||
|
||||
### When to spawn a sub-agent vs do it yourself
|
||||
|
||||
- **Do it yourself** when the work is small, on the critical path, or tightly
|
||||
coupled to what you're already doing. Sub-agent overhead and coordination risk
|
||||
outweigh the benefit.
|
||||
- **Spawn a sub-agent** for a self-contained unit of work that can run
|
||||
independently — a disjoint investigation, an isolated implementation slice, a
|
||||
long-running search — especially when it frees the main thread to keep
|
||||
orchestrating.
|
||||
|
||||
### Briefing contract
|
||||
|
||||
Every sub-agent brief must specify four things, or the sub-agent will guess:
|
||||
|
||||
- **Objective** — the one concrete outcome it owns, in a sentence.
|
||||
- **Context** — the facts it needs (paths, prior findings, constraints) so it
|
||||
doesn't re-derive them.
|
||||
- **Output** — the exact shape you want back (a summary, a file edited, a list
|
||||
of paths, a yes/no with rationale).
|
||||
- **Boundaries** — what it must NOT touch (files, branches, side effects) and
|
||||
when to stop and report rather than push forward.
|
||||
|
||||
### Fan-out discipline
|
||||
|
||||
- **Default to a single sub-agent.** Most delegation is one focused task.
|
||||
- **Spawn multiple only for genuinely independent units** that don't share state
|
||||
or files. Never parallelize coupled work — if B needs A's output, run them in
|
||||
sequence.
|
||||
- **Cap parallel fan-out at ~3.** More sub-agents means more synthesis cost and
|
||||
more chance of conflicting edits to the same area.
|
||||
|
||||
### Synthesis discipline
|
||||
|
||||
- **Read every result** before concluding — don't act on the first one back.
|
||||
- **Reconcile conflicts** between sub-agent findings explicitly; decide which is
|
||||
right rather than averaging or ignoring.
|
||||
- **Integrate into one answer.** The main thread produces the single coherent
|
||||
result; it never just forwards raw sub-agent transcripts to the user.
|
||||
|
||||
Background sub-agents must use the core run-manager / Agent Teams infrastructure
|
||||
rather than ad-hoc LLM calls.
|
||||
|
||||
## Don't
|
||||
|
||||
- Don't `import Anthropic from "@anthropic-ai/sdk"` in client or server code
|
||||
- Don't `import OpenAI from "openai"` in client or server code
|
||||
- Don't make direct API calls to any LLM provider
|
||||
- Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
|
||||
- Don't build "AI features" that bypass the agent chat
|
||||
- Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
|
||||
- Don't use `completeText()` for workflows that need tools, database writes,
|
||||
auditability, user steering, or multi-step reasoning. Use the agent chat
|
||||
instead, optionally with `background: true`.
|
||||
|
||||
## Exception
|
||||
|
||||
Scripts may call external APIs (image generation, search, etc.) — but the AI
|
||||
reasoning and orchestration still goes through the agent. A script is a tool
|
||||
the agent uses, not a replacement for the agent.
|
||||
|
||||
`completeText()` is allowed for small server-side transforms such as
|
||||
classification, extraction, rewriting a short string, or normalizing messy
|
||||
provider text. It deliberately runs with `tools: []` and does not create chat
|
||||
thread state.
|
||||
|
||||
## When to Use A2A Instead
|
||||
|
||||
`sendToAgentChat()` delegates work to the **local** agent — the one running alongside your app. When the work should go to a **different** agent entirely (e.g., asking an analytics agent for data, or a calendar agent for availability), use the A2A (agent-to-agent) protocol instead.
|
||||
|
||||
```ts
|
||||
import { callAgent } from "@agent-native/core/a2a";
|
||||
|
||||
// Call a different agent — not the local agent chat
|
||||
const stats = await callAgent(
|
||||
"https://analytics.example.com",
|
||||
"What were last week's signups?",
|
||||
{ apiKey: process.env.ANALYTICS_A2A_KEY },
|
||||
);
|
||||
```
|
||||
|
||||
See the **a2a-protocol** skill for the full pattern.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **a2a-protocol** — When the work goes to a different agent, not the local one
|
||||
- **actions** — The agent invokes actions via `pnpm action <name>` to perform complex operations
|
||||
- **self-modifying-code** — The agent operates through the chat bridge to make code changes
|
||||
- **storing-data** — The agent writes results to the database after processing requests
|
||||
- **real-time-sync** — The UI updates automatically when the agent writes data
|
||||
@@ -0,0 +1,169 @@
|
||||
---
|
||||
name: feature-flags
|
||||
description: >-
|
||||
Declare, evaluate, manage, and remove framework feature flags. Use when
|
||||
shipping a capability gradually, targeting users or organizations, or
|
||||
replacing a compile-time rollout switch with a production-safe runtime flag.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Feature Flags
|
||||
|
||||
A feature flag is a boolean declared in app code, evaluated locally by Core,
|
||||
and managed from the Analytics fleet control plane. Code owns whether a flag
|
||||
exists. Runtime settings own only its rollout state.
|
||||
|
||||
Flags let an app deploy dormant code and turn it on in the real environment
|
||||
without another deployment. They are not experiments: do not add variants,
|
||||
hypotheses, conversion metrics, exposure tracking, or lifecycle states.
|
||||
|
||||
## When to use one
|
||||
|
||||
Use a flag for a reversible rollout of a user-facing capability whose dormant
|
||||
code is safe to deploy. Flags are useful for production dogfooding, exact-user
|
||||
or organization pilots, and deterministic percentage rollouts.
|
||||
|
||||
Do not use a flag for authentication, authorization, secrets, audit enablement,
|
||||
SSR cache behavior, or another security boundary. Client hiding is presentation
|
||||
only; every guarded server action must evaluate the same registered flag.
|
||||
|
||||
## Agent workflow
|
||||
|
||||
### 1. Declare
|
||||
|
||||
Keep definitions in a shared TypeScript module so server and client code use the
|
||||
same stable key. Flags are boolean and default-off.
|
||||
|
||||
```ts
|
||||
import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
|
||||
|
||||
export const FULL_APP_BUILDING = defineFeatureFlag({
|
||||
key: "full-app-building",
|
||||
displayName: "Full app building",
|
||||
description: "Create and edit Fusion-backed applications.",
|
||||
});
|
||||
```
|
||||
|
||||
Keys are immutable, never reused, and contain only letters, numbers, dots,
|
||||
underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
|
||||
definitions or rollout rows from Analytics.
|
||||
|
||||
### 2. Register
|
||||
|
||||
Register app definitions from a Nitro plugin before actions are discovered.
|
||||
Do not add app-specific flags to a Core registry.
|
||||
|
||||
```ts
|
||||
import { createFeatureFlagsPlugin } from "@agent-native/core/server";
|
||||
|
||||
import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
|
||||
|
||||
export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
|
||||
```
|
||||
|
||||
### 3. Guard server and client
|
||||
|
||||
The server action is the enforcement boundary:
|
||||
|
||||
```ts
|
||||
import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
|
||||
|
||||
run: async (args, ctx) => {
|
||||
if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
|
||||
throw new Error("Full app building is not enabled for this account.");
|
||||
}
|
||||
// guarded operation
|
||||
}
|
||||
```
|
||||
|
||||
Use the client hook only to hide or reveal hydrated UI:
|
||||
|
||||
```tsx
|
||||
import { useFeatureFlag } from "@agent-native/core/client/feature-flags";
|
||||
|
||||
const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
|
||||
return enabled ? <FullAppOption /> : null;
|
||||
```
|
||||
|
||||
The client hook intentionally returns false while loading or for an unknown
|
||||
flag. Never replace that fail-closed behavior with app-local bucketing or a
|
||||
compile-time fallback. Never evaluate personalized flags in the public SSR
|
||||
shell; it is shared and cached for every visitor.
|
||||
|
||||
### 4. Verify and roll out
|
||||
|
||||
1. Verify the off path before changing rollout state.
|
||||
2. Confirm the registered flag appears in **Analytics → Feature flags** for the
|
||||
app and is Off by default.
|
||||
3. Use **Enable for me** for initial production dogfood.
|
||||
4. Expand to exact emails, organization IDs, or a percentage only from
|
||||
Analytics.
|
||||
5. Confirm the client presentation and authoritative server action agree.
|
||||
|
||||
## Management contract
|
||||
|
||||
Core mounts three actions in registered apps:
|
||||
|
||||
| Action | Purpose |
|
||||
| --- | --- |
|
||||
| `get-feature-flags` | Return the current caller's evaluated boolean values. |
|
||||
| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
|
||||
| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
|
||||
|
||||
Analytics calls the app-local operator actions through narrowly scoped A2A
|
||||
delegation. Tokens require an exact audience, organization, scope, operator
|
||||
role, and audit correlation id. Management is permission-checked and audited
|
||||
by the target app. Never manage flags through generic settings routes, raw SQL,
|
||||
or per-app toggle UIs.
|
||||
|
||||
## Rollout semantics
|
||||
|
||||
The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
|
||||
as `off`, `rules`, and `on`.
|
||||
|
||||
Targeted rules combine exact normalized emails, exact organization IDs, and a
|
||||
percentage with OR semantics. Exact matches are checked first. Percentage
|
||||
buckets use Core's stable hash of the flag key and authenticated user identity;
|
||||
anonymous callers fail closed. Raising a percentage preserves the users already
|
||||
included at a lower percentage. Do not implement bucketing in app code.
|
||||
|
||||
Unknown definitions, missing state, malformed state, storage errors, and
|
||||
evaluation errors all return the code default (`false` in v1). Explicit Off
|
||||
wins over every target; Everyone enables every authenticated caller.
|
||||
|
||||
## Remove a flag
|
||||
|
||||
After a rollout is permanent:
|
||||
|
||||
1. Replace guarded branches with the chosen behavior.
|
||||
2. Delete the server and client gates.
|
||||
3. Delete the definition and registration entry.
|
||||
4. Verify the flag disappears from the Analytics fleet.
|
||||
5. Remove stale tests and rollout instructions.
|
||||
|
||||
A permanent flag is just an if statement with a pension plan.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- Unknown and unregistered keys evaluate false.
|
||||
- UI hiding and server enforcement use the same registered key.
|
||||
- Exact-user, organization, deterministic percentage, Everyone, and Off paths
|
||||
have focused tests.
|
||||
- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
|
||||
- Unauthorized callers cannot list targeting details or mutate flags.
|
||||
- Mutations are atomic, read back stored state, emit refresh, and appear in the
|
||||
audit log with the flag key.
|
||||
- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
|
||||
and unreachable directory apps honestly.
|
||||
- Future agents can find this skill from root `AGENTS.md`, and
|
||||
`pnpm guard:workspace-skills` passes after syncing generated copies.
|
||||
|
||||
## Related skills
|
||||
|
||||
- **adding-a-feature** — preserve UI/action/instruction/application-state parity
|
||||
- **actions** — define and call guarded app operations
|
||||
- **audit-log** — inspect automatic action mutation history
|
||||
- **reliable-mutations** — make rollout changes atomic and provable
|
||||
- **security** — keep security controls out of feature flags
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
name: frontend-design
|
||||
description: >-
|
||||
Create distinctive, production-grade frontend interfaces with high design
|
||||
quality. Use when building web components, pages, artifacts, posters, or
|
||||
applications (websites, landing pages, dashboards, React components,
|
||||
HTML/CSS layouts, or when styling/beautifying any web UI). Generates
|
||||
creative, polished UI that avoids generic AI aesthetics.
|
||||
scope: dev
|
||||
license: Complete terms in LICENSE.txt
|
||||
source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Frontend Design
|
||||
|
||||
This skill guides creation of distinctive, production-grade frontend interfaces. Implement real working code with strong product judgment, excellent accessibility, and a clear visual point of view.
|
||||
|
||||
The user may ask for a component, page, full app, dashboard, marketing surface, or restyle. Before coding, understand the audience and pick a direction that fits the product instead of defaulting to generic SaaS polish.
|
||||
|
||||
## Design Thinking
|
||||
|
||||
Before coding, decide:
|
||||
|
||||
- **Purpose**: What workflow does this surface make easier? What is the primary action?
|
||||
- **Audience**: Who will use it repeatedly, and what should feel fast, calm, playful, premium, editorial, technical, or utilitarian?
|
||||
- **Tone**: Choose a concrete aesthetic direction: refined minimal, dense operations console, editorial, playful, industrial, warm handmade, high-contrast data tool, etc.
|
||||
- **Information hierarchy**: What must be visible in the first five seconds, and what should be progressively disclosed?
|
||||
- **Differentiation**: What makes this feel designed for this exact domain?
|
||||
|
||||
Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
|
||||
|
||||
## Minimalism And Progressive Disclosure
|
||||
|
||||
Default to Apple/Linear-level restraint: make the primary workflow obvious, then remove everything that does not help that workflow right now. A polished UI often has fewer visible controls, fewer borders, fewer labels, and fewer explanatory surfaces than the first reasonable implementation.
|
||||
|
||||
### Progressive Disclosure Is A Design Requirement
|
||||
|
||||
Treat an all-at-once interface as a defect to fix during design, not as a
|
||||
styling preference. Before coding, inventory every piece of content and action
|
||||
on the surface, then assign each one to the smallest useful visibility level:
|
||||
|
||||
1. **Immediate** — the page title, current state, one primary action, and the
|
||||
compact context needed to choose what to do next.
|
||||
2. **Expanded** — the details needed for the selected item or active workflow.
|
||||
3. **On demand** — advanced settings, diagnostics, credentials, metadata,
|
||||
destructive actions, documentation, and rarely used tools.
|
||||
|
||||
Use single-select accordions or simple disclosure rows for sibling panels when
|
||||
the user is choosing one item at a time. Inside an expanded panel, keep another
|
||||
layer for independent concerns instead of dumping every form, explanation, and
|
||||
secondary action into the first reveal. Prefer one flat panel with alignment,
|
||||
dividers, and whitespace over nested cards; provider or product icons should
|
||||
not receive decorative borders or containers unless the container communicates
|
||||
state or interaction. A collapsed row should still show the item name, status,
|
||||
and a concise summary so the user can scan the whole surface without opening
|
||||
everything.
|
||||
|
||||
Before shipping, ask: “What can disappear until the user asks for it?” Then
|
||||
verify collapsed, expanded, loading, empty, error, and narrow-width states.
|
||||
If the first viewport contains multiple forms, repeated explanatory copy,
|
||||
documentation links, and controls for unrelated tasks, the surface has not
|
||||
passed this requirement yet.
|
||||
|
||||
- **Start by subtracting**: Before adding a visible control, banner, toolbar row, card, or explanatory block, ask what can be removed, merged, renamed, or moved into an existing affordance.
|
||||
- **One primary action**: Each surface should have one dominant next action. Secondary actions belong in menus, popovers, command palettes, disclosure rows, or contextual hover/focus states unless they are used constantly.
|
||||
- **Progressively disclose rare work**: Advanced options, diagnostics, metadata, settings, import/export, destructive actions, and inspection tools should stay tucked away until requested. Prefer small icon triggers with tooltips, popovers, drawers, or detail panels over permanent chrome.
|
||||
- **Keep chrome quiet**: Avoid new always-visible bars, badges, callouts, helper text, and counters unless they prevent mistakes or are central to repeated use. Status can often be a dot, ring, muted count, or tooltip.
|
||||
- **Favor content over containers**: Do not wrap every section in a card. Use whitespace, alignment, typography, dividers, and full-width bands before adding boxes.
|
||||
- **Design for repeated use**: Production app UI should feel calm after the hundredth use. If a control shouts, animates, explains itself, or occupies a full row for an occasional action, hide or compress it.
|
||||
- **Make absence intentional**: Empty states should be sparse and action-oriented. Do not fill blank space with marketing copy, decorative art, or lists of features just because the screen feels empty.
|
||||
- **Use familiar primitives**: Icon buttons need clear tooltips. Menus, popovers, tabs, switches, and segmented controls should carry complexity instead of exposing every option at once.
|
||||
|
||||
## Aesthetic Guidelines
|
||||
|
||||
- **Typography**: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
|
||||
- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
|
||||
- **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
|
||||
- **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
|
||||
- **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
|
||||
- **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
|
||||
|
||||
**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
|
||||
|
||||
## Agent-Native UI Rules
|
||||
|
||||
- Agent-native apps use React and Vite. The default adapter uses Tailwind CSS,
|
||||
shadcn/ui, and `@tabler/icons-react`, but an app may register a different
|
||||
company design system in `app/design-system.ts`.
|
||||
- **Use the app's design-system seam for standard UI.** Inspect
|
||||
`app/design-system.ts`, `ToolkitProvider`, and the local UI adapter directory
|
||||
before choosing a primitive. Use shadcn primitives when they are the active
|
||||
adapter; use the registered company components when they are not.
|
||||
- **When touching shadcn/ui components, also read `shadcn-ui` if it exists.** That skill covers `components.json`, CLI docs, component composition, theming, and registry workflows.
|
||||
- Check `app/components/ui/` before importing a shadcn component. If a primitive is missing, add it from the app root with `pnpm dlx shadcn@latest add <component>`, then review the generated file.
|
||||
- Pages, routes, and domain components must import controls through the app's
|
||||
local adapter path, usually `@/components/ui/*`. Never import
|
||||
`@agent-native/toolkit/ui/*` directly in app product code.
|
||||
- Toolkit/Core feature presentation flows through the semantic components from
|
||||
`@agent-native/toolkit/design-system`. Their props express intent, emphasis,
|
||||
size, controlled values, and behavior; they do not require Tailwind, CVA, or
|
||||
`className`.
|
||||
- For deeper feature customization, consume the feature-level headless
|
||||
controller through its product render slot. The same controller must power
|
||||
the default and custom views. Eject the smallest supported unit only after
|
||||
tokens, semantic components, controllers, and slots are insufficient.
|
||||
- Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
|
||||
- Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
|
||||
- Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
|
||||
- Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
|
||||
- Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
|
||||
- Custom styles belong in Tailwind classes, component CSS, or the existing global CSS theme file; avoid inline styles.
|
||||
|
||||
## shadcn/ui Design Rules
|
||||
|
||||
- Use built-in component variants first (`variant`, `size`) before overriding classes.
|
||||
- Use semantic tokens (`bg-background`, `text-muted-foreground`, `border-border`, `bg-primary`) instead of raw Tailwind colors for app chrome and reusable components.
|
||||
- Use `gap-*` in flex/grid layouts instead of `space-x-*` or `space-y-*`.
|
||||
- Use `size-*` when width and height are equal, and `truncate` instead of spelling out overflow/ellipsis/nowrap.
|
||||
- Use `cn()` from the local utils alias for conditional classes.
|
||||
- Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use `sr-only` only when the visible design already communicates the title.
|
||||
- Put menu/list items inside their group primitives: `SelectGroup`, `DropdownMenuGroup`, `CommandGroup`, and equivalents.
|
||||
- Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
|
||||
- Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
|
||||
- For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
|
||||
- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
Avoid:
|
||||
|
||||
- Generic AI aesthetics: purple gradients, glassy cards everywhere, vague sparkle language, decorative blobs, and context-free hero sections.
|
||||
- Custom reimplementations of shadcn primitives.
|
||||
- Raw color overrides on shared components when semantic tokens or variants would work.
|
||||
- New always-visible controls for rare actions. Prefer menus, popovers, sheets, tabs, collapsibles, or advanced sections.
|
||||
- Full-width banners, persistent helper rows, decorative cards, or explanatory chrome for status that could be a compact affordance.
|
||||
- Treating progressive disclosure as optional. If a control is not part of the main daily workflow, hide it until context, hover, focus, or explicit user intent makes it relevant.
|
||||
- UI cards nested inside other cards.
|
||||
- Text or icons that resize or shift fixed-format UI on hover/loading.
|
||||
|
||||
## Verification
|
||||
|
||||
For substantial frontend work:
|
||||
|
||||
1. Run the relevant formatter/checks.
|
||||
2. Start the dev server when the app needs one.
|
||||
3. Verify with browser screenshots at desktop and mobile widths.
|
||||
4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
|
||||
5. When registering or changing a company adapter, run
|
||||
`@agent-native/toolkit/conformance`, including mixed-overlay focus,
|
||||
`portalContainer`, and z-index stacking checks.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **shadcn-ui** — shadcn CLI, component docs, composition rules, theming, and registries
|
||||
- **customizing-agent-native** — Design-system registration, feature controllers, product slots, conformance, and ejection
|
||||
- **self-modifying-code** — The agent can edit source code to apply design changes
|
||||
- **storing-data** — All data lives in SQL; use actions for data access
|
||||
- **actions** — `useActionQuery`/`useActionMutation` hooks for frontend data fetching
|
||||
@@ -0,0 +1,232 @@
|
||||
---
|
||||
name: real-time-sync
|
||||
description: >-
|
||||
How to keep the UI in sync with agent changes via SSE plus polling fallback.
|
||||
Use when wiring query invalidation for new data models, debugging UI not
|
||||
updating, or understanding jitter prevention.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Real-Time Sync
|
||||
|
||||
## Rule
|
||||
|
||||
The UI stays in sync with agent/script changes through `useDbSync()`. In-process writes stream over `/_agent-native/events` first; `/_agent-native/poll` remains the cross-process/serverless fallback. When the agent writes to the database, the UI detects the change and updates automatically — no manual refresh needed.
|
||||
|
||||
## Why
|
||||
|
||||
The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same-process writes immediately; polling bridges anything SSE cannot see, such as another serverless invocation, cron job, or external script. Every visible write increments a version counter, `useDbSync()` receives the change, and React Query invalidates the relevant caches. This is what makes database writes feel real-time without relying on aggressive polling.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Server** increments a version counter on every database write. In-process events stream through the authenticated `/_agent-native/events` endpoint.
|
||||
|
||||
2. **Client** listens for sync events and updates per-source change counters:
|
||||
|
||||
```ts
|
||||
import { useDbSync } from "@agent-native/core/client/hooks";
|
||||
useDbSync({ queryClient });
|
||||
```
|
||||
|
||||
For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
|
||||
|
||||
3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
|
||||
|
||||
```ts
|
||||
import { useChangeVersion } from "@agent-native/core/client/hooks";
|
||||
import { useQuery } from "@tanstack/react-query";
|
||||
|
||||
const v = useChangeVersion("dashboards");
|
||||
const dashboard = useQuery({
|
||||
queryKey: ["dashboard", id, v],
|
||||
queryFn: () => fetchDashboard(id),
|
||||
placeholderData: (prev) => prev, // no flicker on refetch
|
||||
});
|
||||
```
|
||||
|
||||
When the agent writes (`update-dashboard` action → server emits `source: "dashboards"`), the counter advances, the queryKey changes, and React Query refetches that one query. The old data stays on screen during the refetch thanks to `placeholderData`.
|
||||
|
||||
For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
|
||||
|
||||
4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
|
||||
|
||||
5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
|
||||
|
||||
## Don't
|
||||
|
||||
- Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
|
||||
- Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
|
||||
- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
|
||||
|
||||
```ts
|
||||
import { subscribeSyncEvents } from "@agent-native/core/client/hooks";
|
||||
|
||||
const unsubscribe = subscribeSyncEvents({
|
||||
onEvents: (events) => {
|
||||
// filter by event.source and handle push-style updates
|
||||
},
|
||||
// Optional: relax your own fallback cadence while push is healthy.
|
||||
onSseStateChange: (connected) => {},
|
||||
});
|
||||
```
|
||||
|
||||
`useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events. Hidden tabs keep that shared transport alive by default: SSE stays connected and active fallback polling relaxes to a 10-second floor (idle polling remains once per minute). Pass `pauseWhenHidden: true` only for a consumer that explicitly must stop all hidden-tab sync.
|
||||
|
||||
## Which sources to depend on
|
||||
|
||||
Common sources you'll fold into query keys:
|
||||
|
||||
| Source | Bumped by |
|
||||
| ----------------- | --------------------------------------------------------------------------- |
|
||||
| `action` | The agent runner after every successful mutating action tool call |
|
||||
| `app-state` | Writes to `application_state` (navigation, selections, ephemeral UI state) |
|
||||
| `settings` | Writes to the `settings` table |
|
||||
| `dashboards` | Dashboard CRUD via `upsertDashboard` / `archiveDashboard` etc. |
|
||||
| `analyses` | Analysis CRUD |
|
||||
| `extensions` | Extension CRUD |
|
||||
| `collab` | Yjs collaborative-doc updates |
|
||||
| `screen-refresh` | Explicit `refresh-screen` agent tool call |
|
||||
|
||||
If a query reads data the agent can mutate via more than one path, depend on multiple sources with `useChangeVersions`:
|
||||
|
||||
```ts
|
||||
const v = useChangeVersions(["dashboards", "action"]);
|
||||
useQuery({ queryKey: ["dashboard", id, v], ... });
|
||||
```
|
||||
|
||||
`useChangeVersions` returns a single integer that advances whenever any of the listed sources advance.
|
||||
|
||||
## Tuning refetch behavior
|
||||
|
||||
To prevent cache thrashing during rapid agent writes, set `staleTime` on your queries:
|
||||
|
||||
```ts
|
||||
useQuery({
|
||||
queryKey: ["items"],
|
||||
queryFn: fetchItems,
|
||||
staleTime: 2000, // don't refetch within 2 seconds
|
||||
});
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Check |
|
||||
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
||||
| UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer? |
|
||||
| Poll endpoint not responding | Is `/_agent-native/poll` accessible? Is the server running? |
|
||||
| SSE not connecting | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback. |
|
||||
| High CPU / event storms | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation. |
|
||||
|
||||
## Jitter Prevention
|
||||
|
||||
When the agent writes to application-state via script helpers (`writeAppState`, `deleteAppState`), the write is automatically tagged with `requestSource: "agent"`. This prevents the UI from overwriting active user edits when it receives the change event.
|
||||
|
||||
### How it works
|
||||
|
||||
1. **Agent writes** are tagged: the script helpers in `@agent-native/core/application-state` pass `{ requestSource: "agent" }` to the store.
|
||||
2. **UI writes** are tagged: templates send a per-tab ID via the `X-Request-Source` header on PUT/DELETE requests to application-state endpoints.
|
||||
3. **Sync filters**: `useDbSync()` accepts an `ignoreSource` option. The UI passes its own tab ID so it ignores events from its own writes — but still picks up events from agents, other tabs, and scripts.
|
||||
|
||||
### Template setup
|
||||
|
||||
```ts
|
||||
// app/lib/tab-id.ts
|
||||
export const TAB_ID = `tab-${Math.random().toString(36).slice(2, 8)}`;
|
||||
|
||||
// app/root.tsx
|
||||
import { TAB_ID } from "@/lib/tab-id";
|
||||
|
||||
useDbSync({
|
||||
queryClient,
|
||||
ignoreSource: TAB_ID,
|
||||
});
|
||||
```
|
||||
|
||||
The `use-navigation-state.ts` hook sends the same `TAB_ID` in the `X-Request-Source` header when writing navigation state, so the tab that wrote the state does not refetch it.
|
||||
|
||||
### Why this matters
|
||||
|
||||
Without jitter prevention, a cycle occurs: the UI writes state, sync detects the change, the UI refetches and re-renders, potentially overwriting what the user is actively editing. With `ignoreSource`, the UI only reacts to changes from other sources (agent scripts, other browser tabs, other users).
|
||||
|
||||
## Action Routes and Live Sync
|
||||
|
||||
Actions work with the same sync system. When a mutating action writes to the database, the version counter increments and `useDbSync` picks up the change. Frontend mutations via `useActionMutation` automatically invalidate `["action"]` query keys on success, triggering refetches of `useActionQuery` hooks. Client components should call actions through those hooks, not with raw action-route fetches.
|
||||
|
||||
For custom apps, the best out-of-the-box path is:
|
||||
|
||||
1. Put read actions in `actions/` with `defineAction({ http: { method: "GET" } })`.
|
||||
2. Put write actions in `actions/` with the default POST/PUT/DELETE behavior.
|
||||
3. Call reads from React with `useActionQuery` and writes with `useActionMutation`.
|
||||
|
||||
This avoids duplicate `/api/*` JSON CRUD routes and makes agent-created records show up automatically. Raw `useQuery` can still work, but it should include `useChangeVersions(["action", "<domain-source>"])` in the query key for targeted refreshes.
|
||||
|
||||
### Auto-emit on mutating actions
|
||||
|
||||
The framework emits a change event with `source: "action"` whenever any non-read-only action runs to completion — whether called via HTTP (`/_agent-native/actions/:name`) or as an agent tool call. Read-only actions (`http: { method: "GET" }` or explicit `readOnly: true`) are skipped.
|
||||
|
||||
This means UIs don't need the agent to remember to call `refresh-screen` after every mutation. A listener like this (used in the `macros` template) will refresh after any mutating agent call:
|
||||
|
||||
```ts
|
||||
useDbSync({
|
||||
queryClient,
|
||||
ignoreSource: TAB_ID,
|
||||
onEvent: (data) => {
|
||||
if (data.requestSource === TAB_ID) return;
|
||||
// Invalidate all useActionQuery caches so list-*, get-*, etc. refetch
|
||||
queryClient.invalidateQueries({ queryKey: ["action"] });
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
`refresh-screen` remains available for unusual cases — e.g. the agent mutated data via a path the framework can't see (external system the app mirrors), or the agent wants to pass a `scope` hint for narrower invalidation.
|
||||
|
||||
## Keeping Stateful Components In Sync
|
||||
|
||||
The `useChangeVersion` / `useActionQuery` pattern above keeps the **query layer** fresh. But components that copy a server value into local React state still go stale on agent edits — refetching the query updates the prop, yet the local copy never re-adopts it. This is a recurring bug.
|
||||
|
||||
**Never do this** for a value the agent can mutate:
|
||||
|
||||
```ts
|
||||
// BUG: `title` is captured once and never re-reads the prop.
|
||||
const [title, setTitle] = useState(props.title);
|
||||
```
|
||||
|
||||
When the agent renames the record, the query refetches, `props.title` updates, but the input still shows the stale value until the component remounts.
|
||||
|
||||
**Derived-state surfaces (form fields, inline editors, popovers): use `useReconciledState`.** It re-adopts the authoritative external value when it changes, except while the user is actively editing that field — so agent mutations show up live without clobbering in-progress typing:
|
||||
|
||||
```ts
|
||||
import { useReconciledState } from "@agent-native/core/client/hooks";
|
||||
|
||||
// `active` = true while the user is editing this field (focused / dirty).
|
||||
const [title, setTitle] = useReconciledState(props.title, { active: isEditing });
|
||||
```
|
||||
|
||||
**Collaborative rich-text editors are different** — they don't copy a value into `useState`. They reconcile authoritative SQL content into a shared Y.Doc under an `updatedAt` gate with lead-client election. See `real-time-collab` → "Agent edits as a real-time peer editor". Don't reach for `useReconciledState` for a Yjs-backed editor.
|
||||
|
||||
| Surface | Keep it fresh with |
|
||||
| ------- | ------------------ |
|
||||
| React Query reads | `useChangeVersion` / `useActionQuery` (above) |
|
||||
| Local edit state copied from a server value (inputs, popovers, inline editors) | `useReconciledState(externalValue, { active })` |
|
||||
| Collaborative rich-text editor (Yjs) | `updatedAt`-gated reconcile + `isReconcileLeadClient` — see `real-time-collab` |
|
||||
|
||||
## Granular server-side merge for non-body fields
|
||||
|
||||
For structured documents (slide decks, form builders, design files) where the
|
||||
Yjs body collab would cause LWW conflicts at the container level, pair the
|
||||
change-sync `updatedAt` bump with a **granular server-side merge action** that
|
||||
accepts targeted per-item operations (add/patch/delete/reorder). Concurrent
|
||||
edits to different items both survive at the action level; the `collab` source
|
||||
version bump then propagates the merged state to all open clients. See
|
||||
`real-time-collab` for the pattern and examples.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **storing-data** — Application-state and settings are data stores that sync through change events
|
||||
- **context-awareness** — Navigation state writes use jitter prevention to avoid overwriting active edits
|
||||
- **actions** — Mutating actions trigger change events
|
||||
- **client-methods** — Route details belong in helpers/hooks, not components
|
||||
- **self-modifying-code** — Agent code edits trigger change events; rapid edits can cause event storms
|
||||
- **real-time-collab** — Collaborative editors reconcile agent edits into a shared Y.Doc, driven by the same change-sync `updatedAt` bump; also the granular server-side merge pattern for structured data
|
||||
@@ -0,0 +1,280 @@
|
||||
---
|
||||
name: security
|
||||
description: >-
|
||||
Secure coding practices for agent-native apps: input validation, SQL
|
||||
injection, XSS, secrets, data scoping, and auth. Use when writing any action,
|
||||
route, or component that touches user data or external input.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Security
|
||||
|
||||
## Rule
|
||||
|
||||
Use the framework's security primitives everywhere. Never bypass them.
|
||||
|
||||
## Absolute Secrets Rule
|
||||
|
||||
Never hardcode secret values or real private data. This applies to source code,
|
||||
docs, tests, fixtures, generated prompts, screenshots, seed data, and extension
|
||||
HTML just as much as production code.
|
||||
|
||||
Do not paste or invent real-looking API keys, bearer tokens, OAuth refresh
|
||||
tokens, webhook URLs, signing secrets, private Builder/internal data, or customer
|
||||
data into the repo. Examples must use obvious placeholders such as
|
||||
`<OPENAI_API_KEY>`, `${keys.SLACK_WEBHOOK}`, `sk-test-example`, or
|
||||
`example.customer@example.com`. Test literals should be clearly fake and must
|
||||
not match real provider token formats when an `example` token will do.
|
||||
|
||||
Credential values enter the system only through approved runtime channels:
|
||||
deployment env vars for deploy-level secrets, the encrypted `app_secrets` vault
|
||||
or `saveCredential` / `resolveCredential` for user/org/workspace API keys, and
|
||||
`oauth_tokens` for OAuth. Code and instructions may name the credential key
|
||||
(`OPENAI_API_KEY`), but must never contain the credential value.
|
||||
|
||||
## Input Validation
|
||||
|
||||
Use `defineAction` with a Zod `schema:` for every action. The framework validates input automatically and returns clear 400 errors for HTTP callers and structured error results for agent tool calls.
|
||||
|
||||
```ts
|
||||
export default defineAction({
|
||||
schema: z.object({
|
||||
email: z.string().email(),
|
||||
role: z.enum(["admin", "member"]),
|
||||
limit: z.coerce.number().int().min(1).max(100).default(25),
|
||||
}),
|
||||
run: async (args) => { /* args is fully typed and validated */ },
|
||||
});
|
||||
```
|
||||
|
||||
The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
|
||||
|
||||
## Large Payloads
|
||||
|
||||
Do not accept or persist unbounded base64/file blobs through actions, SQL writes,
|
||||
or `application_state`. Route uploads through the file-upload provider and store
|
||||
references. This prevents database bloat, slow hot paths, and accidental secret
|
||||
or customer-data embedding inside binary payloads.
|
||||
|
||||
## SQL Injection
|
||||
|
||||
Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:
|
||||
|
||||
```ts
|
||||
// Safe — Drizzle ORM
|
||||
await db.select().from(users).where(eq(users.email, args.email));
|
||||
|
||||
// Safe — parameterized raw SQL
|
||||
await client.execute({ sql: "SELECT * FROM users WHERE id = ?", args: [id] });
|
||||
|
||||
// NEVER do this
|
||||
await client.execute(`SELECT * FROM users WHERE id = '${id}'`);
|
||||
```
|
||||
|
||||
## XSS
|
||||
|
||||
- React auto-escapes JSX content — trust it.
|
||||
- Never use `dangerouslySetInnerHTML`, `innerHTML`, `eval()`, or `document.write()` with user-controlled content.
|
||||
- For rich text editing, use TipTap (framework dependency).
|
||||
- For rendering markdown, use `react-markdown`.
|
||||
|
||||
## SSRF
|
||||
|
||||
Any server-side `fetch` of a user- or agent-controlled URL must go through the framework SSRF guard — a bare `fetch()` can be steered at cloud metadata (`169.254.169.254`), `localhost`, or internal services.
|
||||
|
||||
```ts
|
||||
import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
|
||||
// Blocks private/internal targets, re-checks the resolved IP at connect time
|
||||
// (DNS rebinding), and re-validates every redirect hop.
|
||||
const res = await ssrfSafeFetch(userProvidedUrl, {}, { maxRedirects: 3 });
|
||||
```
|
||||
|
||||
For a pre-flight-only check (e.g. before a streaming or one-shot fetch), use `isBlockedExtensionUrlWithDns(url)` plus `createSsrfSafeDispatcher()` from the same module, and set `redirect: "manual"`. Never let the default `fetch` follow redirects for an untrusted URL — a public URL can 30x into the private network.
|
||||
|
||||
## Secrets
|
||||
|
||||
- OAuth tokens go in the `oauth_tokens` store via `saveOAuthTokens()`.
|
||||
- Per-user / per-org API keys go through `saveCredential` / `resolveCredential` (`@agent-native/core/credentials`) or the `app_secrets` vault. Both encrypt values at rest with AES-256-GCM (keyed by `SECRETS_ENCRYPTION_KEY`, falling back to `BETTER_AUTH_SECRET`; production refuses to start without one).
|
||||
- Never hand-roll secrets into `settings`, `application_state`, source code, or action responses sent to the client. The credential / vault APIs above are the only sanctioned stores.
|
||||
- Never commit real keys, tokens, webhook URLs, signing secrets, or private
|
||||
Builder/customer data in examples or fixtures. Use placeholders that cannot be
|
||||
mistaken for working credentials.
|
||||
|
||||
## User Credentials Are Per-User Data — Never `process.env`
|
||||
|
||||
User credentials (API keys, third-party tokens) are per-user (or per-org) data. They MUST live in SQL, scoped per-user (`u:<email>:credential:KEY`) or per-org (`o:<orgId>:credential:KEY`). Always read with the request context:
|
||||
|
||||
```ts
|
||||
import { resolveCredential } from "@agent-native/core/credentials";
|
||||
const apiKey = await resolveCredential("OPENAI_API_KEY", { userEmail, orgId });
|
||||
```
|
||||
|
||||
Values are encrypted at rest (AES-256-GCM, shared `secrets/crypto.ts`): `saveCredential` encrypts on write and `resolveCredential` decrypts on read, with a transparent fallback for legacy plaintext rows. The agent's raw `db-query` / `db-exec` tools also cannot read credential rows — they are excluded from the scoped `settings` view. To encrypt pre-existing rows in place, run `pnpm action db-migrate-encrypt-credentials` (idempotent, non-destructive; needs the same `SECRETS_ENCRYPTION_KEY` / `BETTER_AUTH_SECRET` as the app).
|
||||
|
||||
On 2026-04-29 the previous one-arg `resolveCredential(key)` form fell back to `process.env[key]` and an unscoped global `settings` row, so every signed-in user inherited the deployment's credentials. Two guards now block this in CI (`pnpm prep`):
|
||||
|
||||
- `scripts/guard-no-env-credentials.mjs` — bans `process.env.<KEY>` reads in `packages/core/src/credentials/`, `secrets/`, `vault/`, and `templates/*/server/{lib,routes/api}/credential*` paths, except for an explicit allowlist of deploy-level vars (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `NETLIFY_*`, etc.). Per-line opt-out: `// guard:allow-env-credential — <reason>`.
|
||||
- `scripts/guard-no-unscoped-credentials.mjs` — bans one-arg calls to `resolveCredential` / `hasCredential` / `saveCredential` / `deleteCredential`. Per-line opt-out: `// guard:allow-unscoped-credential — <reason>`.
|
||||
|
||||
If a deploy-level value genuinely needs an env var (CI-set token, host secret), it's not a user credential — keep it out of the credentials/ secrets/ vault/ paths and the env-credentials guard won't see it.
|
||||
|
||||
## Guards
|
||||
|
||||
Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant leak class — request-state escaping into shared process state, and dev-mode sentinel identities used as production fallbacks.
|
||||
|
||||
- `scripts/guard-no-env-mutation.mjs` — bans `process.env.<KEY> = …` (and bracket / compound forms) anywhere in production code. On serverless, every warm container handles many concurrent requests in one Node process, so `process.env` mutation leaks across in-flight requests (the "restore" line at the end of a handler races and never helps — most recently the Zoom webhook). Use `runWithRequestContext({ userEmail, orgId, timezone }, fn)` from `@agent-native/core/server` instead — it's AsyncLocalStorage-backed and per-request safe. Allowlisted paths: `scripts/`, `*.spec.ts` / `*.test.ts`, `packages/core/src/dev**`, `templates/*/test/`, anything under `/cli/` or `/scaffold/`. Per-line opt-out: `process.env.X = y // guard:allow-env-mutation — <reason>`.
|
||||
- `scripts/guard-no-localhost-fallback.mjs` — bans the literal `"local@localhost"` / `'local@localhost'` / `` `local@localhost` `` in production code. The bug class: `getRequestUserEmail() ?? "local@localhost"` silently pools every unauthenticated request into a single shared tenant, leaking credentials, tools, and `application_state` rows between accounts. The right behavior is to throw / 401 when there's no session. Allowlisted paths: the dev-mode auth shim (`packages/core/src/server/auth.ts`), `packages/core/src/dev**`, tests, `scripts/`, `seed/` / `seeds/`, plus a few framework helpers that intentionally inspect or migrate the dev identity. SQL DDL `DEFAULT 'local@localhost'` and the Drizzle helper `.default('local@localhost')` are skipped per-line — schema column defaults are intentional dev fixtures, not the dangerous fallback pattern. Per-line opt-out: `email ?? "local@localhost" // guard:allow-localhost-fallback — <reason>`.
|
||||
|
||||
## Auth
|
||||
|
||||
- All actions are protected by the auth guard automatically.
|
||||
- Prefer actions for normal app data. Do not hand-write `/api/*` routes for
|
||||
CRUD, data queries, or action re-exports just to add auth; action endpoints
|
||||
already get auth and request context.
|
||||
- If you must create custom `/api/` routes, always call `getSession(event)` and reject requests without a session:
|
||||
|
||||
```ts
|
||||
import { getSession } from "@agent-native/core/server";
|
||||
|
||||
export default defineEventHandler(async (event) => {
|
||||
const session = await getSession(event);
|
||||
if (!session) throw createError({ statusCode: 401 });
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
- Never create unprotected routes that modify data.
|
||||
|
||||
**Exception — the SSR HTML/`.data` catch-all is deliberately session-blind.**
|
||||
The rule above is for routes that read or mutate user data. The SSR page
|
||||
render and React Router `.data` route are different: they serve one
|
||||
impersonal, public-cacheable shell to every visitor by design, and loaders on
|
||||
that path render no user data. Do not "fix" this by adding `getSession`,
|
||||
`private`, or `no-store` to it — that regresses the CDN cache contract for the
|
||||
whole site. Data scoping lives in actions and API routes; the client gates
|
||||
private UI after the shell loads. See the `authentication` skill and
|
||||
`guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
|
||||
|
||||
## Human-in-the-Loop Approval for High-Consequence Actions
|
||||
|
||||
For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
|
||||
|
||||
```ts
|
||||
export default defineAction({
|
||||
description: "Send an email via Gmail.",
|
||||
schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
|
||||
needsApproval: true, // or (args, ctx) => boolean | Promise<boolean>
|
||||
run: async (args) => {
|
||||
/* ...actually send... */
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
|
||||
|
||||
Rules:
|
||||
|
||||
- Reach for `needsApproval` only for genuinely high-consequence operations. The default is off, and the framework intentionally keeps approvals rare — over-gating turns the agent into a click-through wizard. The canonical (and intentionally lone) framework example is Mail's `send-email`.
|
||||
- `needsApproval` is **not** a substitute for `accessFilter` / `assertAccess` or for hiding sensitive operations from the model with `agentTool: false` / `toolCallable: false`. It is the layer for "a human must explicitly bless this specific outward-facing call," not for scoping data. See the `actions` skill for the full surface.
|
||||
|
||||
## Custom HTTP Routes Must Apply Access Control Themselves
|
||||
|
||||
This is the single most-failed rule in the codebase. Auto-mounted action routes (`/_agent-native/actions/...`) get a request context wired up automatically. **Hand-written `/api/*` Nitro routes do not.** If your handler queries an ownable resource (any table with `...ownableColumns()`), you MUST:
|
||||
|
||||
1. Read the session: `const session = await getSession(event).catch(() => null)`.
|
||||
2. Run the work inside `runWithRequestContext({ userEmail: session?.email, orgId: session?.orgId }, fn)` from `@agent-native/core/server`.
|
||||
3. Inside `fn`, query through one of:
|
||||
- `accessFilter(table, sharesTable)` in the WHERE clause for list/read-many.
|
||||
- `resolveAccess("<type>", id)` for read-by-id (returns null if no access — return 404, not 403, so existence isn't leaked).
|
||||
- `assertAccess("<type>", id, "viewer"|"editor"|"admin")` for write/delete-by-id.
|
||||
|
||||
```ts
|
||||
// Bad — Brent's signup leaked every other user's decks because of this exact shape.
|
||||
export default defineEventHandler(async () => {
|
||||
const db = getDb();
|
||||
return db.select().from(schema.decks); // no access filter!
|
||||
});
|
||||
|
||||
// Good
|
||||
import { getSession, runWithRequestContext } from "@agent-native/core/server";
|
||||
import { accessFilter } from "@agent-native/core/sharing";
|
||||
export default defineEventHandler(async (event) => {
|
||||
const session = await getSession(event).catch(() => null);
|
||||
return runWithRequestContext(
|
||||
{ userEmail: session?.email, orgId: session?.orgId },
|
||||
async () => {
|
||||
const db = getDb();
|
||||
return db
|
||||
.select()
|
||||
.from(schema.decks)
|
||||
.where(accessFilter(schema.decks, schema.deckShares));
|
||||
},
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
`scripts/guard-no-unscoped-queries.mjs` runs in `pnpm prep` and fails the build if any file in `templates/*/server/`, `templates/*/actions/`, or `packages/*/src/` queries an ownable table without one of the access helpers. Last-resort opt-out is the marker comment `// guard:allow-unscoped — <reason>` — only use it for cases like the sharing primitives themselves or share-token-public viewer endpoints, and always include a reviewer-readable reason.
|
||||
|
||||
## Data Scoping
|
||||
|
||||
In production, the framework automatically restricts all agent SQL queries to the current user's data using temporary views. This is enforced at the SQL level — the agent cannot bypass it.
|
||||
|
||||
The `db-query` / `db-exec` tools (and the extension SQL bridge, which shares the same path) reject schema-qualified table references like `public.<table>` or `main.<table>` — a qualified name resolves to the base table and would skip the temp view. Use bare table names; scoping is applied automatically.
|
||||
|
||||
### Per-User Scoping (`owner_email`)
|
||||
|
||||
Every template table with user data **must** have an `owner_email` text column:
|
||||
|
||||
1. Framework detects `owner_email` via schema introspection
|
||||
2. Creates temp views `WHERE owner_email = <current user>` before each query
|
||||
3. Auto-injects `owner_email` into INSERT statements
|
||||
|
||||
The current user is resolved from `AGENT_USER_EMAIL` (set automatically from the session).
|
||||
|
||||
### Per-Org Scoping (`org_id`)
|
||||
|
||||
For multi-org apps, tables also need `org_id`:
|
||||
|
||||
1. `WHERE org_id = <current org>` is added (in addition to `owner_email` if present)
|
||||
2. `org_id` is auto-injected into INSERT statements
|
||||
|
||||
Enable org scoping in the agent-chat plugin:
|
||||
|
||||
```ts
|
||||
createAgentChatPlugin({
|
||||
resolveOrgId: async (event) => {
|
||||
const ctx = await getOrgContext(event);
|
||||
return ctx.orgId;
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Column Conventions
|
||||
|
||||
| Column | Purpose | Required |
|
||||
| ------------- | ----------------------- | ------------------------------- |
|
||||
| `owner_email` | Per-user data isolation | Yes, for all user-facing tables |
|
||||
| `org_id` | Per-org data isolation | Yes, for multi-org apps |
|
||||
|
||||
Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org apps.
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] New action uses `defineAction` with a Zod `schema:`
|
||||
- [ ] No SQL string concatenation with user input
|
||||
- [ ] No `dangerouslySetInnerHTML` with user content
|
||||
- [ ] Server-side fetches of user/agent URLs use `ssrfSafeFetch`, not bare `fetch`
|
||||
- [ ] Secrets stored via `saveCredential` / the vault (encrypted), never raw in `settings` or responses
|
||||
- [ ] No hardcoded API keys, tokens, webhook URLs, signing secrets, real
|
||||
credential-looking strings, private Builder/internal data, or customer data
|
||||
- [ ] New env vars in `.env` only, not committed
|
||||
- [ ] New user-data tables have `owner_email` column
|
||||
- [ ] Custom routes call `getSession` and reject unauthenticated requests
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `storing-data` — SQL patterns and the agent's db tools
|
||||
- `actions` — `defineAction` with Zod schema validation
|
||||
- `authentication` — Auth modes, sessions, and org context
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
name: self-modifying-code
|
||||
description: >-
|
||||
How the agent can modify the app's own source code. Use when the agent needs
|
||||
to edit components, routes, styles, or scripts, when designing UI for agent
|
||||
editability, or when deciding what the agent should and shouldn't modify.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Self-Modifying Code
|
||||
|
||||
## Rule
|
||||
|
||||
The agent can edit the app's own source code — components, routes, styles, scripts. This is a feature, not a bug. Design your app expecting this.
|
||||
|
||||
## Why
|
||||
|
||||
An agent-native app isn't just an app the agent can _use_ — it's an app the agent can _change_. The agent can fix bugs, add features, adjust styles, and restructure code. This makes the agent a true collaborator, not just an operator.
|
||||
|
||||
## Modification Taxonomy
|
||||
|
||||
Not all modifications are equal. Use this to decide what level of care is needed:
|
||||
|
||||
| Tier | What | Examples | After modifying |
|
||||
| ------------- | --------------------- | ------------------------------------------------ | --------------------------------- |
|
||||
| 1: Data | Files in `data/` | JSON state, generated content, markdown | Nothing — these are routine |
|
||||
| 2: Source | App code | Components, routes, styles, scripts | Run `pnpm typecheck && pnpm lint` |
|
||||
| 3: Config | Project config | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first |
|
||||
| 4: Off limits | Secrets and framework | `.env`, `@agent-native/*` packages & overrides | Never modify these |
|
||||
|
||||
Tier 4 includes **all** of the following — not only editing package source:
|
||||
|
||||
- Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
|
||||
- `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
|
||||
target any `@agent-native/*` package
|
||||
- Local package patches or invented "dispatch/core behavior" shims meant to
|
||||
paper over a version skew or failed upgrade
|
||||
|
||||
This does not prohibit intentional app-owned UI customization. When public
|
||||
props and composition are insufficient, the `customizing-agent-native` skill
|
||||
uses `agent-native eject` to transfer the smallest supported unit from the
|
||||
installed package into the app. The ejected unit must keep public runtime
|
||||
contracts and must not replace Core auth, DB, actions, agent execution, or
|
||||
transport behavior. Manual copying is only the fallback described by an unknown
|
||||
third-party package's add-style blueprint.
|
||||
|
||||
When an older branch needs current packages, use **`agent-native upgrade`**
|
||||
(see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
|
||||
**app** code or stop and ask — do not patch the framework.
|
||||
|
||||
## Git Checkpoint Pattern
|
||||
|
||||
Before modifying source code (Tier 2+), create a rollback point:
|
||||
|
||||
1. Commit or stash current state
|
||||
2. Make the edit
|
||||
3. Run `pnpm typecheck && pnpm lint`
|
||||
4. If verification fails → revert with `git checkout -- <file>`
|
||||
5. If verification passes → continue
|
||||
|
||||
This ensures the agent can experiment without breaking the app.
|
||||
|
||||
## Designing for Agent Editability
|
||||
|
||||
Make your app easy for the agent to understand and modify:
|
||||
|
||||
**Expose UI state via `data-*` attributes** so the agent knows what's selected:
|
||||
|
||||
```ts
|
||||
const el = document.documentElement;
|
||||
el.dataset.currentView = view;
|
||||
el.dataset.selectedId = selectedItem?.id || "";
|
||||
```
|
||||
|
||||
**Expose richer context via `window.__appState`** for complex state:
|
||||
|
||||
```ts
|
||||
(window as any).__appState = {
|
||||
selectedId: id,
|
||||
currentLayout: layout,
|
||||
itemCount: items.length,
|
||||
};
|
||||
```
|
||||
|
||||
**Use configuration-driven rendering** — Extract visual decisions (colors, layouts, sizes) into JSON config files in `data/`. The agent can modify the config (Tier 1) instead of the component source (Tier 2).
|
||||
|
||||
**Keep localized copy in catalogs** — When editing visible UI copy, labels,
|
||||
toasts, empty states, prompts, or formatting, read `internationalization` and
|
||||
update `app/i18n/en-US.ts` plus existing locale catalogs instead of leaving new
|
||||
inline strings in components.
|
||||
|
||||
## Don't
|
||||
|
||||
- Don't modify `.env` files or files containing secrets
|
||||
- Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
|
||||
`@agent-native/*` package internals (including under `node_modules`)
|
||||
- Don't confuse readable package source with app-owned code: use
|
||||
`customizing-agent-native` and `agent-native eject` for supported ownership
|
||||
transfer
|
||||
- Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
|
||||
`@agent-native/*` to "make the app run" after a version bump
|
||||
- Don't invent local dispatch/core behavior overrides when upgrade fails —
|
||||
run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
|
||||
- Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
|
||||
- Don't skip the typecheck/lint step after editing source code
|
||||
- Don't make source changes without a git checkpoint to roll back to
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **upgrade-agent-native** — supported path to bring an older app/workspace current
|
||||
- **customizing-agent-native** — configure, compose, or eject installed features safely
|
||||
- **storing-data** — Tier 1 modifications (data files) are the safest and most common
|
||||
- **actions** — The agent can create or modify actions to add new capabilities
|
||||
- **delegate-to-agent** — Self-modification requests come through the agent chat
|
||||
- **real-time-sync** — Database writes trigger change events to update the UI
|
||||
- **internationalization** — UI copy, language catalogs, locale switching, and RTL-safe edits
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: shadcn-ui
|
||||
description: >-
|
||||
Use when adding, updating, debugging, styling, or composing shadcn/ui
|
||||
components, forms, dialogs, menus, charts, sidebars, themes, registries, or
|
||||
any project with a components.json file.
|
||||
scope: dev
|
||||
source: https://ui.shadcn.com/docs/skills
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# shadcn/ui
|
||||
|
||||
This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them.
|
||||
|
||||
## First Steps
|
||||
|
||||
1. Work from the app root that owns `components.json`.
|
||||
2. In an Agent Native app, inspect `app/design-system.ts` and
|
||||
`ToolkitProvider` before choosing a primitive. A registered company design
|
||||
system takes precedence over the default shadcn adapter.
|
||||
3. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
|
||||
4. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
|
||||
5. Check `app/components/ui/` or the resolved `ui` path before importing a component.
|
||||
6. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
|
||||
|
||||
## Agent Native Adapter Rule
|
||||
|
||||
Pages, routes, and domain components import controls through the app's local UI
|
||||
adapter layer. Never import `@agent-native/toolkit/ui/*` directly in app product
|
||||
code. Direct imports bypass `app/design-system.ts` and make Toolkit/Core
|
||||
surfaces use different controls from the app.
|
||||
|
||||
When shadcn is the app's adapter, add or update the local primitive and keep
|
||||
product code on that local import. When a company design system is registered,
|
||||
adapt its components to the semantic contracts from
|
||||
`@agent-native/toolkit/design-system`; do not recreate a parallel shadcn
|
||||
surface. The semantic API is styling-runtime agnostic, so do not require
|
||||
Tailwind, CVA, or `className` in customer adapters.
|
||||
|
||||
For shared Toolkit features, customize presentation through semantic
|
||||
components, a feature-level controller, and product-level render slots. Keep
|
||||
the same controller for default and custom views. Use the conformance kit for
|
||||
behavior components whose focus, portal, keyboard, dismissal, or stacking
|
||||
behavior comes from the company design system.
|
||||
|
||||
## Adding Or Updating Components
|
||||
|
||||
- Add missing primitives with `pnpm dlx shadcn@latest add <component>` from the app root.
|
||||
- Before overwriting an existing component, use `pnpm dlx shadcn@latest add <component> --dry-run` and `--diff` to inspect the change.
|
||||
- After adding registry code, read the generated files. Fix import aliases, icon imports, missing subcomponents, and composition issues before using the component.
|
||||
- Do not fetch raw component files manually from GitHub when the shadcn CLI can resolve the registry item.
|
||||
- If a user asks to add a third-party block but does not name a registry, ask which registry to use instead of guessing.
|
||||
|
||||
## Component Composition
|
||||
|
||||
- Use existing primitives before custom markup: `Alert` for callouts, `Badge` for small status labels, `Separator` for dividers, `Skeleton` for placeholders, `Table` for tabular data, and `Card` for framed content.
|
||||
- Use full card anatomy when appropriate: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter`.
|
||||
- Dialog, Sheet, Drawer, and AlertDialog content must include an accessible title. Use visually hidden titles only when the visible UI already communicates the title.
|
||||
- Put items inside their group components: `SelectItem` in `SelectGroup`, `DropdownMenuItem` in `DropdownMenuGroup`, `CommandItem` in `CommandGroup`, and equivalent menu groups.
|
||||
- `TabsTrigger` belongs inside `TabsList`.
|
||||
- `Avatar` always needs `AvatarFallback`.
|
||||
- Buttons do not have magic loading props. Compose loading with `disabled`, `Spinner`, and clear text.
|
||||
|
||||
## Forms And Inputs
|
||||
|
||||
- Use the app's shadcn form primitives instead of raw div stacks.
|
||||
- If `Field`, `FieldGroup`, `FieldSet`, or `InputGroup` are installed or worth adding, use them for form layout, grouped fields, and input add-ons.
|
||||
- Do not place buttons inside inputs with absolute positioning. Use `InputGroup` and `InputGroupAddon` when available.
|
||||
- Use `ToggleGroup` for small option sets, `RadioGroup` for one-of-many choices, `Checkbox` for multi-select, `Switch` for settings toggles, `Select` or `Combobox` for predefined choices, and `Slider` or numeric input for numeric values.
|
||||
- Validation must be accessible: pair visual invalid states with `aria-invalid`, and connect descriptions/errors to controls.
|
||||
|
||||
## Styling And Theming
|
||||
|
||||
- Use semantic tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `border-border`, `text-destructive`) instead of raw colors for reusable app UI.
|
||||
- Prefer built-in variants and sizes before custom classes.
|
||||
- Use `className` mostly for layout and spacing; avoid overriding component colors and typography unless the component is intentionally being extended.
|
||||
- Use `gap-*` instead of `space-x-*` / `space-y-*`.
|
||||
- Use `size-*` when width and height are equal.
|
||||
- Use `truncate` for single-line clipping.
|
||||
- Use `cn()` for conditional classes.
|
||||
- Do not add manual `z-index` to overlay primitives unless you are fixing a verified stacking bug.
|
||||
- Add custom colors as CSS variables in the existing Tailwind CSS file reported by shadcn info. For Tailwind v4, register variables with `@theme inline`.
|
||||
|
||||
## Transitions And Motion
|
||||
|
||||
shadcn's built-in component animations are the right level of polish — keep them. The goal is a snappy, clean UI, not a motionless one. Match shadcn's motion vocabulary; don't strip it and don't pile on decorative custom animation.
|
||||
|
||||
- **Never remove or override a shadcn component's default animation.** `data-[state=open]:animate-in`, `data-[state=closed]:animate-out`, `fade-in/out`, `zoom-in/out`, `slide-in-from-*`, accordion height, the `tailwindcss-animate` utilities — these ship for a reason. Leave them as-is.
|
||||
- **Custom transitions are fine when they communicate a state change and match shadcn's feel.** Reuse the same vocabulary: short durations (~120–200ms), `ease-out`, opacity/transform only, gated on `data-[state=...]`. Examples that are good and welcome:
|
||||
- A portaled custom popover/tooltip/sheet that fades + scales/slides in on `data-[state=delayed-open]` / `data-[state=closed]`, mirroring Radix's own content animation.
|
||||
- A list row or toast that fades/slides in on mount and out on dismiss.
|
||||
- A chevron/caret `rotate` on expand, a subtle `opacity`/`color` hover on an icon button, skeleton shimmer, a progress/height transition on a collapsible.
|
||||
- Continuous, product-defining motion where it _is_ the experience (e.g. a multi-stage booking flow's stage transitions) — fine, and framer-motion is acceptable there.
|
||||
- **Avoid decorative, attention-seeking, or slow motion:** hand-rolled `duration-700` hero fade-ins, parallax, bouncing/spring entrances on ordinary content, animated gradients, staggered cascades on long lists, anything that delays the user seeing or acting on content. If an animation makes the UI feel slower, cut it.
|
||||
- Rule of thumb: if the motion clarifies what just changed and is over in well under a quarter-second, it's polish; if it's there to look impressive, it's bloat.
|
||||
|
||||
## Icons
|
||||
|
||||
- Agent-native apps use `@tabler/icons-react`. Do not add `lucide-react` because a registry example used it.
|
||||
- If registry code imports a different icon package, replace those imports with Tabler equivalents before finishing.
|
||||
- Let shadcn components size icons through their CSS. Avoid manual icon sizing inside buttons, menus, alerts, and sidebars unless the local component API requires it.
|
||||
|
||||
## Base-Specific APIs
|
||||
|
||||
Check the project context before using trigger composition APIs:
|
||||
|
||||
- Radix-based components use `asChild` for custom triggers.
|
||||
- Base UI components may use `render` and sometimes `nativeButton={false}`.
|
||||
|
||||
Do not wrap triggers in extra divs just to place a Button or Link inside them.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **frontend-design** — Product UX, visual direction, responsive polish, and verification
|
||||
- **customizing-agent-native** — Registered design systems, controllers, slots, conformance, and ejection
|
||||
- **actions** — Data fetching and mutation patterns for agent-native apps
|
||||
- **security** — User data, forms, external input, and action safety
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
name: upgrade-agent-native
|
||||
description: >-
|
||||
Bring an older Agent Native app or workspace current. Use when updating
|
||||
@agent-native/core, fixing a broken upgrade, or when tempted to patch or
|
||||
override core/dispatch packages to make an old branch run.
|
||||
scope: dev
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
|
||||
# Upgrade Agent Native
|
||||
|
||||
## Rule
|
||||
|
||||
When an older Agent Native app/branch needs to run on current packages, use
|
||||
`agent-native upgrade`. Never "fix" upgrade breakage with
|
||||
`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
|
||||
edits under `node_modules/@agent-native/*` — especially not against
|
||||
`@agent-native/core` or `@agent-native/dispatch`.
|
||||
|
||||
## Why
|
||||
|
||||
Agents often respond to a failed core bump by inventing framework patches and
|
||||
dispatch behavior overrides. That hides the real app-level break, drifts from
|
||||
upstream, and makes the next upgrade worse. The supported path is bump →
|
||||
install → refresh scaffold skills → verify, then fix **app** code only.
|
||||
|
||||
## How
|
||||
|
||||
1. **Preview migration codemods first**
|
||||
|
||||
```bash
|
||||
npx @agent-native/core@latest upgrade --codemods
|
||||
```
|
||||
|
||||
Codemods are preview-by-default: read the diff before applying it. Do not
|
||||
manually edit imports before running this command; the migration manifest is
|
||||
the source of truth for renamed specifiers and symbols.
|
||||
|
||||
2. **Apply the reviewed codemods, then run the upgrade**
|
||||
|
||||
```bash
|
||||
npx @agent-native/core@latest upgrade --codemods --yes
|
||||
npx @agent-native/core@latest upgrade
|
||||
```
|
||||
|
||||
Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
|
||||
`agent-native upgrade`.
|
||||
|
||||
What it does:
|
||||
|
||||
- Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
|
||||
- Rewrites non-local `@agent-native/*` dependency pins to `latest`
|
||||
- Runs the package manager install
|
||||
- Runs `skills update scaffold --project`
|
||||
- Runs `typecheck` when the project has that script
|
||||
|
||||
3. **Pull upstream template changes (optional, separate from the bump)**
|
||||
|
||||
`agent-native upgrade` moves package versions. It never touches files that
|
||||
were copied out of a template at scaffold time, so template fixes and
|
||||
improvements do not arrive with a bump.
|
||||
|
||||
```bash
|
||||
agent-native template status # recorded ref vs latest, drift counts
|
||||
agent-native template diff # what upstream changed, read-only
|
||||
agent-native template sync # 3-way merge it into the app
|
||||
```
|
||||
|
||||
`sync` defaults to the ref matching the installed `@agent-native/core`, so
|
||||
run it after `upgrade`. It merges per file against a pristine baseline
|
||||
stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
|
||||
did not touch are left alone, and real collisions get conflict markers.
|
||||
After resolving markers, run `agent-native template accept` — the baseline
|
||||
deliberately does not advance past an unresolved merge.
|
||||
|
||||
Apps scaffolded before provenance existed have no baseline. Create one
|
||||
with `agent-native template baseline` before the first sync.
|
||||
|
||||
4. **If upgrade or typecheck fails**
|
||||
|
||||
- Read the concrete error
|
||||
- Fix **app** source, actions, config, or env — not framework packages
|
||||
- Re-run `agent-native upgrade` or `pnpm typecheck`
|
||||
- Stop and ask the user if you cannot fix the app-level error
|
||||
|
||||
Intentional app-level UI customization is a separate workflow. Read
|
||||
`customizing-agent-native` when the product needs to own a selectively
|
||||
copied component; do not use that path to reproduce framework runtime
|
||||
behavior or hide version skew.
|
||||
|
||||
5. **Dry-run / partial runs**
|
||||
|
||||
```bash
|
||||
agent-native upgrade --dry-run
|
||||
agent-native upgrade --skip-verify
|
||||
agent-native upgrade --skip-install # package.json bumps only
|
||||
agent-native doctor --only migration-manifest
|
||||
```
|
||||
|
||||
`migration-manifest` has no opt-out. Run it in CI before upgrading to find
|
||||
imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`
|
||||
to preview the supported rewrite.
|
||||
|
||||
## Don't
|
||||
|
||||
- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
|
||||
`patchedDependencies` for any `@agent-native/*` package
|
||||
- Don't edit `node_modules/@agent-native/core` or
|
||||
`node_modules/@agent-native/dispatch`
|
||||
- Don't invent local "dispatch behavior" shims to paper over version skew
|
||||
- Don't keep iterating with more framework patches after a failed install
|
||||
- Don't skip `skills update scaffold --project` after a core bump (the
|
||||
upgrade command does this for you)
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **self-modifying-code** — Tier 4: framework packages are off limits
|
||||
- **agent-native-docs** — version-matched docs after the bump
|
||||
- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
|
||||
- **portability** — keep app code provider-agnostic across upgrades
|
||||
Reference in New Issue
Block a user