Adding A FeatureBLOCK

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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.

Scope check first: this is the checklist for a feature that adds app data or a new capability. A restyle, a copy change, or a screen with no new data model and no new agent-visible operation only needs the areas it actually touches — do not manufacture actions, state keys, or a skill for it.

## 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/hooks` 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.

**Agent edits must refresh the UI without a background poll.** Local chat-run
tool completions invalidate action queries and source counters after each
side-effecting tool and again at run end. There are two query paths:

- **`useActionQuery` / `useActionMutation`** — local action mutations invalidate `['action']` observers, and chat-run tool completions invalidate them for agent writes. No background sync opt-in is needed for the current user's agent run. **Prefer this path.**
- **Raw `useQuery` with custom keys** — fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client/hooks` into the `queryKey` and set `placeholderData: (prev) => prev`. Local chat-run side effects bump those counters too. Remote changes require the page's explicit `useDbSync({ realtime: { reason } })` opt-in only when data changes without the current user acting and must appear before refresh.

Never opt in public, anonymous, marketing, docs, or SSR routes, settings,
forms, or read-mostly lists. Refetch those on focus or navigation. Shared Slides
editing and the Mail inbox are the current first-party examples that need
remote updates. Each opted-in open tab adds a shared background transport and
one poll per idle interval; hidden tabs pause, and idle polling backs off to 1,
2, then 5 minutes. See `real-time-sync` for the decision rule and examples.

  ```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 credentials or include personal or customer data in source,
fixtures, docs, prompts, or generated app content. Register required secrets,
use OAuth helpers, or read scoped values from the credential store.

Before writing custom setup or credential UI, perform the shared-primitive
preflight from `agent-native-toolkit`: inspect the workspace/provider connection
catalog first, then settings, secrets/vault, OAuth, onboarding, and provider API
support. Reuse an existing connection's app grant and scoped credential
resolver; only use app-local vault or OAuth primitives when no reusable
connection exists. Keep any wizard thin and provider-specific - it may explain
prerequisites, ordering, or readiness, but must not become a second vault or
custom credential transport. Do not mark each field `required` by reflex;
model onboarding around the logical connection outcome.

If the feature involves attachments, images, recordings, screenshots, exports,
or other file-like payloads, design the upload path in 

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (6)

use OAuth helpers, or read scoped values from the credential store.

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Adding A Feature](https://modelsatlas.com/skills/builderio/adding-a-feature/badge.svg)](https://modelsatlas.com/skills/builderio/adding-a-feature/)

Not your listing, or something out of date? Claim or update your listing.