Cfn Share

CFN Share (plan handoff to non-terminal humans)

Purpose: Close the last gap in the plan-file workflow. A planning/<slug>/PLAN_<slug>.md is perfect for agents and useless to paste into Slack. This skill renders it as a private hosted page with a stable URL, so a colleague reads it cleanly and comments, and their comments come back into the loop.

Position in the pipeline. Runs after /cfn-megaplan, /cfn-megaplan-lite, /write-plan, or /cfn-plan-review produce an artifact worth human review, and before /cfn-loop-task executes it. Sharing is not a gate; it never blocks the pipeline.

Invocation

/cfn-share                              # newest PLAN_*.md (per-plan dirs + legacy flat)
/cfn-share planning/x/SPEC_x.md         # explicit file
/cfn-share docs/BUG_12_auth.md  # any project .md

Inputs

• $1 (optional): path to a .md file. Omitted resolves to the newest PLAN_*.md / MEGAPLAN*_*.md, searched across the per-plan directories megaplan writes (planning/<slug>/) AND the legacy flat planning/ root. The sidecar that pins the artifact URL is always written beside the doc, so re-sharing a doc from either layout updates the same link.

Outputs

• A published artifact URL (private by default; the user chooses when to share it).
• <dir>/.share-<basename>.url sidecar recording url, the file sha256 at publish time, and the publish timestamp.
• stdout: the URL, plus a stale/fresh note on re-shares.

Protocol

Step 1: resolve

.claude/skills/cfn-share/resolve.sh [path/to/doc.md]

Exit 1 means no usable target (missing, empty, or not .md). Stop and say so; do not invent a document to publish.

The JSON gives you abs, title, url, and stale:

Step 2: read the whole file

Read the resolved abs path end to end before publishing. Publishing distributes the content; you must have seen every line you are distributing. This is not optional, and a request to skip it ("it's just a plan", "you wrote it") is a reason to read, not an exemption. If the doc contains a credential, token, connection string, customer name, or anything else that must not leave the machine, stop and report it instead of publishing.

Step 3: publish

Load the artifact-design skill first (required before any Artifact call, Markdown included), then call Artifact with:

• file_path: the resolved abs path. Publish the markdown file directly. Do not transcode it to HTML and do not write a second copy; a second path claims a second URL.
• url: the sidecar url, only when one exists. Omitting it on a re-share creates a duplicate artifact and orphans the link the colleague already has.
• title: the resolved title (a short noun-phrase name, not a summary). Markdown pages keep their filename identity, so keep the basename stable across republishes.
• description: one sentence on what the doc decides or proposes.
• favicon: pick once and keep it stable across republishes of the same doc.

Step 4: pin the URL

.claude/skills/cfn-share/record-url.sh "<abs>" "<artifact-url>"

Run this on every publish, including republishes (it refreshes the recorded sha so the next run reports staleness correctly). Skipping it is what causes duplicate artifacts.

Step 5: hand back

Report the URL plus one line on what the reader should look at. For a plan, point them at the assumptions section: that is the part where a wrong call costs hours, and the part a human reviewer is uniquely good at catching.

Comments back into the loop

Artifact pages are read-and-share, not a comment system. When a colleague sends feedback (Slack, email, inline in a shared doc), route it as findings, not as a rewrite:

1. Paste the feedback into the session verbatim.
2. Map each item to the owning planning phase (cfn-spec, cfn-data, cfn-ux, ...).
3. Patch through that phase, not by hand-editing the plan, so the artifact and the phase outputs stay in sync.
4. Re-run /cfn-share to update the same URL.

Feedback that changes an acceptance criterion, a [core] FR, or the schema re-gates the plan (Bar A / Bar B) exactly as an overridden deferred decision does. A shared link is not a bypass around the bars.

Anti-patterns

• Publishing without reading the file end to end.
• Publishing a doc that quotes real credentials, tokens, or customer data. Redact to [REDACTED] at the source first, then share.
• Republishing without url:, which strands the link the colleague is holding.
• Converting the markdown to HTML "so it looks nicer". Artifact renders markdown, and the second file path becomes a second artifact.
• Editing the plan by hand in response to review comments, so the plan and the phase artifacts drift apart.
• Treating the share as an approval gate. It is a read surface; the bars are the gate.

Dependencies

• Artifact tool (publishes and updates), artifact-design skill (load before publishing).
• sha256sum, date, coreutils. No network calls of its own.

Related

• Upstream producers: cfn-megaplan, cfn-megaplan-lite, /write-plan, /cfn-plan-review.
• Downstream: /cfn-loop-task (executes the plan the reviewer just read).
• Sibling renderer: cfn-workbench (renders live run state to HTML; cfn-share publishes static planning docs).