feat(feature-flags): add wizard feature-flags install skill by fristovic · Pull Request #378 · PostHog/context-mill

fristovic · 2026-09-01T19:14:41Z

The SDK can already evaluate flags. This skill does not add a flags engine. It installs the Next.js App Router pattern the SDK allows and a typical install almost never does: cheap, fast, safe to merge.

Default wizard is product analytics. wizard audit feature-flags is read-only. MCP / PostHog AI create and manage flags. Neither wires this pattern into the app. This is that install.

What it puts in the repo (vs SDK defaults)

One /flags call per request, not one per check. evaluateFlags(distinctId) once in the root layout, then flags.isEnabled(key). getFeatureFlag / isFeatureEnabled / getAllFlags each hit /flags again. PostHog bills those.
no second client fetch. Server values are bootstrapped into PostHogProvider. instrumentation-client.ts cannot take per-request bootstrap, so existing init there is moved into the provider.
Same distinct_id on server and client so percentage rollout is real. Anonymous apps get a ph_distinct_id cookie; identified apps reuse the real user id.
CI does not poll. advanced_disable_feature_flags in test/CI. No local-evaluation 30s poll on idle servers.
Optional worked example, off until they turn it on. One wizard_ask, skip first. Confirm → one boolean flag at 0% and one additive UI path. Auth / checkout / mutations are out of bounds. The SDK will not stop you from wrapping checkout at 100%.

Who this is for

A Next App Router team that wants the cheap/correct first hour, not “can I use flags?”. Skip is valid. If they already evaluate once on the server and bootstrap, they already have the benefit.

Pairs with wizard: PostHog/wizard#1192.

Docs: PostHog/posthog.com#19911 (/docs/feature-flags/installation/ai-wizard). Do not add that URL to mill shared_docs until https://posthog.com/docs/feature-flags/installation/ai-wizard.md returns 200.

sarahxsanders · 2026-09-01T22:29:53Z

+
+`advanced_disable_feature_flags: true` in test/CI stops forgotten CI jobs from polling `/flags` (see `cutting-costs.md`). A missing token in production is a no-op (render `children`); in development throw the missing-config error named in the framework guidelines.
+
+**If `instrumentation-client.ts` (or `.js`) already inits `posthog-js`:** move that init into this provider so bootstrap can be passed per request. Keep the existing `api_host` / `defaults` / other options. Do not leave both inits in place. Do not follow any framework note that says to keep init in `instrumentation-client.ts` — that path cannot take per-request bootstrap.


this might work better as a commandment (check and see if it already is, it might be) and see what this might contradict with in commandments in general

It seems like this already is a commandment, I missed that. I'll have to add an exception here I think because we want this skill to do the opposite so it can pass per-request bootstrap.

I will add a nextjs-flags-bootstrap commandment and tagg only this skill.

gewenyu99

Hey, this is a great start. I have some suggestions:

I'm not sure if I understand who would want/need this Wizard
Try setting up feature flags yourself, think about the pain points/difficult bits that someone is likely to fumble on, see if this resolves those issues.
I would think about this program's relationship to the main PostHog integration program and shared skill reuse. I think this contains a less reliable but duplicate version of many of they paths.

gewenyu99 · 2026-09-02T00:56:51Z

+
+Record: package manager, whether `src/` is used, and whether PostHog is already initialized (`posthog.init`, `PostHogProvider`, `instrumentation-client`, `posthog-js` / `posthog-node` in dependencies). If flags are already wired the way this skill describes (`evaluateFlags` + bootstrap + a gated call site), verify they are correct and skip to STEP 10.
+
+### STEP 2: Credentials


If we're installing the package, we can init this for them. There's examples you can copy from, the OAuth session will let you grab the token on the wizard side to add them. I think it'd be pretty odd to have an environment variable -> have no integration.

Yep, this was a sequencing leftover. This skill will now require an existing client init. OAuth still fills a missing phc_ into existing env names. If there's no init, we abort and point at npx @posthog/wizard instead of shipping a second integration.

gewenyu99 · 2026-09-02T00:58:19Z

