diff --git a/context/agents/integration-v2/dashboard.md b/context/agents/integration-v2/dashboard.md index 57c3d332..d09aef80 100644 --- a/context/agents/integration-v2/dashboard.md +++ b/context/agents/integration-v2/dashboard.md @@ -7,7 +7,7 @@ effort_pi: low model_sdk: claude-sonnet-4-6 effort_sdk: high skills: [integration-v2-dashboard, integration-v2-insight, integration-v2-mcp] -allowedTools: [Read, Glob, Grep] +allowedTools: [Read] disallowedTools: [Write, Edit, Bash, enqueue_task] dependsOn: [build] --- @@ -17,6 +17,13 @@ dependsOn: [build] Create a starter PostHog dashboard with a few insights built on the events this integration instruments, using the PostHog MCP. +Read `.posthog-wizard-cache/.posthog-events.json`, relative to the project root. That +is the event plan — every event this run instrumented, already decided and recorded. +It and the handoffs you were given are your only sources. Open nothing else: not the +project's source, not its config. Re-deriving events from code wastes the run and +risks tiles built on events that were never shipped. The cache folder is deleted when +the run ends, so read what you need in one pass and carry it in your handoff. + ## How you know you succeeded A dashboard exists with a handful of insights on the captured events, and you hand diff --git a/context/agents/integration-v2/integrate-posthog.md b/context/agents/integration-v2/integrate-posthog.md index 7fc3621c..2a463eb3 100644 --- a/context/agents/integration-v2/integrate-posthog.md +++ b/context/agents/integration-v2/integrate-posthog.md @@ -14,7 +14,31 @@ dependsOn: [] ## Goal -Plan a PostHog integration and seed the task queue with this graph: +Plan a PostHog integration and seed the task queue. First decide which of two shapes +this project needs. + +**Is the integration shape already settled by the framework?** It is when the reference +example is close to the answer for this project: the framework prescribes where the SDK +initializes, the app has a single deployable surface rather than a separate frontend and +backend, its authentication is the framework's own or it has none, and it has not +invented configuration of its own — no content-security policy it builds itself, no +asset pipeline it serves by hand. A content site, a CMS theme, a starter, a stock +single-framework app: the work is to follow a known shape, not to find one. + +When all of that holds, seed the short graph: + +- `integrate` — the whole integration in one pass. +- `review`, after `integrate`, parallel to `dashboard`. +- `dashboard`, after `integrate`. +- `report`, after `dashboard` and `review`. + +Otherwise — a split frontend and backend, authentication the project wrote itself, +identity that crosses layers, a content-security policy or asset pipeline of its own, or +a framework you cannot match to an example — seed the full graph below. Prefer the full +graph whenever you are unsure: it is slower, while the short graph on a project that +needed the long one leaves the integration half-made. + +The full graph: - `install` and `init`, independent of each other. - `identify` and `error-tracking`, each after `install` and `init` and independent diff --git a/context/agents/integration-v2/integrate.md b/context/agents/integration-v2/integrate.md new file mode 100644 index 00000000..66d89a86 --- /dev/null +++ b/context/agents/integration-v2/integrate.md @@ -0,0 +1,54 @@ +--- +type: integrate +flow: integration-v2 +label: Integrate PostHog +model_pi: openai/gpt-5.6-terra +effort_pi: medium +model_sdk: claude-sonnet-4-6 +effort_sdk: high +skills: [integration-v2-install, integration-v2-init, integration-v2-identify, integration-v2-error-tracking-step, integration-v2-capture, posthog-best-practices] +allowedTools: [Read, Write, Edit, Glob, Grep] +disallowedTools: [enqueue_task] +dependsOn: [] +--- + +## Goal + +Integrate PostHog into this project in one pass: declare the SDK, initialize it, +identify users, make uncaught errors reach PostHog, and instrument the events worth +capturing. You are used when the project's integration shape is already settled by its +framework — the reference example is close to the answer, and there is no split +frontend and backend, no hand-rolled auth, and no configuration the app invented for +itself. Follow the example's shape adapted to this codebase rather than surveying the +project for a design. + +Work in this order, because each step constrains the next: + +1. Declare the SDK in the project's manifest, at a version range that resolves to a + current release. +2. Initialize it once at the entry point the framework prescribes, reading keys from + the environment, and document those variable names where the project documents its + configuration. +3. Establish identity at the boundary the SDK gives you — the app's own stable + identifier for the user, never an email or name unless the app has nothing else. +4. Make the errors the app does not catch reach PostHog by whatever means the SDK + offers for this framework. +5. Instrument the actions a product team would ask about — the handful of things users + do that a funnel or a trend would be built from. Prefer the actions that already + have a handler over inventing new seams to capture from. + +Record what you instrumented in `.posthog-wizard-cache/.posthog-events.json`, relative +to the project root, in the shape the capture skill describes. Later steps build the +dashboard and the report from that file alone and never re-read your code, so an event +missing from it may as well not exist. + +## How you know you succeeded + +The SDK is declared, initialized once at the framework's entry point, and reads its +configuration from the environment without breaking the app when that configuration is +absent. A known user's activity is attributable to them by a stable id. Uncaught errors +reach PostHog. The events you instrumented are real product actions, they carry the +properties needed to segment them, and every one of them is written to the event plan. +Your handoff names each file you changed, what you did there, and which insight or +funnel the change feeds — a reviewer reads only your handoff and the diff, so anything +you leave out is invisible to them. diff --git a/context/agents/integration-v2/report.md b/context/agents/integration-v2/report.md index 66c3b9a3..c33d7cfd 100644 --- a/context/agents/integration-v2/report.md +++ b/context/agents/integration-v2/report.md @@ -7,7 +7,7 @@ effort_pi: low model_sdk: claude-sonnet-4-6 effort_sdk: high skills: [integration-v2-report, integration-v2-notebook, integration-v2-mcp] -allowedTools: [Read, Write, Glob, Grep] +allowedTools: [Read, Write] disallowedTools: [enqueue_task] dependsOn: [dashboard, review] --- @@ -33,6 +33,12 @@ costs if left alone. A `DISTINCT_ID` placeholder left at a call site means no st was available: name every file and line carrying one, so the user knows what to replace before those events mean anything. +Length follows the work. A small integration on a familiar framework earns a short +report — what was installed, what is captured, what the user must set before it works. +Reserve the long form for runs that actually accumulated nuance: conflicts, skipped +steps, unresolved follow-ups, placeholders. Padding a simple run into a long report +costs the user time twice, once waiting for it and once reading it. + ## How you know you succeeded `posthog-setup-report.md` exists at the project root: what was installed and diff --git a/context/agents/integration-v2/review.md b/context/agents/integration-v2/review.md index 1db31df4..4eca1697 100644 --- a/context/agents/integration-v2/review.md +++ b/context/agents/integration-v2/review.md @@ -15,10 +15,10 @@ dependsOn: [build] ## Goal Review every change this run made, as a strict reviewer who did none of the work, -and fix what fails. The project had no PostHog before this run, so find the full -changeset yourself: grep for posthog (all cases) across source and config, read -each file you find, and read the handoffs for anything the grep cannot see (env -files, manifest edits). +and fix what fails. Start from the handoffs: every step reports the files it edited +and why, so that list is your changeset. Read those files first. Then grep for +posthog (all cases) across source and config to catch anything the handoffs missed +— that grep is a safety net, not your primary search. Judge each change against these dimensions, in order: @@ -44,8 +44,9 @@ kill bad changes; never alter the what. Only flag what you can pin to a specific line and dimension — no taste-based rewrites, and never expand the integration. Fix findings by editing in place. For each fix, ask what would behave differently if your fix were wrong, and check by -reading the callers — not by trusting your edit. If you changed anything, re-run -the project's lint or build the way the build step did, when one exists. +reading the callers — not by trusting your edit. The build step already ran the +project's lint and build and reported the result in its handoff; take that as given. +Re-run them only if you edited code, and only the ones your edit could break. ## How you know you succeeded