SuperAPI AI Directory

draft-hold

General & other

View repository

Updated 10-16 08:48

About this skill

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

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:

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

draft-hold.sh is a thin shim that execs the Bun/TypeScript engine scripts/draft-hold.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" "$DH" 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 — "$DH" 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:

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

    Use --body-only to get exactly the text to send/paste — it strips the title heading and everything from the ------ provenance separator onward. Show the operator the exact current text, get explicit go-ahead, then send/commit.

  4. "$DH" list enumerates held 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&quot; $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 &amp; 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 (about → 关于; 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 …(2026-07-20…), so an exact whose name is <title> lookup MISSES long-titled notes. The engine handles this: new reads its note back by id (not title) for the verify, and get/sticky/move-note resolve a title to a note truncation-tolerantly via noteNameMatchesTitle() (exact, else the stored name is the title truncated with a trailing …). Never rely on exact-name AppleScript matching for a possibly-long title.
  • Links: the SETTER keeps them, the GETTER strips them (verified 2026-08-05). Write [label](url) and the engine emits <a href>; Notes stores a genuine link attribute (confirmed by decompressing the note's ZICNOTEDATA.ZDATA protobuf in NoteStore.sqlite — the href sits in the attribute run while the visible-text run holds only the label). But AppleScript's body getter returns <u>label</u> with no href, for links Notes itself made too. Consequences: (1) get/get --body-only shows link TEXT and silently loses the URL — never round-trip a linked note through get and re-new it, the links will be gone; (2) read-back verify is link-blind by construction, so renderInline's unit tests are the only place an href is observable — do not "harden" verify by asserting hrefs, they never appear. Only http(s) and mailto become anchors; any other scheme (javascript:, file:, a bare path) renders as literal text.
  • Proportional prose, monospace only in fences: prose paragraphs render in Notes' normal proportional font (so a long line reflows). Only ``` fenced blocks are wrapped in <tt> (Notes' "Monostyled" face) with spaces held as &nbsp;. The mono face is fixed by Notes — it is not the global NSFixedPitchFont, which governs TextEdit-style apps, not Notes.

Getting the session UUID for provenance

The Bash tool already has it: Claude Code exports CLAUDE_CODE_SESSION_ID (verified 2026-08-05 — matches the ~/.claude/projects/<slug>/<uuid>.jsonl name). So just forward it, and don't go hunting:

CLAUDE_SESSION_ID="$CLAUDE_CODE_SESSION_ID" "$DH" new "<title>" …

Only if that variable is empty: the statusline-tools:session-info skill reports the UUID, or read the newest *.jsonl under ~/.claude/projects/<project-slug>/. If genuinely unavailable, omit it (the footer drops the token — never write a placeholder).

Rules

  • Never send/commit from memory — always get the note first; the operator may have changed it.
  • Notes is the source of truth. Stickies cannot be read back (no AppleScript dictionary), so never treat a sticky as the live draft.
  • There is no scriptable deep-link to a specific note (open x-coredata://… fails; applenotes: links are UI-only) — reference drafts by folder + title.
  • First run prompts once for Automation permission to control Notes.

Evolution log

  • 2026-08-05 (b) — the skill could not find its own entrypoint (exit 127). Trigger: /notes-commander:draft-hold invoked from another repo died on (eval):1: no such file or directory: /skills/draft-hold/draft-hold.sh. Root cause: this SKILL.md told the caller to use DH="$CLAUDE_PLUGIN_ROOT/skills/draft-hold/draft-hold.sh", but CLAUDE_PLUGIN_ROOT is not a shell variable. Claude Code substitutes the exact literal ${CLAUDE_PLUGIN_ROOT} (braces REQUIRED — the helper is e.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginPath)) inside plugin manifests, and injects the var into hook/MCP subprocess envs — never into the Bash tool. The bare $… spelling used here is unsubstitutable on every path, so it reached zsh as an unset var, expanded to empty, and produced an absolute-looking /skills/… path — which reads like a missing file, not a missing variable. Two upstream causes made it likely: the repo's own advanced-topics.md and lifecycle-reference.md documented the rule exactly backwards ("available in skill loading, NOT in hooks" — it is the reverse), and the recovery path was equally unsound: globbing the version cache and taking the highest semver picked 23.4.1, which is marked .orphaned_at (live was 23.5.0). Fix: added scripts/cc-plugin-root (reads ~/.claude/plugins/installed_plugins.json, tolerates both registry schemas, jq with a python3 fallback, symlinked into ~/.local/bin/); this SKILL.md now resolves DH="$(cc-plugin-root notes-commander)/skills/draft-hold/draft-hold.sh"; both reference docs corrected; the stale "L3 cache strips scripts/" claim retired. Also stopped the sibling waste in this same flow: CLAUDE_CODE_SESSION_ID is already exported into the Bash env, so the provenance UUID no longer needs hunting. Evidence: resolver returns the live 23.5.0 path via both jq and python3 backends and under both registry shapes; negative cases exit 1/2 with actionable stderr; the resolved draft-hold.sh and scripts/draft-hold.ts both exist.
  • 2026-08-05 (a) — every URL had to be shown naked, because the formatter escaped anchors. Trigger: staging a weekly report whose 16 PR references made the prose unreadable; the operator asked for #470-style link text and supplied a screenshot of a working link in Notes, proving Notes supports them. Root cause: escapeHtml() was applied to every prose and list line, so an <a href> could only ever render as literal &lt;a href…. The trap that nearly ended the investigation: a probe note written with <a href> read back as <u>#470</u>, which looks exactly like "Notes stripped the link" — I nearly concluded the setter was broken. The operator's OWN hand-made link read back as <u>link text</u> too, which is what exposed the real shape: the getter is lossy, not the setter. Confirmed by decompressing ZICNOTEDATA.ZDATA from NoteStore.sqlite — the probe note's visible text was See #470 and #472. while the hrefs sat in the attribute run. A read-back-only check would have produced a false negative and no links. Fix: added pure, unit-tested renderInline() promoting [label](url) → <a href> at the three prose/list call sites (fences stay verbatim, so a fenced [x](url) renders literally); http(s)/mailto allow-list so a javascript: link can never be minted into a document a human will click. Evidence: 6 new unit tests (39 pass, 0 fail), plus a live round-trip verified against the SQLite protobuf — 16 hrefs stored, zero URLs leaked into visible prose.
  • 2026-07-27 — a lead-in line silently ate the list under it. Trigger: staging a real reply draft, 解决办法有两个,你倾向哪个? immediately followed by two - bullets (no blank line) came back from get --body-only as ONE run-on line, bullets and all. Hit twice in the same session, in two different notes. Root cause: renderTextBlock() classified each blank-line-delimited paragraph by testing p[0] only — so a paragraph whose first line is prose was rendered wholly as prose, and reflowJoin() folded the following -/1. markers into it. The list was destroyed with no error. This contradicted SKILL.md, which promised list markers "each stay on their own line", and left an undocumented "you must leave a blank line before a list" rule that authors could only learn by being bitten. Fix: split each paragraph at the FIRST line matching LIST_RE — lead-in lines reflow as prose, everything from the first marker on renders per-item via the new extracted renderListItems() helper (also removes the duplicated item-grouping loop). All three shapes now work: all-prose, all-list, and lead-in-then-list. Evidence: 3 new unit tests (CJK lead-in + bullets, English lead-in + numbered list, multi-line lead-in that must still reflow before splitting); 33 pass, 0 fail.
  • 2026-07-20 (b) — unified the truncation-match rule into one home (DRY). The 2026-07-20 (a) fix left the exact-then-truncated matching rule in TWO places: noteNameMatchesTitle() in notes-core.ts (used by draft-hold) AND a hand-copied AppleScript scan inside notes.ts OSA_MOVE, guarded only by a "keep the two rules in step" comment. Fix: added pure matchNoteIds(index, title) to notes-core.ts (exact ids first, else truncation-tolerant; returns every match so callers can flag ambiguity). move-note now indexes the source folder (OSA_NOTE_INDEX_BY_PATH), resolves the title in TS via matchNoteIds, and moves by id (OSA_MOVE_BY_ID); the name-matching AppleScript is deleted. draft-hold's own resolver + dedup route through matchNoteIds too. One rule, unit-tested (5 new tests, 30 total), impossible to drift. Invariant recorded in the plugin CLAUDE.md (the matchNoteIds entry).
  • 2026-07-20 (a) — long titles broke read-back verify + move-note (name truncation). Trigger: parking a 66-char draft ("CPC Scanners — Procurement Intelligence & Deliverables (2026-07-20)") returned a false ✗ CONTENT-MISMATCH, and move-note "<that title>" then failed with "note not found in source folder", even though the note existed and its body was correct. Root cause: macOS Notes stores a long first-line name TRUNCATED with a trailing …, so new's read-back (body of note <title> of folder) and move-note's whose name is <title> both looked up a name that no longer equalled the title. Fix: added the pure, unit-tested noteNameMatchesTitle() + NOTES_NAME_ELLIPSIS to notes-core.ts (exact, else truncated-prefix match); new now verifies by id (OSA_GET_BY_ID) and dedups older copies via a JS-side folder index; get/sticky resolve title→id truncation-tolerantly; move-note (notes.ts) falls back to a truncated-prefix scan that captures matches by id (a live notes of src reference held past the loop throws -1728). Evidence: a 125-char-title probe now creates (clean id, no CONTENT-MISMATCH), gets its body, and move-notes across folders — all green; 5 new unit tests (25 pass total). Verified live on macOS Notes.
  • 2026-07-18 (b) — migrated into notes-commander + hardened. The standalone draft-hold plugin was folded into the new notes-commander plugin as one of its skills; formatting + process wrappers moved to the shared scripts/lib/notes-core.ts engine. Added, per a web-researched audit of recent macOS AppleScript failure modes: silent-no-op detection (isNoteId on create — osascript can exit 0 yet create nothing on macOS 26), bounded retry on transient AppleEvent errors (-600/-1712), and a default-on read-back verify (entityLeaks + contentPresent). All pure helpers unit-tested (16 tests in notes-core.test.ts).
  • 2026-07-18 (a) — hard-wrapped prose became forced mid-sentence breaks. A long bilingual briefing was passed with each paragraph pre-wrapped at ~100 chars; because the old bash new made each input line its own Notes paragraph (all wrapped in <tt>), the reader saw mid-sentence line breaks that did not reflow. First fix (insufficient): a "one line per paragraph" caller contract — but that only works if every caller remembers it. Real fix: reimplemented the engine as Bun/TypeScript, enforcing the formatting in code so the failure is impossible: prose blocks REFLOW (consecutive lines join; blank line = paragraph), list markers stay per-item, and only ``` fenced blocks are preserved verbatim/monospace (spaces held as &nbsp;). Verified by unit tests + a live Notes round-trip.

Post-Execution Reflection

After holding or sending a draft, check before closing:

  1. Did read-back match what Notes shows? — if entities/quotes leaked (e.g. &quot), the decode path drifted; the verify step should have caught it — fix the textutil step in notes-core.ts, never hand-roll sed.
  2. Did get/list find the note by title? — if not, the name==title assumption broke; fix the title-prepend in new.
  3. Did Notes/Stickies change behavior? — update the macOS-quirks section so the next run doesn't rediscover it.

Only update if the issue is real and reproducible — not speculative.