open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

chore(voyage): release v5.0.2 — operator-driven annotation HTML (scripts/annotate.mjs)

Browse source 
v5.0.0 added a read-only HTML render. v5.0.1 deleted that and pointed at
/playground document-critique, which pre-generates Claude's suggestions
and asks the operator to approve/reject them. The operator asked for the
opposite — a surface where THEY drive every annotation. v5.0.2 lands it.

scripts/annotate.mjs (~430 lines, zero deps) takes any artifact .md and
writes a self-contained HTML next to it. The HTML renders the document
with line numbers, lets the operator click any line to add their own
note (inline textarea, save with Cmd+Enter or button), keeps a sidebar
of all notes (editable + deletable + persisted in localStorage per
artifact path), and exposes Copy Prompt to gather every note into one
structured prompt. Operator copies, pastes back, Claude revises the .md.

The three producing commands now run annotate.mjs at their last step and
print the file:// link with explicit "Click any line to add YOUR OWN note"
instructions. The v5.0.1 /playground document-critique line is gone.

npm test green: 516 tests, 514 pass, 0 fail, 2 skipped.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-13 14:04:28 +02:00
commit 8ea692bc60
15 changed files with 995 additions and 118 deletions
Download patch file Download diff file Expand all files Collapse all files

52
plugins/voyage/commands/trekbrief.md
View file

@ -483,34 +483,46 @@ If the validator returns errors, report them to the user and offer to
re-enter Phase 4 with the validator's hints in scope. If only warnings,
note them in the final report.
**Report — single block, printed verbatim** (substitute the bracketed
fields, but keep the structure and the `/playground` invocation literal —
operators copy-paste that line directly into Claude). The `/playground`
command points at the official `claude-plugins-official` `playground`
skill, which loads its `document-critique` template, reads the brief,
generates per-line suggestions, and writes a single self-contained HTML
file that opens in the browser. The HTML has the brief on the left
(nicely formatted, line-numbered), suggestion cards on the right
(Approve / Reject / Comment), and a "Copy Prompt" button at the bottom
that gathers everything marked into one prompt. Paste that prompt back
into Claude — Claude then revises `brief.md` freehand from the notes.
**Build the operator-annotation HTML, then print the report.** After the
brief is validated, run `scripts/annotate.mjs` to produce a self-contained
HTML file the operator opens in their browser. The HTML renders the brief
with line numbers, lets the operator click any line to attach their own
note (not Claude-generated suggestions — the operator drives every
annotation), keeps a sidebar of all notes, persists state in localStorage,
and exposes a "Copy Prompt" button that generates a single structured
prompt with every note. The operator copies that prompt and pastes it
back into Claude; Claude revises `brief.md` freehand from the notes.
```bash
ANNOT_HTML=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/annotate.mjs "{PROJECT_DIR}/brief.md" 2>&1)
# stdout is the absolute path to the .html on success.
```
If `annotate.mjs` exits non-zero, surface a one-line warning and continue
— the annotation HTML is a convenience, not a gate. The report below
still mentions the (failed) path so the operator can debug.
Then print this block **verbatim** (substitute `{PROJECT_DIR}` and
`$ANNOT_HTML`):
```
Brief written: {PROJECT_DIR}/brief.md
Brief written: {PROJECT_DIR}/brief.md
Annotation HTML: file://{$ANNOT_HTML}
Review iterations: {1..3}
Final quality: {complete | partial}
Validator: {PASS | warnings(N)}
Final quality: {complete | partial}
Validator: {PASS | warnings(N)}
Research topics identified: {N}
────────────────────────────────────────────────────────────────────
To review and annotate this brief, copy and paste this into Claude:
To review and annotate this brief, open the HTML above in a browser:
/playground build a document-critique playground for {PROJECT_DIR}/brief.md
open file://{$ANNOT_HTML}
That builds a self-contained HTML file with the brief on the left,
per-line approve/reject/comment annotations on the right, and a
"Copy Prompt" button at the bottom. Copy the generated prompt, paste
it back here, and Claude revises brief.md from your notes.
Click any line to add YOUR OWN note. The sidebar collects every note,
the "Copy Prompt" button gathers them into one structured prompt.
Paste that prompt back into this chat and Claude revises brief.md
from your notes. Annotations persist in your browser if you close
the tab and reopen the same file.
────────────────────────────────────────────────────────────────────
```