draft-park

name	draft-park
description	Park a draft message/text in macOS Notes for the operator to review and edit, then read it back before acting (e.g. before sending to a real person). Notes is the source of truth (AppleScript CRUD, iCloud-synced, provenance-stamped with the Claude Code session UUID); Stickies is a best-effort view-only desktop mirror. Use whenever you draft something a human should confirm/edit before it is sent or committed — messages, replies, announcements, anything outbound. TRIGGERS - park this draft, park the message, hold this draft, let me edit first, draft for my approval, save to notes for review, read back the draft.
allowed-tools	Bash, Read

draft-park — human-in-the-loop drafts via macOS Notes

Renamed from draft-hold on 2026-08-12. Invoke as /notes-commander:draft-park; there is no draft-hold alias. Evolution-log entries dated before the rename keep the old name — that is the accurate historical record, not drift.

Self-Evolving skill — if macOS Notes/Stickies behavior drifts from what's below, fix this SKILL.md and the shared engine scripts/lib/notes-core.ts (+ a case in notes-core.test.ts); see the Post-Execution Reflection at the bottom.

When you compose something a human should confirm or edit before it goes out (a message to a real person, an announcement, a commit body), don't keep it only in chat — park it in macOS Notes so the operator can edit it on any device, then read it back and act on the edited version.

Resolve the entrypoint first — $CLAUDE_PLUGIN_ROOT is NOT a shell variable and expands to empty here (it exists only inside plugin manifests and hook/MCP subprocesses; see the $CLAUDE_PLUGIN_ROOT invariant in the plugin CLAUDE.md). Never glob the version cache either — it retains orphaned versions. Use the resolver:

DP="$(cc-plugin-root notes-commander)/skills/draft-park/draft-park.sh"

draft-park.sh is a thin shim that execs the Bun/TypeScript engine scripts/draft-park.ts, built on the plugin's shared notes-core engine (which also powers notes-inventory/notes-export/notes-organize).

Formatting is handled in code — just write naturally

The engine (formatter in scripts/lib/notes-core.ts, unit-tested in notes-core.test.ts) normalizes your input into Notes HTML, so you never hand-manage line breaks:

• Prose reflows. Consecutive non-blank lines join into ONE paragraph that Notes soft-wraps to the reader's screen. Accidental hard-wrapping (text pre-wrapped at ~80/100 cols) is corrected automatically — it can no longer become a permanent mid-sentence break. Blank lines are the only breaks that matter.
• A blank line = a new paragraph/section. That is the one authored break.
• List items — lines beginning with -, *, +, •, 1., 2), a. etc. each stay on their own line; a wrapped continuation line (indented, no marker) joins back to its item.
• Verbatim / columnar / code blocks — wrap them in a ``` fence. Every line inside is preserved exactly and rendered monospace with spaces held (via  ), so columns and IDs line up in the Notes UI. (Note: get --body-only returns the sendable plain text and collapses inter-column runs to single spaces; if exact alignment must survive to the recipient, send an attachment/screenshot.)

Hardening (verified failure modes this engine guards)

• Silent-failure detection — new asserts Notes returned a real note id (x-coredata://…); on recent macOS, osascript can exit 0 yet create nothing. If that happens you get a loud ✗ SILENT-FAILURE instead of a phantom "success".
• Bounded retry — transient AppleEvent errors (-600/-1712/"not running") retry with backoff; permission/syntax errors fail fast.
• Read-back verify (default ON) — after new, the note is read back and checked for entity leaks and content presence. --no-verify skips (rarely needed).

Workflow

1. Park the draft (body on STDIN):

   CLAUDE_SESSION_ID="$CLAUDE_CODE_SESSION_ID" "$DP" new "<title>" --project "<repo-or-context>" <<'EOF'
   Hi <name> — <your drafted message>...
   EOF
   

   Creates/replaces a note in the "Claude Drafts" folder with a provenance footer (session UUID + project + timestamp). Tell the operator: "Draft is in Notes → Claude Drafts → ; edit it there, then tell me to send."

2. (Optional) desktop mirror — "$DP" sticky "<title>" pops a view-only Stickies note (needs Accessibility permission). Notes stays authoritative.

3. Read it back before acting — ALWAYS re-read, since the operator may have edited it:

   "$DP" get "<title>"              # full note (heading + message + provenance footer)
   "$DP" get "<title>" --body-only  # JUST the sendable message (no heading, no footer)
   

   Use --body-only to get exactly the text to send/paste. Add --for whatsapp to convert markdown into the channel's own syntax, and --copy to put the result straight on the clipboard so there is no hand-selection step to get wrong:

   "$DP" get "<title>" --for whatsapp --copy   # sendable text → clipboard, warnings on stderr
   

   --for and --copy both imply --body-only. stdout is always exactly the sendable bytes; warnings go to stderr, so piping stays clean. Show the operator the exact current text, get explicit go-ahead, then send/commit.

4. "$DP" list enumerates parked drafts.

macOS quirks this skill handles for you

• Quote serialization: Notes' AppleScript body getter re-emits every " as the semicolon-less legacy entity &quot (verified 2026-06-29). We decode with textutil (a real HTML parser) instead of sed, so &quot/&amp/&lt etc. round-trip back to literal characters. Never hand-roll entity decoding here. The read-back verify now DETECTS a drift here automatically (✗ ENTITY-LEAK). A real HTML parser is not sufficient on its own (fixed 2026-07-20): because the stored form is semicolon-LESS, a note holding Write-Host "x"; $y comes back raw as Write-Host &quotx" $y, and textutil reads the closing &quot plus the author's own ; as one entity — silently eating the semicolon, so it round-tripped as Write-Host "x" $y. That corrupts most staged PowerShell/C/Java/JS with no error, which is fatal for a skill whose job is staging text a human will SEND. terminateLegacyEntities() in notes-core.ts now appends the ; to every bare entity before decoding, so a following literal ; stays literal. This is safe unconditionally because Notes escapes every & it stores (an author's literal & comes back as &ampamp;), so a terminated entity in Notes output can only ever be bare-entity + the author's semicolon.
• UTF-8 decode needs an explicit charset: textutil -format html assumes Latin-1 when the HTML has no charset declaration, mojibaking every non-ASCII character (关于 → 关于; verified 2026-07-02 with a Chinese draft). htmlToText therefore prepends <meta charset="utf-8"> before piping to textutil — keep that prefix.
• Note name = first body line, TRUNCATED: Notes names a note after its first line, ignoring any title you "set". new therefore prepends the title as a bold first line so get/list/replace can find it by title. Pass the message body only on STDIN. But Notes truncates a long first line to a capped name ending in an ellipsis … (verified 2026-07-20: a 66-char title stored as ), so an exact lookup MISSES long-titled notes. The engine handles this: reads its note back (not title) for the verify, and // resolve a title to a note via (exact, else the stored name is the title truncated with a trailing ). Never rely on exact-name AppleScript matching for a possibly-long title.