Skill: pass the template source on MCP uploads #511

Activity

1. Silthus

   added

   wayfinder:implement

   on Oct 17, 2026
2. Silthus

   added a parent issue on Oct 17, 2026

   • Map: send code-managed email templates with one PostHog call #461
3. Silthus

   marked this as blocked on Oct 17, 2026

   • posthog-node: fill the template source repository, path and ref on upload #510
4. Silthus

   self-assigned this

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

   

   Silthus

   on Oct 17, 2026

   OwnerAuthor

   More actions

   Runtime: T3 child task
   Task: node:delegated-task:command%3Amcp%3A1778d880-5a25-404c-80d0-25fc5ccca3b2%3Adelegate-task%3Awf-email-impl-511-1
   Cast: Opus 5.5, high. Cap 150 minutes.
6. Silthus commented on Oct 17, 2026

   

   Silthus

   on Oct 17, 2026

   OwnerAuthor

   More actions

   Resolution

   Shipped: four commits on Silthus:feat/send-transactional-email-skill, the branch of draft PostHog/context-mill#433. The PR stays a draft. Head 8b236c30c6774e3b77163ff626f3c242c041902c. fleet proof gate passes (HEAD reviewed in final read 6).

   • 5127da7 feat(skills): record a template's file on upload and change it in the file
   • 99eaa9a fix(skills): cover undo, early publish and no-repository changes
   • c128595 fix(skills): scope undo to templateFile and order the by-key upload
   • 8b236c3 fix(skills): name a published revert in STEP 8 and split the fallback

   What shipped

   One file changed: context/skills/omnibus/send-transactional-email/description.md.

   • STEP 5, upload. Pass source on every MCP upload:
     • repository: the git remote get-url origin URL as host/owner/name, without the scheme, user name, token or .git ending. There is an SSH example and an HTTPS-with-token example.
     • path: from the repository root (git rev-parse --show-toplevel), with a monorepo example.
     • ref: git rev-parse HEAD.
     • Leave out a field git can't give.
   • SDK note (matches posthog-node: fill the template source repository, path and ref on upload #510). posthog-node fills the same fields on its own uploads with templateFile(), from CI and hosting variables or the git checkout. It always sends a path, which falls back to the app's working directory. A repository or ref it can't find keeps the stored value. I checked this against _write_source in template_uploads.py.
   • New section "Change an email the app already sends".
     • With the repository, edit the file. Never use update, patch or design (403 immutable), and leave the template managed by code.
     • Live timing:
       • With templateFile(), the first send from the changed code uploads it, and a local run publishes it too.
       • Upload early only when the person asks, and warn that every running copy then sends the new version.
       • An undo to published content needs an upload.
       • By key, the deploy step uploads, or the agent uploads after the change.
     • Without the repository, tell the person which file to change. Where the MCP has workflows-request-email-template-change, call it and share the task link. An agent that can edit the file never calls it. This is true before and after Request a change: start a PostHog Code task that opens a PR for a code-managed template #513.
     • A prompt from Edit with your agent names the key, and the file when PostHog knows it. This is true before and after Edit with your agent: copy a prompt for a code-managed template's file #503.
   • STEP 8 (HTTP upload, the revert exception) and the STEP 9 immutable line now point at the new section.

   Proof

   • Evals: the skill has none, and context-mill has no eval harness, so there was nothing to extend.
   • Bundle test and gate: pnpm test passed 220 tests and pnpm build passed at 8b236c3, both through fleet heavy. The bundle test is unchanged. I added no test of the wording.
   • Ranking: the MCP SkillCatalog over the overlaid catalog gives rank 1 for all five trigger prompts at 8b236c3. The output is byte-identical to Agent skill: verify a sender, upload the template from the repo, send by key #476's. The description is unchanged.
   • Local agent sessions: Sonnet 5.5, a clean config, only the skill and a local PostHog MCP. Django ran from spec/code-managed-templates 07d7e0ee544 with the flag forced on. Each run had its own project with a verified sender. The scratch repo was a monorepo with the app in apps/web, and origin was https://x-access-token:ghp_…@github.com/example/acme.git with a fake token. Red runs used the skill at 965a656.

   Scenario	Red (965a656)	Green
   Set up from the repo root	github.com/example/acme, apps/web/emails/welcome.html, HEAD	same
   Agent started in apps/web	same	same
   "Add a line under the greeting"	edits the file, no upload	edits the file, no upload, explains it goes live on the first send after deploy
   "... make it live right away", then "undo that line"	uploads both times, no warning	uploads both times, warns about running copies, explains why the undo needs an upload

   Template API read-back after the green run at c128595 (personal API key):

   GET /api/projects/18/messaging_templates/
   {"key": "welcome", "managed_by": "code", "source_repository": "github.com/example/acme", "source_path": "apps/web/emails/welcome.html", "source_ref": "ad86435b7521cff0dbb52a917644428b79a4cc0e", "content_hash": "v1:cee89c39…"}
   

   • None of the 9 proof projects stores a repository with a token, user name or scheme.
   • No run called an update, patch or design tool.
   • The red did not reproduce. Sonnet 5.5 already passed all three fields and edited the file with the old wording. So this is a proof that the behavior holds, not a red-green test. The new text adds the running-copy warning and the undo rule, which only the green runs showed.
   • Full evidence: ~/.local/state/fleet/proof/PostHog/context-mill/433/c128595…/live-run/.

   Review

   Opus 5.5 at high effort, each round in a fresh subagent, recorded with fleet proof review-start and review-finish.

   • Round 2 (on 5127da7), FAIL: 4 medium and 4 low findings.
     • Fixed in 99eaa9a:
       • an undo never goes live through templateFile();
       • any send from changed code publishes it;
       • the by-key rule disagreed with the "Edit with your agent" prompt;
       • "never call" didn't depend on repository access;
       • the SDK always sends path;
       • sentences were too long.
     • Rejected:
       • ref may name a commit without the file. The spec defines ref as HEAD, and the next SDK or deploy upload corrects it.
       • The description doesn't trigger on change requests. That routing is Agents edit a code-managed template's file when they can, and request a change through PostHog Code when they can't #515's.
   • Final read 4, FAIL: 1 medium (the undo bullet said "sent" where the server checks "published") and 4 lows, all fixed in c128595.
   • Final read 5: PASS. It had 2 lows, fixed in 8b236c3, and one follow-up for Edit with your agent: copy a prompt for a code-managed template's file #503 (see below).
   • Final read 6: PASS, with no findings.

   Calls made

   • 👤 Who edits a code-managed template? The agent with the repository edits the file. "Request a change" is only for agents without it (spec Spec: copy-as-code and open-a-PR for code-managed templates #502, revision 4).
   • 🤖 Does the description widen to change requests? No. Routing a change request belongs to Agents edit a code-managed template's file when they can, and request a change through PostHog Code when they can't #515 (designing-email-templates), and the ranking stays as Agent skill: verify a sender, upload the template from the repo, send by key #476 measured it.
   • 🤖 When does an agent upload a templateFile() change itself? Only when the person asks for it before the deploy, with a warning that every running copy sends it.
   • 🤖 How does an undo go live? Through an upload. A send with an older published hash gets the newer content, and the SDK's automatic upload sets if_not_superseded.
   • 🤖 What does an agent without the repository do before Request a change: start a PostHog Code task that opens a PR for a code-managed template #513? It tells the person which file to change.
   • Proof stack: a new detached worktree at spec/code-managed-templates and a database cloned from a migrated scratch database. Nothing sends, so there was no CDP worker.
   • Docs cache: seeded from docs(workflows): add the transactional email API page PostHog/posthog.com#21306 head c86c7a6, which still answers 404 on posthog.com.

   Follow-ups

   • Edit with your agent: copy a prompt for a code-managed template's file #503's prompt text (spec Spec: copy-as-code and open-a-PR for code-managed templates #502's "About this file" block) disagrees with the skill in two places:
     • "Do not upload the file by hand" means an undo made through that prompt never goes live.
     • By key, the prompt says to upload after the change even when the project's deploy step uploads it.
     • The skill is right in both places, so the prompt should match it.
   • Docs: change a code-managed template with an agent, PostHog Code or PostHog AI, and where source details come from #507 docs: the docs page at c86c7a6 still says source.path defaults to the working directory. It should describe posthog-node: fill the template source repository, path and ref on upload #510's detection.
   • Trigger for change requests: if Agents edit a code-managed template's file when they can, and request a change through PostHog Code when they can't #515 leaves coding agents without a skill for "change the welcome email", add a change trigger to this skill's description and re-run the ranking proof.
   • Carried from Agent skill: verify a sender, upload the template from the repo, send by key #476: name the posthog-node release once feat(node): send transactional email with the flat SDK contract PostHog/posthog-js#5312 ships, and merge only after the docs page is published.
7. Silthus

   closed this as completedon Oct 17, 2026