+```ts
+import { PostHog } from 'posthog-node'
+
+export function PostHogServer(token: string) {


I'm gonna throw you one more wrench, you'll need to figure out a reasonable lower bound for the patterns you apply here. The way Next versions work across the board differs, and changes how PostHog need to be initialized. There are examples here in the repo

Actually, thats not a wrench at all, makes total sense. I went with Next.js App Router 15.3+, matching the mill Next commandment and example-apps/next-app-router (15.5.x).
We read package.json's next version and abort below that. On 15.3+ we still relocate instrumentation-client into the provider when bootstrap is required.

gewenyu99 · 2026-09-02T00:59:48Z

+
+Flags change production UI. Ask **once**, then create a flag and gate only if they picked a target.
+
+1. Scan pages and components for additive surfaces (a banner, an extra card, an empty-state illustration). Prefer a new element over wrapping existing critical logic.


🤔 Do you think someone is more likely to come to this program with a thing they have in mind and wanna gate, or do you think they'd be looking for suggestions on what to gate?

Both can be right depending on the user. That's why I built both options here:

Skip first = "I already know what I'll gate" (they add useFeatureFlagEnabled on the wiring we just installed)

Suggestions = "show me the loop, I don't know how this works"

Right? Feel free to correct me If I'm missing something here?

gewenyu99 · 2026-09-02T01:02:07Z

+const token = process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN
+const cookieStore = await cookies()
+const distinctId =
+  cookieStore.get('ph_distinct_id')?.value ?? crypto.randomUUID()


PostHog always generates a distinct_id on the frontend. You can call posthog.get_distinct_id(). If they're not identified, they'd have an anonymous distinct Id that's merged with the user on identify.

…he user

fristovic · 2026-09-02T16:13:22Z

Hey, this is a great start. I have some suggestions:

I'm not sure if I understand who would want/need this Wizard

I can see this easily being used by someone who wants to evaluate cheaply feature-flags (server eval, bootstrap, CI off). I don't see it as a flag factory. Default wizard won’t install this pattern.

On the fumbles: the ones I initially meant to hit are double /flags, first-paint render issue, CI polling overnight, and the deprecated per-call APIs (getFeatureFlag / getAllFlags). The weaker copy of the main integration (init, env, packages, Next version) was a real miss that I will address in the other comments.

On reuse: agreed. This skill will now extend an existing PostHog install instead of reimplementing it.

fristovic · 2026-09-02T17:51:07Z

Official docs page (draft): PostHog/posthog.com#19911 — /docs/feature-flags/installation/ai-wizard. Do not add that URL to shared_docs until it returns HTTP 200.

fristovic added 2 commits September 1, 2026 21:01

feat(feature-flags): add wizard feature-flags install skill

2ce1d07

feat(feature-flags): refactor feature-flags skill

7f47cc2

fristovic requested a review from a team as a code owner September 1, 2026 19:14

fristovic marked this pull request as draft September 1, 2026 20:36

feat(feature-flags): set 0% rollout on boolean flag

0613389

fristovic mentioned this pull request Sep 1, 2026

feat(feature-flags): add wizard feature-flags install program PostHog/wizard#1192

Draft

15 tasks

sarahxsanders reviewed Sep 1, 2026

View reviewed changes

gewenyu99 reviewed Sep 2, 2026

View reviewed changes

fristovic added 3 commits September 2, 2026 17:08

feat(feature-flags): stop killing the run if there is no demo widget

5976bf7

feat(feature-flags): add nextjs-flags-bootstrap commandment exception

5547044

feat(feature-flags): refacor description so it makes more sense for t…

1783e7e

…he user

fristovic mentioned this pull request Sep 2, 2026

docs: add AI wizard page for wizard feature-flags PostHog/posthog.com#19911

Draft

5 tasks

Navigation Menu

Uh oh!

feat(feature-flags): add wizard feature-flags install skill - #378

feat(feature-flags): add wizard feature-flags install skill#378
fristovic wants to merge 6 commits into
PostHog:mainfrom
fristovic:feat/feature-flags-program

fristovic commented Sep 1, 2026 •

edited

Loading

Uh oh!

sarahxsanders Sep 1, 2026

Uh oh!

fristovic Sep 2, 2026

Uh oh!

gewenyu99 left a comment

Uh oh!

gewenyu99 Sep 2, 2026

Uh oh!

fristovic Sep 2, 2026

Uh oh!

gewenyu99 Sep 2, 2026

Uh oh!

fristovic Sep 2, 2026

Uh oh!

gewenyu99 Sep 2, 2026

Uh oh!

fristovic Sep 2, 2026

Uh oh!

gewenyu99 Sep 2, 2026

Uh oh!

fristovic commented Sep 2, 2026

Uh oh!

fristovic commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		`advanced_disable_feature_flags: true` in test/CI stops forgotten CI jobs from polling `/flags` (see `cutting-costs.md`). A missing token in production is a no-op (render `children`); in development throw the missing-config error named in the framework guidelines.

		If `instrumentation-client.ts` (or `.js`) already inits `posthog-js`: move that init into this provider so bootstrap can be passed per request. Keep the existing `api_host` / `defaults` / other options. Do not leave both inits in place. Do not follow any framework note that says to keep init in `instrumentation-client.ts` — that path cannot take per-request bootstrap.


		Record: package manager, whether `src/` is used, and whether PostHog is already initialized (`posthog.init`, `PostHogProvider`, `instrumentation-client`, `posthog-js` / `posthog-node` in dependencies). If flags are already wired the way this skill describes (`evaluateFlags` + bootstrap + a gated call site), verify they are correct and skip to STEP 10.

		### STEP 2: Credentials


		Flags change production UI. Ask once, then create a flag and gate only if they picked a target.

		1. Scan pages and components for additive surfaces (a banner, an extra card, an empty-state illustration). Prefer a new element over wrapping existing critical logic.

Uh oh!

Conversation

fristovic commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gewenyu99 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fristovic commented Sep 2, 2026

Uh oh!

fristovic commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fristovic commented Sep 1, 2026 •

edited

Loading