From 0fdb6773347244bd06f7d125c112d163341505e7 Mon Sep 17 00:00:00 2001 From: Marcus Chandra Date: Mon, 7 Sep 2026 18:41:55 -0700 Subject: [PATCH] deploy-workflow: version documents and cross-workspace promotion semantics Claude-Session: https://claude.ai/code/session_01MYsyypbYR5eT4rxM2vaeEF --- skills/deploy-workflow/SKILL.md | 37 +++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/skills/deploy-workflow/SKILL.md b/skills/deploy-workflow/SKILL.md index d499b1b..c18ba4d 100644 --- a/skills/deploy-workflow/SKILL.md +++ b/skills/deploy-workflow/SKILL.md @@ -17,6 +17,18 @@ post-deployment state. access configuration. - Never create, rotate, or reveal an API key unless the user separately asked for key management. +## What a stored version is not + +A stored workflow version nulls out `credential`, `oauthCredential`, resource selectors, and +related binding fields. Two consequences: + +- A diff against a version document is not a change report. Blocks whose only delta is a nulled + field show as changed, and selector changes do not show at all - the diff overstates and + understates simultaneously. Diff live state against live state instead. +- A revert restores the nulled document, stripping every credential and selector in the workflow. + Never present revert as a safe rollback; the reverted draft needs its bindings re-established + before it can run. + ## Choose one surface - **API:** for software calling a workflow as a pipeline. Publish with @@ -42,6 +54,31 @@ Do not choose a surface from convenience. Ask when the intended caller does not - Reuse an existing MCP server when it is the intended tool collection; do not create duplicates by default. +## Promoting across workspaces with fork sync + +When a workflow moves between workspaces via a fork push, the sync has its own semantics; do not +reason about it as a copy. + +- The push creates resources that are missing in the target and rebinds selector-bound references + to them. Do not pre-create tables in the target as a promotion prerequisite - pre-creating + defeats the mapping and leaves references pointing at the source. +- A table the push creates arrives holding the source's rows. Re-seed environment-specific values, + feature flags and configuration especially, immediately after the push, before anything reads + them. Where possible design flag rows so the source's value is also the safe value in every + target. +- Deployment state travels. A workflow deployed in the source is live in the target as soon as the + sync completes, and a schedule trigger starts firing there on its own - there is no separate + deploy step in the target. Before syncing anything scheduled or triggered, state plainly what + will start running where and when. +- Bind every resource through its selector and leave the manual id fields empty. The push remaps + selectors but carries a hardcoded manual id verbatim, silently pointing the promoted workflow at + the source workspace's resource - and a cross-workspace read succeeds, so no error surfaces. +- The push does not preserve a block's basic/advanced mode: some blocks arrive rebound and working, + others arrive carrying the source's manual id and broken, with nothing surfacing which is which. + "Works in the source workspace" is therefore never the completion condition. Verify each target + environment after promotion - run its workflows or audit its bindings - rather than inferring + health from the source. + ## Verify and report After publishing, read the deployment again. Confirm its active status and version and return the