poc(agents): WIP DONT LOOK short graph for framework-determined projects

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

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

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.

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

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