feature-flag

Skill: feature-flag

Purpose

Implement new features behind feature flags to enable safe, gradual rollouts and easy rollbacks without code deployments.

Trigger

Use when:

• Implementing a risky or large feature
• A feature needs gradual rollout
• A/B testing is desired
• The feature might need to be disabled quickly in production

Process

Step 1: Assess Flag Need

Determine if a feature flag is appropriate:

• Always flag: breaking changes, major UI changes, experimental features
• Consider flagging: new integrations, significant logic changes
• Skip flagging: bug fixes, minor improvements, refactors

Step 2: Define the Flag

# Flag definition
FLAG_NAME = "feature_[descriptive_name]"
FLAG_DEFAULT = False  # default to OFF for new features
FLAG_DESCRIPTION = "[what this flag controls]"
FLAG_OWNER = "[team or person responsible]"
FLAG_CREATED = "[date]"
FLAG_PLANNED_REMOVAL = "[date or milestone when flag should be cleaned up]"

Step 3: Implement the Guard

# Python example
from agent.config import get_feature_flag

def some_feature():
    if not get_feature_flag("feature_new_thing"):
        return existing_behavior()
    return new_behavior()

// TypeScript example
import { isFeatureEnabled } from './config/flags';

function someFeature() {
    if (!isFeatureEnabled('feature_new_thing')) {
        return existingBehavior();
    }
    return newBehavior();
}

Step 4: Test Both Paths

Write tests for BOTH flag states:

def test_feature_disabled(monkeypatch):
    monkeypatch.setenv("FEATURE_NEW_THING", "false")
    assert some_feature() == expected_old_behavior

def test_feature_enabled(monkeypatch):
    monkeypatch.setenv("FEATURE_NEW_THING", "true")
    assert some_feature() == expected_new_behavior

Step 5: Document the Flag

Add to docs/feature-flags.md:

| Flag | Default | Description | Owner | Remove By |
|------|---------|-------------|-------|-----------|
| feature_new_thing | false | [description] | [owner] | [milestone] |