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
- Verify the off path before changing rollout state.
- Confirm the registered flag appears in Analytics → Feature flags for the app and is Off by default.
- Use Enable for me for initial production dogfood. It adds you to the rule that decides your access (see Rule scopes).
- Expand to exact emails, organization IDs, or a percentage only from Analytics.
- 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.
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:
- Replace guarded branches with the chosen behavior.
- Delete the server and client gates.
- Delete the definition and registration entry.
- Verify the flag disappears from the Analytics fleet.
- 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, andpnpm guard:workspace-skillspasses 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