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 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?
mkdir -p ~/.claude/skills/feature-flag # Save SKILL.md to ~/.claude/skills/feature-flag/SKILL.md
- 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.
- 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.
- 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.
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.