Skip to content

feat(integration): rules and agent wording per capture mode - #455

Closed
eli-r-ph wants to merge 2 commits into
feat/skill-menu-capture-modefrom
feat/capture-mode-commandments
Closed

eli-r-ph wants to merge 2 commits into
feat/skill-menu-capture-modefrom
feat/capture-mode-commandments

Conversation

@eli-r-ph

@eli-r-ph eli-r-ph commented Nov 3, 2026 •

Copy link
Copy Markdown

Problem

Several framework rules and the install agent tell the agent to install a PostHog SDK by bare name, the Swift rule tells it to look up the latest release, and the review agent may step a major down. Each of those moves a project off the major line the wizard set it up for. The rules also cannot differ between the legacy and v1 majors, which disagree on module paths, options arguments, AI capture methods, TLS features and deployment targets.

Stacked on #453.

Changes

  • A <tag>@v1 key in commandments.yaml holds the rules for the capture v1 majors; a variant gets them only when it declares capture_mode: v1. An untagged variant is mode-neutral and carries the base rules alone, so a skill that serves both modes never contradicts the integration skill beside it.
  • The base install rules are true for every consumer: run the wizard tool's command when it lists the SDK, otherwise install a bounded requirement for the installed major, never a bare name. Legacy-only facts became mode-neutral base rules.
  • The v1 rules were checked against the SDK branches and migration guides: snake_case option keys, the Node 6 captureException object form, the register fallback on iOS and Android, the personless-option warning, the AI capture method on every SDK, module paths, TLS features and deployment targets.
  • The install, review, install-step and revise wording runs the tool's command for a pinned SDK and never moves its major; the AI observability references send manual $ai_* events through the AI capture method on the new majors.

Test plan

Tests for the mode rules, that no legacy-only key exists, that every v1 key has a base tag some variant carries, and that no rule spells an option key in camelCase. pnpm test.

LLM context

Written with Claude Code (Claude Fable 5.1). An SDK owner should still read their @v1 block against the final guide before that SDK's flip.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown

🧙 Wizard CI

Run the Wizard CI and test your changes against wizard-workbench example apps by replying with a GitHub comment using one of the following commands:

Test all apps:

  • /wizard-ci all

Test all apps in a directory:

  • /wizard-ci ai-observability
  • /wizard-ci basic-integration
  • /wizard-ci feature-flags
  • /wizard-ci mcp-analytics
  • /wizard-ci replay-vision
  • /wizard-ci revenue
  • /wizard-ci self-driving
  • /wizard-ci warehouse
  • /wizard-ci warehouse-seeded

Test an individual app:

  • /wizard-ci ai-observability/anthropic
  • /wizard-ci ai-observability/google-adk
  • /wizard-ci ai-observability/groq
Show more apps
  • /wizard-ci ai-observability/manual-capture
  • /wizard-ci ai-observability/openai
  • /wizard-ci ai-observability/openai-agents
  • /wizard-ci ai-observability/opentelemetry
  • /wizard-ci ai-observability/vercel-ai
  • /wizard-ci basic-integration/android
  • /wizard-ci basic-integration/angular
  • /wizard-ci basic-integration/astro
  • /wizard-ci basic-integration/django
  • /wizard-ci basic-integration/fastapi
  • /wizard-ci basic-integration/flask
  • /wizard-ci basic-integration/flutter
  • /wizard-ci basic-integration/javascript-node
  • /wizard-ci basic-integration/javascript-web
  • /wizard-ci basic-integration/laravel
  • /wizard-ci basic-integration/next-js
  • /wizard-ci basic-integration/nuxt
  • /wizard-ci basic-integration/python
  • /wizard-ci basic-integration/rails
  • /wizard-ci basic-integration/react-native
  • /wizard-ci basic-integration/react-router
  • /wizard-ci basic-integration/sveltekit
  • /wizard-ci basic-integration/swift
  • /wizard-ci basic-integration/tanstack-router
  • /wizard-ci basic-integration/tanstack-start
  • /wizard-ci basic-integration/vue
  • /wizard-ci feature-flags/django
  • /wizard-ci feature-flags/next-js
  • /wizard-ci mcp-analytics/custom-dispatcher
  • /wizard-ci mcp-analytics/typescript-sdk
  • /wizard-ci replay-vision/javascript-node
  • /wizard-ci replay-vision/next-js
  • /wizard-ci replay-vision/react-vite
  • /wizard-ci revenue/stripe
  • /wizard-ci self-driving/astro
  • /wizard-ci self-driving/fastapi
  • /wizard-ci self-driving/nuxt
  • /wizard-ci self-driving/react-router
  • /wizard-ci self-driving/sveltekit
  • /wizard-ci warehouse/monorepo-env
  • /wizard-ci warehouse/multi-source-next
  • /wizard-ci warehouse/stripe-node
  • /wizard-ci warehouse/zero-source
  • /wizard-ci warehouse-seeded/next-stripe
  • /wizard-ci warehouse-seeded/next-stripe-declined

Test against a wizard branch:

  • /wizard-ci all wizard:my-branch

Add wizard:<branch> to any command above to pin the wizard branch. It defaults to main.

Results will be posted here when complete.

