OpenParable
Skip to content
← Back to skills

Feature Switch

Development
feature-switch

Feature Switch is an Agent Skill for development published in the vm0-ai/vm0 repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Feature switch system guide for gating new user-facing features behind feature flags

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/vm0-ai/vm0/blob/HEAD/.claude/skills/feature-switch/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/feature-switch, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Feature Switch Skill

This skill documents the feature switch system and provides step-by-step instructions for adding new feature switches. All new user-facing features must be gated behind a feature switch for gradual rollout.

When to Use

A feature switch is required when adding:

  • New UI pages, sections, or sidebar navigation items
  • New API endpoints exposed to users or agents
  • New integrations (connectors, Slack, Telegram, etc.)
  • New zero token capabilities

A feature switch is not required for:

  • Internal refactors or code cleanup
  • Test infrastructure changes
  • Build/CI configuration
  • Bug fixes to existing features
  • Documentation updates

How to Add a Feature Switch

Step 1: Add a key to the enum

File: turbo/packages/core/src/feature-switch-key.ts

Add a new entry to FeatureSwitchKey:

export enum FeatureSwitchKey {
  // ... existing keys
  MyFeature = "myFeature",
}

Step 2: Register the switch

File: turbo/packages/core/src/feature-switch.ts

Add an entry to the FEATURE_SWITCHES record:

[FeatureSwitchKey.MyFeature]: {
  maintainer: "[email protected]",
  enabled: false,
  enabledOrgIdHashes: STAFF_ORG_ID_HASHES, // optional: staff-only access
},

Configuration options:

FieldTypeDescription
maintainerstringEmail of the responsible person
enabledbooleantrue = on for everyone, false = off by default
enabledUserHashesstring[]FNV-1a hashes of allowed user IDs
enabledEmailHashesstring[]FNV-1a hashes of allowed emails
enabledOrgIdHashesstring[]FNV-1a hashes of allowed org IDs

Common default states:

  • enabled: false — fully hidden until manually enabled via Lab page
  • enabled: false + enabledOrgIdHashes: STAFF_ORG_ID_HASHES — staff-only (most common for new features)
  • enabled: true — on for everyone (use when feature is ready for GA)

Step 3: Gate the feature in application code

Choose the pattern that matches where your feature is consumed.

Server-side (API routes)

import { isFeatureEnabled, FeatureSwitchKey } from "@vm0/core";

// In route handler:
if (!isFeatureEnabled(FeatureSwitchKey.MyFeature, { userId, orgId })) {
  return createErrorResponse("FORBIDDEN", "Feature not available");
}

Client-side (Platform UI)

import { FeatureSwitchKey } from "@vm0/core";
import { featureSwitch$ } from "../../signals/external/feature-switch.ts";

// In component:
const features = useLastResolved(featureSwitch$);
const showMyFeature = features?.[FeatureSwitchKey.MyFeature] ?? false;

// Conditional rendering:
{showMyFeature && <MyFeatureComponent />}

Sidebar navigation gating

In turbo/apps/platform/src/views/zero-page/zero-sidebar.tsx, add a featureGate to the sidebar item:

{
  id: "my-feature",
  label: "My Feature",
  icon: MyIcon,
  featureGate: FeatureSwitchKey.MyFeature,
}

Connector gating

In turbo/packages/core/src/contracts/connectors.ts, add featureFlag to the connector config:

myConnector: {
  label: "My Connector",
  featureFlag: FeatureSwitchKey.MyConnector,
  // ...
}

Zero token capability gating

In turbo/apps/api/src/signals/auth/tokens.ts, add to CONDITIONAL_CAPABILITIES:

const CONDITIONAL_CAPABILITIES: ReadonlyMap<ZeroCapability, FeatureSwitchKey> =
  new Map([
    // ... existing entries
    ["my-feature:write", FeatureSwitchKey.MyFeature],
  ]);

Key Files

FileRole
turbo/packages/core/src/feature-switch-key.tsEnum of all feature switch keys
turbo/packages/core/src/feature-switch.tsRegistry and evaluation logic
turbo/apps/platform/src/signals/external/feature-switch.tsClient-side reactive state with override layers
turbo/apps/platform/src/views/zero-page/zero-sidebar.tsxSidebar nav items with featureGate
turbo/packages/core/src/contracts/connectors.tsConnector type definitions with featureFlag field
turbo/apps/api/src/signals/auth/tokens.tsToken capability gating

Override Layers

Evaluation has two layers (lowest to highest priority):

  1. Core registry — static config in source code, evaluated against userId / email / orgId hashes.
  2. DB overrides — most switches are per-user rows in user_feature_switches keyed by (orgId, userId). Some switches are org-scoped and stored under the org sentinel user id (__org__); currently AgentUnreadIndicators and ChatThreadUnifiedSearch are org-scoped. Written via the Lab page toggles or window._vm0.featureSwitches.myFeature = true (both call POST /api/zero/feature-switches). Cleared via the Lab page "Reset all" button (DELETE /api/zero/feature-switches).

The same two-layer resolution applies on the server: route handlers that call isFeatureEnabled(..., { userId, orgId, overrides }) pass overrides loaded via loadFeatureSwitchOverrides(orgId, userId).

There is no client-only layer. window._vm0.featureSwitches requires auth and persists across refreshes; there is no device-local override.