Spec the Workflows first run and slice it into PRs #255

Activity

1. Silthus

   added

   wayfinder:spec

   on Oct 5, 2026
2. Silthus

   added a parent issue on Oct 5, 2026

   • Map: build the Workflows first run, from template gallery to first send #253
3. Silthus commented on Oct 5, 2026

   

   Silthus

   on Oct 5, 2026

   OwnerAuthor

   More actions

   Runtime: Claude Code background agent (conductor thread on devbox-michaelr-3)
   Worker: spec-255
   Cap: 90 minutes
   Cast: Claude Opus 5.5
4. Silthus

   self-assigned this

   on Oct 5, 2026
5. Silthus commented on Oct 5, 2026

   

   Silthus

   on Oct 5, 2026

   OwnerAuthor

   More actions

   Claimed by conductor worker spec-255 (Claude Code background agent, Opus 5.5).
6. Silthus commented on Oct 5, 2026

   

   Silthus

   on Oct 5, 2026

   OwnerAuthor

   More actions

   Worker transcript: /tmp/claude-1001/-home-coder--t3-worktrees-posthog-t3code-1d6de0ea/6f4018e1-a32c-4b89-bae8-f0ca1d7056a8/tasks/ab21743bbc15f30ef.output. Deadline wake set for 09:43 UTC.
7. Silthus commented on Oct 5, 2026

   

   Silthus

   on Oct 5, 2026

   OwnerAuthor

   More actions

   Resolution

   Spec: #256 Spec: Workflows first run (closed as the reference document, linked under the map).

   /to-spec and /to-tickets cannot be invoked by an agent in this runtime (both are restricted to user invocation). The spec and tickets follow the shape of Spec: sandbox sender and its tickets instead.

   Implementation tickets (all wayfinder:implement, children of #253):

   #	Slice	Cast	Blocked by
   #257	Templates declare what starts them	GPT-6.1 Sol (backend)	none
   #258	Tailored template gallery on the empty Workflows tab (adds the flag)	Opus 5.5 (UI)	#257
   #259	One seam for the first-run sender	Opus 5.5 (UI)	#237
   #260	Make it yours, send me a test, enable	Fable 5.1 (UI)	#258, #259
   #261	Change with PostHog AI edits the email in place	GPT-6.1 Sol	#260
   #262	Draft and sending banners on the first workflow	Opus 5.5 (UI)	#260
   #263	Capture engagement events by default	Opus 5.5 (UI)	#260, #262
   #264	Say who the first sends reach, and the own-domain line	Opus 5.5 (UI)	#254, #262, #238
   #265	Hand missing signups and emails to an agent	Opus 5.5 (UI)	#258
   #266	Quick start follows the first run	Opus 5.5 (UI, two enum values)	#260

   Frontier: #257. Next, #259 as soon as #237 closes; it stacks on #237's PR (PostHog#111695) until that merges.
   After #257: #258, then #265 beside the #260 chain. #261, #262 and #266 run side by side after #260.

   Waiting on #254: only #264. It holds the copy that names who the first sends reach and how loud the own-domain line is. Every other slice behaves the same under all three options on #254, because the sender sits behind the #259 seam. A later shared sender changes that seam only.

   Test seams and why

   1. DRF tests through the hog flow templates list, plus one test over the template files. The template is the one home for what starts it, so the check sits where the data lives.
   2. Kea logic tests with the API mocked at the HTTP layer, for the gallery, Make it yours, the sender seam, the banners, the agent banners and the quick start. Each asserts the request the frontend sends (the create payload, the test invocation, the team update) or the state a user sees.
   3. Storybook stories at full width and 520px for every screen and state.
   4. The backend tool test pattern of the existing MaxTools, with the LLM mocked, for Workflows first run: Change with PostHog AI edits the email in place #261.
      All four exist today with prior art; no new seam.

   Decisions made here, with reasons

   • Who sees the first run: flag on and a project with no workflows, at any organization age. It reuses workflowsSetupLogic. A paying team that never used Workflows is exactly who the first run is for.
   • Who sees Quick start: unchanged, organizations younger than three months until every task is done. That rule is shared by every product's quick start in productSetupLogic; forking it for one product adds a special case for little gain. Under the flag the Workflows task list follows the first run (Workflows first run: quick start follows the first run #266), because today it starts with "Set up your first workflows channel", which sends a new team to DNS first.
   • Flag: workflows-first-run, one flag for every slice.
   • What starts a template lives in the template file (starts_on), not in a frontend table. Several global templates have an empty event trigger and "a stretch without an event" is not a trigger type, so the trigger alone cannot say what starts a template.
   • The first run writes the matched event into the trigger at creation. A template with an empty trigger cannot go live, and a project's own signup event name should drive the welcome sequence without a rename.
   • Fit uses event definitions, one lookup by name. A definition exists only once the event was seen, so no event query runs.
   • Recommended starter: the welcome sequence when ready, else the first ready template, in one selector so a Jev decision (Map: AI decisions in workflows, a decision step backed by Jev #240) can replace it.
   • "Start playing" reuses createEmptyWorkflow, so the AI-first experiment still governs the blank path.
   • No workflow exists until "Enable and open workflow". Creating a draft on pick would make the gallery disappear the moment someone goes back to choose another template.
   • "Send me a test" sends in one click to the signed-in user through the existing test invocation endpoint, and shows any skip reason. The prototype's simulated inbox is dropped: a real inbox is the point.
   • The sender is one seam (Workflows first run: one seam for the first-run sender #259): own verified sender first, then the sandbox sender, then none. Nothing else names a sender, so Shared sender or members-only: who may the first run's first sends reach? #254 changes one selector at most.
   • The first-run workflow is remembered in the browser, not in a database field. The banners guide one person's first session; a marker column would need a migration for a hint.
   • Enable is pointed at with the existing setup highlight, not the prototype's curved arrow.
   • The email check reads the email person property definition, not a person scan. Person data in bulk is off limits, and a yes or no answer is enough here.
   • "Change with PostHog AI" applies changes through a frontend-applied tool. The existing email MCP tools patch saved workflows, and the email on Make it yours is not saved yet.
   • Engagement events stay admin-only, matching the backend gate on workflows_config.
   • Copy does not promise opens and clicks from the sandbox sender. Sandbox sends carry no open or click tracking (Spec: sandbox sender #229), so the engagement switch captures only sent and delivered events for them. This matters for Workflows first run: capture engagement events by default #263 and Workflows first run: say who the first sends reach, and the own-domain line #264.
   • Out of this build: brand detection (Map: detect an Email brand from GitHub and create a branded starter template #198), the prototype's recent-signups line, and an empty state for a Metrics tab with no data yet.

   No other load-bearing one-way decision came up, so nothing new is parked. #254 stays with Michael.
8. Silthus

   closed this as completedon Oct 5, 2026