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.
────────────────────────────────────────────────────────────────────
```

49
plugins/voyage/commands/trekplan.md
View file

@ -769,30 +769,43 @@ If the user asks questions or requests changes:
- Show what changed
- Re-present the summary
### Print the annotation invocation
### Build the operator-annotation HTML and print the link
After the plan summary, print this block **verbatim** (substituting only
`{plan_path}` with the absolute path). The `/playground` command must
appear literally — operators copy-paste it directly into Claude. It
points at the official `claude-plugins-official` `playground` skill,
which loads its `document-critique` template, reads `plan.md`, generates
per-line suggestions, and writes a single self-contained HTML file that
opens in the browser. The HTML has the plan 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 `plan.md` freehand from the notes.
After the plan summary, run `scripts/annotate.mjs` to produce a
self-contained HTML the operator opens in their browser. The HTML renders
`plan.md` 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 `plan.md` freehand from the
notes.
```bash
ANNOT_HTML=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/annotate.mjs "{plan_path}" 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.
Then print this block **verbatim** (substituting `{plan_path}` and
`$ANNOT_HTML`):
```
────────────────────────────────────────────────────────────────────
To review and annotate this plan, copy and paste this into Claude:
Plan written: {plan_path}
Annotation HTML: file://{$ANNOT_HTML}
/playground build a document-critique playground for {plan_path}
To review and annotate the plan, open it in a browser:
That builds a self-contained HTML file with the plan 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 plan.md from your notes.
open file://{$ANNOT_HTML}
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 plan.md
from your notes. Annotations persist in your browser if you close
the tab and reopen the same file.
────────────────────────────────────────────────────────────────────
```

28
plugins/voyage/commands/trekreview.md
View file

@ -262,6 +262,20 @@ Append a stats line to `${CLAUDE_PLUGIN_DATA}/trekreview-stats.jsonl`
If `${CLAUDE_PLUGIN_DATA}` is unset or not writable, skip stats silently.
Never let stats failures block the main workflow.
**Build the operator-annotation HTML.** After stats land, run:
```bash
ANNOT_HTML=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/annotate.mjs "{review_path}" 2>&1)
```
`stdout` is the absolute path to the `.html` on success. The HTML renders
`review.md` 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. If `annotate.mjs`
exits non-zero, surface a one-line warning and continue — the annotation
HTML is a convenience, not a gate.
## Phase 8.5 — Validate-only mode (`--validate`)
When `mode == validate`:
@ -282,6 +296,7 @@ After the write succeeds, print:
**Brief:** {brief_path}
**Project:** {project_dir}
**Review:** {review_path}
**Annotation HTML:** file://{$ANNOT_HTML}
**Scope:** {before_sha}..{after_sha} ({reviewed_files_count} files)
**Verdict:** {BLOCK | WARN | ALLOW}
@ -297,14 +312,15 @@ After the write succeeds, print:
{up to 5 highest-severity findings}
────────────────────────────────────────────────────────────────────
To review and annotate this review, copy and paste this into Claude:
To review and annotate the review, open it in a browser:
/playground build a document-critique playground for {review_path}
open file://{$ANNOT_HTML}
That builds a self-contained HTML file with the review 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 review.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 review.md
from your notes. Annotations persist in your browser if you close
the tab and reopen the same file.
────────────────────────────────────────────────────────────────────
You can also: