Skip to main content
Agent skill

Feature Flag

Decision guide and implementation patterns for Gram's two feature-gating systems: productfeatures (org-level, admin-configurable, entitlement-tied) vs PostHog feature flags (per-user/per-group rollout, engineering-controlled). Activate whenever the task involves gating a feature behind a flag, dogfooding a change, deciding which system to use, or adding a new product feature or PostHog flag.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Feature Flag when an AI agent needs a reusable SKILL.md workflow for this job: Decision guide and implementation patterns for Gram's two feature-gating systems: productfeatures (org-level, admin-configurable, entitlement-tied) vs PostHog feature flags (per-user/per-group rollout, engineering-controlled). Activate whenever the task involves gating a feature behind a flag, dogfooding a change, deciding which system to use, or adding a new product feature or PostHog flag.

When not to use it

Skip Feature Flag when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/feature-flag
# Save SKILL.md to ~/.claude/skills/feature-flag/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/feature-flag/SKILL.md. For a shared project, commit the folder at .claude/skills/feature-flag/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Feature Flag skill for this task: Use Feature Flag when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
62/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

## Two systems, two purposes

Gram has two distinct feature-gating mechanisms. They are **not interchangeable** — pick based on the semantics of the flag, not on convenience.

| | `productfeatures` | PostHog feature flags | | ------------------- | ------------------------------------------------- | --------------------------------------- | | **Scope** | Per-organization | Per-user or per-group | | **Who controls it** | Org admins (dashboard) or Speakeasy ops | Engineering (PostHog console) | | **Persistence** | PostgreSQL (`organization_features` table) | PostHog platform | | **Direction** | Permanent capability toggle; maps to entitlements | Temporary rollout gate; removed once GA | | **Example use** | "This org has SSO" / "This org was sold Risk" | "Dogfood this UI change with our org" | | **Frontend** | `useProductFeatures()` hook | `posthog.isFeatureEnabled()` |

### Decision rule

> **Use `productfeatures`** when the toggle represents a durable, org-level capability that admins control or that maps to what the customer purchased (entitlement). Think: GCP's per-project API enablement. > > **Use PostHog flags** when you're rolling something out gradually, dogfooding a change internally, or need per-user granularity. The flag is expected to disappear once the feature ships to everyone.

If you're gating a dev-phase UI change that you only want your dogfooding org to see → **PostHog**. If you're shipping a capability that some customers pay for and others don't → **`productfeatures`**.

---

## `productfeatures`

### Concepts

- Feature constants live in `server/internal/productfeatures/features.go` as typed string constants (`Feature` type). - State is stored in `organization_features` (PostgreSQL). Soft-deletes track removal. - `productfeatures.Client` checks Redis first (15 min TTL), falls back to Postgres, and returns errors on lookup failures — use `PlatformFeatureCheck` when you want silent false-on-error degradation. - The management API (`/rpc/productFeatures.get` and `/rpc/productFeatures.set`) exposes the state to the dashboard and Speakeasy ops.

### Adding a new product feature

**1. Declare the constant** in [server/internal/productfeatures/features.go](../../../server/internal/productfeatures/features.go):

```go const ( FeatureMyNewFeature Feature = "my_new_feature" ) ```

**2. Add it to the Goa design** in [server/design/productfeatures/design.go](../../../server/design/productfeatures/design.go):

```go // In the setProductFeature method's Enum constraint: Enum("logs", "tool_io_logs", ..., "my_new_feature")

// In the getProductFeatures Result: Attribute("my_new_feature_enabled", Boolean, "Whether my new feature is enabled") ```

**3. Wire the result** in [server/internal/productfeatures/impl.go](../../../server/internal/productfeatures/impl.go):

```go MyNewFeatureEnabled: isEnabled(FeatureMyNewFeature), ```

**4. Regenerate** with `mise generate` (Goa codegen updates `gen/`).

### Checking a feature at runtime (Go)

```go // inject *productfeatures.Client — it's already wired in cmd/gram/start.go enabled, err := pf.IsFeatureEnabled(ctx, organizationID, productfeatures.FeatureMyNewFeature) if err != nil { return fmt.Errorf("check my_new_feature: %w", err) } ```

Use `PlatformFeatureCheck` (returns bool, logs errors, degrades to false) only in non-critical paths where you want silent degradation.

### Checking in the React dashboard

```tsx const { data: features } = useProductFeatures(); if (features?.myNewFeatureEnabled) { ... } ```

---

## PostHog feature flags

### Concepts

- Flag constants live in `server/internal/feature/flags.go` as a typed `Flag` string. - The `feature.Provider` interface (`IsFlagEnabled(ctx, flag, distinctID)`) is the only server-side API — inject it, don't call PostHog directly. - The PostHog implementation polls the PostHog platform; a noop stub is used in tests. - `distinctID` is typically the user's ID or email. For org-level targeting you can use the org ID and configure matching groups in PostHog.

### Adding a new PostHog flag

**1. Declare the constant** in [server/internal/feature/flags.go](../../../server/internal/feature/flags.go):

```go const ( FlagMyNewFeature Flag = "my-new-feature" // must match the key in PostHog ) ```

**2. Create the flag in PostHog** — set release conditions (e.g., "users in group X") via the PostHog console. The string key must match exactly.

**3. Check at runtime** by injecting `feature.Provider`:

```go enabled, err := featureProvider.IsFlagEnabled(ctx, feature.FlagMyNewFeature, userDistinctID) if err != nil || !enabled { // flag off or unavailable } ```

### Checking in the React dashboard

Use the `useTelemetry()` hook from `client/dashboard/src/contexts/Telemetry.tsx` — never import PostHog hooks directly:

```tsx const telemetry = useTelemetry(); const myFeatureEnabled = telemetry.isFeatureEnabled("my-new-feature") ?? false; ```

---

## Common mistakes

- **Don't use `productfeatures` for a temporary dogfood gate.** It creates API surface (`getProductFeatures` result field, Goa enum) that must be maintained indefinitely. - **Don't use PostHog for entitlements.** PostHog is engineer-controlled and ephemeral; entitlement checks belong in `productfeatures` so org admins and billing can manage them. - **Don't hardcode PostHog flag strings in multiple places.** Always declare them as constants in `feature/flags.go`. - **Don't call the PostHog SDK directly from Go handlers.** Always go through the `feature.Provider` interface so tests can inject a noop.

Intended uses

  • Use Feature Flag when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.