Skip to content

BuilderIO/agent-native / .agents/skills/feature-flags

feature-flags

Verified

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.

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.

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.",
});

Never import defineFeatureFlag from @agent-native/core/feature-flags. That barrel is server evaluation (isFeatureFlagEnabled) plus store code; Vite will follow it into the browser and crash the page. Plugin and A2A auth helpers live on @agent-native/core/server (or @agent-native/core/feature-flags/server).

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.

import { createFeatureFlagsPlugin } from "@agent-native/core/server";

import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";

export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });

Definitions live in one process-wide registry (a globalThis symbol in feature-flags/registry.ts, like the labs registry). In local dev the plugin can load core from source while actions load the built package; a module-local map gave each copy its own registry, so get-feature-flags saw no definitions and every flag read as off. Keep the shared registry when touching that module.

3. Guard server and client

The server action is the enforcement boundary:

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:

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. When the flag-off UI must not flash before the answer arrives (a whole page swaps on the flag), use useFeatureFlagState(key): it returns { status: "loading" | "ready" | "unavailable", enabled }, so the surface can hold a layout-matching skeleton while status is "loading". 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. It adds you to the rule that decides your access (see Rule scopes).
  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:

ActionPurpose
get-feature-flagsReturn the current caller's evaluated boolean values.
list-feature-flagsReturn definitions and rollout metadata to an authorized operator.
set-feature-flagAtomically 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.

Rule scopes

A flag has up to two stored rules. The global rule (feature-flag:<key>) applies in every organization. Only emails on the target app's AGENT_NATIVE_FEATURE_FLAG_ADMIN_EMAILS list can change it, from inside any organization; outside production a caller with no organization can too. An organization's own rule (o:<orgId>:feature-flag:<key>) applies only there, and only that organization's owners and admins can change it; the admin list grants nothing at organization level. Evaluation uses the organization's rule when one exists and the global rule otherwise. They never merge: a global change does not reach an organization with its own rule. An organization gets a rule of its own only from off or replace-rules, which write a whole rule; enable-for-current-user adds to the rule in effect, so it refuses an organization that follows the global rule (409 follows_global_rule) and a row that can't be read (409 rule_unreadable).

set-feature-flag takes scope: "org" | "global". Without it, the active organization's rule is written, or the global rule for a caller with no organization, so a caller that predates scope never writes wider than before. The result's scope.kind names the rule written. list-feature-flags returns scopes per flag: the global rule, the caller's organization rule, which one is inEffect, and whether the caller can change each. A rule the caller can't change is withheld: its mode, percentage, and how many emails and organizations it targets, never which. A row that cannot be parsed is unreadable, never reported as unset; it still takes precedence and evaluates off, and getFeatureFlagRulesStrict throws on it. Over A2A, a global write passes only when the delegated email is on the target app's own list. Analytics checks that the target lists scopes before a global write, so a target that predates scope is refused rather than quietly writing the organization's rule.

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 the rule applies to.

Reversible experience presets

For an app with documented deviations, @agent-native/core/experience-profiles/server provides createExperienceProfileActions. It reuses the app's existing flag definitions and DEVIATIONS.md, and persists one user-scoped profile choice. This is a presentation preset, not a change to the fleet's global rollout rules. Reference sets every declared deviation to false; Agent-Native uses the promoted values declared by the app. Read packages/core/src/experience-profiles/README.md for the action, authorization, lazy-loading and QA contract. Keep app-specific views and deviation entries in the owning app repository.

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.
  • An organization owner not on the admin list cannot write the global rule; a listed admin can from inside any organization; organization writes still need that organization's owner or admin.
  • 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
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall