agent-native

The shadcn CLI, component composition, theming, and registry workflow. Use when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself, or when changing a theme or registry. Do not load it for ordinary edits to a file that happens to import a shadcn component.

Framework server plugins and the `/_agent-native/` route namespace. Use when adding a custom server plugin, deciding whether to create an `/api/` route vs an action, or debugging auto-mounted framework routes.

Tiers, checkpoints, and off-limits paths for an agent editing the app's own source. Use when designing UI for agent editability, deciding whether a file is safe for the agent to change, or when tempted to patch config, `.env`, or an `@agent-native/*` package. Do not load it for ordinary source edits.

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.

Declaratively register API keys and service credentials a template needs so they appear in the agent sidebar settings UI and the onboarding checklist. Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for surfacing OAuth connections in the unified settings UI.

How the agent must perform writes so they actually persist under the hosted foreground run budget and long-running background handoffs. Use whenever you create, update, delete, or batch-write app data — especially "do this for many items" loops, or any task where the user expects N things to end up saved.

Scheduled tasks the agent runs on a cron schedule. Use when a user asks for something recurring ("every morning", "daily", "weekly"), when creating or updating jobs, or when debugging the job scheduler.

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.

Multi-user collaborative editing with Yjs CRDT, SSE fast-path transport, and granular server-side merge. Use when adding real-time collaborative editing to a template, debugging sync issues, or understanding how the agent and humans edit documents simultaneously.

Autonomous multi-app QA sweep that drives template apps with Playwright MCP. Use only when the user explicitly runs /qa or asks for an end-to-end QA sweep. Do not load it for ordinary feature work, single-page checks, or one-off bug fixes.

How to keep template code database-agnostic and hosting-agnostic. Use when defining schemas, writing raw SQL, creating server routes, or anything that could leak a SQLite-only, Postgres-only, or Node-only assumption.

Keep apps and templates loading fast. Read when adding a data model, a list/read action, a page or sidebar that loads data, or when something loads slowly. Covers column projection, indexing hot-path queries, avoiding N+1 and round-trip waterfalls, cheap polling, and not recomputing on every read.

How to register user-facing setup steps (API keys, OAuth, connecting third-party services) for the sidebar setup checklist. Use when adding a feature that needs initial user configuration.

Agent observability, evals, feedback, and experiments. Use when adding observability dashboards, configuring trace capture, setting up evals, creating A/B experiments, or collecting user feedback on agent responses.

Only when explicitly asked for /new-branch or a fresh git branch: stash local changes, update main, and create it. Do not auto-run for normal coding, PR, Builder.io, or Fusion branch workflows.

Use when adding or reviewing UI navigation so internal routes preserve normal SPA behavior plus Cmd/Ctrl-click and middle-click new-tab semantics.

Use when asking what to do next after a feature pass while avoiding bloat and checking for unfinished MVP work.

Run or extend the Desktop Code Agents Multi-Frontier workflow. Use when coordinating Codex and Claude Code subscriptions, collaboration phases, checkpoints, recovery, usage meters, or helper admission.

How to add or edit localized UI copy in agent-native apps. Use when adding, removing, or changing user-visible interface text, prompts, toasts, labels, empty states, or date/number/list formatting.

Cross-platform pattern for handling messaging integration webhooks (Slack, Telegram, WhatsApp, email, etc.) on serverless hosts. Use when adding a new integration adapter, debugging dropped messages, or wiring long-running agent work into a webhook handler.

Add or use full agent harness runtimes like Claude Code, Codex, Pi, Cursor, Mastra, or ACP agents inside Agent Native.

Generate transient or saved inline chat UI with Alpine/Tailwind controls, outputs, app state, and extensions. Use for knobs, pickers, calculators, dashboards, widgets, or reusable mini-apps.

Sets the visual direction for a new or redesigned surface, with production quality that avoids generic AI aesthetics. Use when building a new page, app, or marketing surface, defining visual identity, or doing a design pass ("make this look good"). Do not load it for routine UI edits: adding a field to an existing form, fixing spacing, wiring a button, or changing copy.

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.

Connect external agents and MCP hosts (Claude, Claude Desktop, Claude Code, ChatGPT custom MCP apps, Codex, Cursor, Claude Cowork, VS Code GitHub Copilot, Goose, Postman, MCPJam) to an agent-native app over MCP, and round-trip artifacts back into the UI with MCP Apps and deep links. Use when adding an action's `link` builder or `mcpApp`, wiring the `/_agent-native/open` route, exposing an "ingest" action to MCP/A2A, or scaffolding apps from an external agent.