Add Feature Flag

If unclear, ask James: "Which repo are we working in - MCP or AI Command Center?"

Step 2: Determine Flag Name

If coming from a Jira ticket, derive the flag name from the ticket summary. If not, ask James: "What should the feature flag be called?"

Naming Conventions

MCP:

AI Command Center:

Confirm with James: "I'll create flag batch_operations. Sound good?"

MCP Repository

Files to Update (5 files)

All paths relative to /Users/jbaldwin/repos/mcp:

2.1 Update env-config schema

File: packages/env-config/src/schema.ts

Add near the other FF_* variables:

FF_BATCH_OPERATIONS: Type.Optional(Type.Boolean()),

2.2 Update turbo.json

File: turbo.json

Add to the globalEnv array (keep alphabetical with other FF_ vars):

"FF_BATCH_OPERATIONS",

2.3 Add getter function

File: packages/feature-flags/src/split.ts

Add at the end of the file, following the existing pattern:

/**
 * Check if [description] is enabled
 *
 * @param user - User context for targeting (userId is used as the Split key)
 */
export const getIsBatchOperationsEnabled = async (
  user: SplitUserAttributes,
): Promise<boolean> => {
  // In local/test environments, check env var first (bypasses Split.io)
  if (env.APP_ENV === "local" || env.APP_ENV === "test") {
    return env.FF_BATCH_OPERATIONS ?? false;
  }

  // Fall back to Split.io for staging/production
  if (!client) {
    return false;
  }

  return getFeatureFlag(user.userId, "batch_operations", user);
};

2.4 Export the function

File: packages/feature-flags/src/index.ts

Add to the export list:

getIsBatchOperationsEnabled,

2.5 Update env example file

File: .env.development.local.example

Add:

# [Description of what this flag controls]
FF_BATCH_OPERATIONS=false

MCP Summary

Feature flag `batch_operations` scaffolded.

Files updated:
- packages/env-config/src/schema.ts
- turbo.json  
- packages/feature-flags/src/split.ts
- packages/feature-flags/src/index.ts
- .env.development.local.example

Next steps:
1. Create flag in Split.io dashboard (name: `batch_operations`)
2. Call `getIsBatchOperationsEnabled(user)` where you need the check

AI Command Center Repository

Files to Update (1 file for web, 1 for MCP app if needed)

All paths relative to /Users/jbaldwin/repos/ai-command-center:

3.1 Add to constants (web app)

File: apps/web/src/server-sdk/lib/feature-flags/constants.ts

Add to the featureFlagsWithDefaults object:

batch_operations: "off",

3.2 Add to MCP app (if flag is needed there)

File: apps/mcp/src/server-sdk/lib/feature-flags/split.ts

Add to the featureFlagsWithDefaults object:

batch_operations: "off",

AI Command Center Summary

Feature flag `batch_operations` scaffolded.

Files updated:
- apps/web/src/server-sdk/lib/feature-flags/constants.ts

Next steps:
1. Create flag in Harness dashboard (name: `batch_operations`, traffic type: "account")
2. Configure for both staging and production environments
3. Use server-side: `getFeatureFlagsFromSession(session)` then check `flags.batch_operations === "on"`
4. Use client-side: `useIsFlagEnabled("batch_operations")` or `isFlagEnabled("batch_operations")`
5. Local override: `OVERRIDE_FEATURE_FLAG_BATCH_OPERATIONS=on` in .env

Usage Patterns by Repository

MCP - Server-side usage

import { getIsBatchOperationsEnabled } from "@zapier/feature-flags";

const enabled = await getIsBatchOperationsEnabled(user);
if (enabled) {
  // new behavior
}

AI Command Center - Server-side usage

import { getFeatureFlagsFromSession } from "@/server-sdk/lib/feature-flags/split";

const flags = await getFeatureFlagsFromSession(session);
if (flags.batch_operations === "on") {
  // new behavior
}

AI Command Center - Client-side usage

import { useIsFlagEnabled, useFeatureFlags } from "@/hooks/user";

// Option 1: Single flag check
const isEnabled = useIsFlagEnabled("batch_operations");

// Option 2: Multiple flags
const { isFlagEnabled } = useFeatureFlags();
if (isFlagEnabled("batch_operations")) {
  // new behavior
}

SplitUserAttributes (MCP)

Available for targeting in MCP:

interface SplitUserAttributes {
  userId: string;           // Split key for user-level targeting
  accountId: number;
  zapierCustomUserId: number;
  email: string;            // Domain targeting (@zapier.com)
  isStaff: boolean;         // Staff-only rollouts
  role: string;
  signupDate: string;
  planType: string;
}

Targeting Attributes (AI Command Center)

Available for attribute-based targeting rules in Harness:

• isStaff - Staff-only rollouts
• role - Role-based targeting
• email - Email domain targeting
• accountId - Account-level targeting
• userId - User-level targeting
• isPaid - Paid plan targeting
• isEnterprise - Enterprise account targeting

Examples

Example 1: MCP repo, chained from work-on-ticket

James: "AGP-999"
Agent: [runs work-on-ticket skill]
Agent: "Bookmark created: agp-999-add-batch-operations. Ready to work on this."

James: "feature flag it"
Agent: "I'll create flag FF_BATCH_OPERATIONS / batch_operations. Sound good?"

James: "yes"
Agent: [scaffolds the 5 MCP files]
Agent: "Feature flag scaffolded. Next: create in Split.io, then implement."

Example 2: AI Command Center repo, standalone

James: "add feature flag enable_new_sidebar"
Agent: "I see we're in ai-command-center. I'll add `enable_new_sidebar` to constants.ts. What's the default - on or off?"

James: "off"
Agent: [updates constants.ts]
Agent: "Done. Flag added with default 'off'. Create in Harness, then use useIsFlagEnabled('enable_new_sidebar')."

Example 3: Unclear repo

James: "feature flag it"
Agent: "Which repo are we working in - MCP or AI Command Center?"

James: "mcp"
Agent: "What should the feature flag be called?"
...

Success Criteria

1. Correct repository detected
2. Flag names confirmed with James
3. All required files updated for that repo
4. Getter function/constant follows existing patterns
5. James informed of next steps (dashboard setup, usage pattern)