@eli-r-ph
eli-r-ph requested a review from a team November 3, 2026 00:26
commandments.yaml gains <tag>@legacy and <tag>@v1 keys; the generator adds
them to a variant's rules by its capture_mode, reading no mode as legacy.
The SDK install rules for python, go, rust, swift, ios and flutter now defer
to the exact command detect_package_manager returns, and the mode-specific
facts from the migration guides (module paths, options arguments, capture_ai,
TLS features, SPM-only iOS, deployment targets) sit under the mode keys. The
install and review agents run the tool's pinned command for an allowlisted
SDK and never move its major.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@eli-r-ph
eli-r-ph force-pushed the feat/capture-mode-commandments branch from cb0c0ba to ed99b18 Compare November 3, 2026 02:17
…the v1 majors

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Comment thread context/commandments.yaml
- "`capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group`, `captureException` and `captureAi` take an `options` argument as their last parameter for per-event controls such as `process_person_profile` (snake_case key). There are no global options: to turn person processing off for every event, `register([\"$process_person_profile\": false])`, which becomes the option at send time"
- "Send `$ai_*` events with `captureAi`, never with `capture`; the `$ai_` prefix is reserved for them"
- "On 4.0 a value set on the call beats a registered value, and a `setBeforeSend` hook must pass the event's options through unchanged"
react-native:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[question] React Native has no @v1 rules here. Is that deliberate, or should it get a block like the other mobile SDKs?

Comment thread context/commandments.yaml
- Capture screen views by adding `PosthogObserver()` to the app's `navigatorObservers`, whatever routing package the app uses; where its routes are unnamed, name them so `$screen` is readable
- Call `Posthog().identify(...)` after login and `Posthog().reset()` on logout; keep PII in user properties, not event properties
- Use `beforeSend` to redact or drop Dart-captured events, but remember it does not intercept native session replay, lifecycle, or system properties
- "For iOS, ensure the minimum deployment target is at least the floor the installed major needs: iOS `13.0` on posthog_flutter 5.x, iOS `15.0` (and macOS `11.0`) on 6.x. If the current `platform :ios` value is lower than that floor or missing, update or add it; if it is already at or above it, leave it unchanged"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] #479 rewrites the Flutter beforeSend rule right above this line, so whichever lands second will need a small rebase.

Comment thread context/commandments.yaml
@@ -322,6 +359,10 @@ commandments:
- Initialize PostHog in the Application class's `onCreate()` method
- Ensure every activity has a `android:label` to accurately track screen views.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[suggestion] Base android: has no rule for staying on the installed major (3.+/4.+), unlike iOS and Flutter. Could we add one so a 3.x app doesn't get bumped to 4.0?

Comment thread context/commandments.yaml
- Initialize PostHog in the Application class's `onCreate()` method
- Ensure every activity has a `android:label` to accurately track screen views.

android@v1:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[question] android@v1, ios@v1 and flutter@v1 only reach variants tagged capture_mode: v1, and no mobile variant in integration/config.yaml is tagged, so these rules never apply. Are we adding v1 mobile variants here or in a follow-up?

Comment thread context/commandments.yaml
android@v1:
- "`capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group`, `captureException` and `captureAi` take an options argument as their last parameter for per-event controls such as `process_person_profile` (snake_case key). There are no global options: to turn person processing off for every event, `register(\"$process_person_profile\", false)`, which becomes the option at send time"
- "Send `$ai_*` events with `captureAi`, never with `capture`; the `$ai_` prefix is reserved for them"
- "On 4.0 a value set on the call beats a registered value, and a `beforeSend` hook must pass the event's options through unchanged"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[suggestion] Could we also cover the other 4.0 breaks agents will hit: apiKey is gone (use projectToken), PostHogConfig.onFeatureFlags moved to the PostHog.onFeatureFlags { } listener, and session replay is screenshot-only?

Comment thread context/commandments.yaml
- "On 4.0 a value set on the call beats a registered value, and a `beforeSend` hook must pass the event's options through unchanged"
kmp:
- com.posthog:posthog-kmp is the Kotlin Multiplatform SDK package name; add it to the shared module's commonMain.dependencies in build.gradle.kts, not to androidMain, iosMain, or any platform-specific source set
- All PostHog APIs live in the com.posthog.kmp package — import com.posthog.kmp.PostHog, com.posthog.kmp.PostHogConfig, and com.posthog.kmp.PostHogContext

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[question] KMP has no @v1 rules either, and the base KMP rule still says to check the latest posthog-kmp on Maven Central, which goes against the "don't look up the latest" approach elsewhere in this PR. Should it stay on the installed version too?

@eli-r-ph

eli-r-ph commented Nov 8, 2026

Copy link
Copy Markdown
Author

👋 noting for posterity: wizard team decided to implement version-aware context another way after these were drafted. this and the corresponding wizard repo series won't be shipping; I was asked to leave them open as a reference for wizard team, they will close them out when their implementation is done 👍

@edwinyjlim

Copy link
Copy Markdown
Member

Closing this stack. The design comes back after the agent DAG refactor, where the wizard picks each SDK's major, and the skills written for it, from project traits and context-mill tags. The branch stays.

@edwinyjlim edwinyjlim closed this Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants