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

82
plugins/voyage/README.md
View file

@ -1,6 +1,6 @@
# trekplan — Brief, Research, Plan, Execute, Review, Continue
![Version](https://img.shields.io/badge/version-5.0.1-blue)
![Version](https://img.shields.io/badge/version-5.0.2-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple)
@ -19,7 +19,7 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep
| **`/trekreview`** | Review — independent post-hoc review of delivered code against the brief, severity-tagged findings |
| **`/trekcontinue`** | Continue — read `.session-state.local.json` and resume the next session in a multi-session project |
`/trekbrief`, `/trekplan`, and `/trekreview` each end by printing a single copy-paste-ready `/playground build a document-critique playground for <artifact_path>` command. Paste it into Claude, the official `playground` skill builds a browser-readable HTML with per-line Approve/Reject/Comment annotations, copy the generated prompt, paste back — Claude revises the artifact. See [Reviewing and annotating artifacts](#reviewing-and-annotating-artifacts-v501).
`/trekbrief`, `/trekplan`, and `/trekreview` each end by running `scripts/annotate.mjs` against the just-written artifact and printing the resulting `file://<abs path>` link. The operator opens the HTML in a browser, clicks any line of the document, writes their own note in the inline textarea, watches a sidebar of all notes (editable, deletable, persisted in browser `localStorage`), and clicks "Copy Prompt" to get one structured prompt that they paste back into Claude — Claude then revises the `.md` from the notes. **The operator drives every annotation.** See [Reviewing and annotating artifacts](#reviewing-and-annotating-artifacts-v502).
Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, `progress.json`, and `review.md`.
@ -503,55 +503,65 @@ Both arguments are required. No interactive prompt — headless-safe.
---
## Reviewing and annotating artifacts (v5.0.1)
## Reviewing and annotating artifacts (v5.0.2)
`/trekbrief`, `/trekplan`, and `/trekreview` each end by printing a single
copy-paste-ready command. After they finish, you see something like:
`/trekbrief`, `/trekplan`, and `/trekreview` each end by running
`scripts/annotate.mjs` against the just-written `.md` and printing the
resulting `file://<abs path>` link. After they finish you see something
like:
```
Brief written: .claude/projects/2026-05-13-foo/brief.md
Annotation HTML: file:///abs/path/.claude/projects/2026-05-13-foo/brief.html
────────────────────────────────────────────────────────────────────
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 .claude/projects/2026-05-13-foo/brief.md
open file:///abs/path/.claude/projects/2026-05-13-foo/brief.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.
────────────────────────────────────────────────────────────────────
```
You copy that one `/playground …` line, paste it into Claude, and the
official `claude-plugins-official` `playground` skill takes over: it loads
its `document-critique` template, reads the `.md`, analyses it, generates
per-line suggestions, and writes a single self-contained HTML file that
opens in your browser. In the browser:
You run `open` (or click the `file://` link in your terminal), the HTML
opens in your default browser. In the browser:
- **Left:** the artifact, nicely formatted, with line numbers and per-line
highlight bars for any line a suggestion targets.
- **Right:** suggestion cards (Approve / Reject / Comment), filterable by
status, with a counter in the header.
- **Bottom:** a live-updated prompt covering everything you approved or
commented on, with a **Copy Prompt** button.
- **Left:** the artifact, rendered with line numbers. Hover any line — the
gutter shows a `+`. Click — an inline textarea appears under that line.
Write your note, hit Save (or `⌘Enter`). The line gets a colored left
border + a number badge showing the annotation count on that line.
- **Right (sidebar):** every annotation you've made, sorted by line. Each
card shows the line reference (click to scroll), the target text
snippet, and your note text. Click the note to edit it, click `✕` to
delete. A **Clear all** button at the top wipes the slate.
- **Bottom:** a structured prompt that updates live with every note. A
**Copy Prompt** button. Click — your clipboard now has the prompt.
- **Persistence:** every annotation is saved to browser `localStorage`
keyed on the artifact's absolute path. Refresh the tab or close the
browser and re-open — your notes are still there.
You mark what you want, click Copy Prompt, paste it back into Claude, and
Claude revises the `.md` artifact freehand from your notes. **One paste
→ playground → mark → copy → paste back.**
You write your notes, click Copy Prompt, paste back into Claude. Claude
revises the `.md` freehand from your notes. **The operator drives every
annotation.** Claude never pre-generates suggestions in this flow.
> **What v5.0.1 changed from v5.0.0.** v5.0.0 had `/trekbrief`, `/trekplan`,
> and `/trekreview` each render their `.md` to a separate read-only `.html`
> view via `scripts/render-artifact.mjs` *and* print a vague "run the
> `/playground` plugin" instruction. In practice the read-only `.html` was
> redundant with what `/playground` produces (which also shows the artifact
> nicely formatted), and the instruction wasn't copy-paste-ready — operators
> had to guess the right invocation. v5.0.1 drops `render-artifact.mjs` and
> its `.html` output, and makes the printed `/playground` invocation
> literal and copy-paste-ready.
> **What v5.0.2 changed from v5.0.1.** v5.0.0 added a read-only HTML
> render that didn't afford annotation. v5.0.1 deleted that and pointed
> operators at `/playground document-critique` — but the `document-critique`
> template pre-generates **Claude's** suggestions and asks the operator to
> approve/reject them. That's "Claude leads, operator reacts" — the
> opposite of what was asked for. v5.0.2 ships `scripts/annotate.mjs`, a
> self-contained zero-dependency operator-annotation HTML generator. The
> operator clicks lines, writes their own notes, copies a structured prompt
> with every note. No Claude-generated suggestions in the loop.
>
> **Still removed from v5.0.0 onward:** the v4.2/v4.3 bespoke playground SPA,
> `/trekrevise`, Handover 8 (annotation → revision), the supporting `lib/`
> modules, and the Playwright e2e suite. See [CHANGELOG.md](CHANGELOG.md)
> § v5.0.0 and § v5.0.1.
> § v5.0.0, § v5.0.1, and § v5.0.2.
---
@ -685,7 +695,7 @@ The `pre-compact-flush.mjs` hook directly fixes the documented P0 in `docs/treke
**Infrastructure-as-code (IaC) gets reduced value.** The exploration agents are designed for application code. Terraform, Helm, Pulumi, CDK projects will get a plan, but agents like `architecture-mapper` and `test-strategist` produce less useful output for IaC. Use trekplan for the structural plan, then supplement IaC-specific steps manually.
**Annotation requires the official `/playground` skill.** Voyage no longer ships an annotation UI of its own. The pasted `/playground build a document-critique playground for …` command depends on the `claude-plugins-official` `playground` skill being installed in the operator's environment. If it isn't, paste the artifact source `.md` into Claude with a "review this" prompt and revise freehand — the same end-result, just without the visual approve/reject/comment surface.
**Annotation HTML requires a desktop browser.** `scripts/annotate.mjs` produces a single self-contained `.html` file you open with `file://` in any modern browser (Chrome / Safari / Firefox / Edge — last two versions). No CDN, no server, no npm runtime deps. State persists in `localStorage` so closing and re-opening the tab keeps your work, but it's local to one browser on one machine — not synced anywhere. If you want to annotate without a browser, paste the `.md` into Claude with "comments inline below" and write notes in chat — same end result, just without the visual surface.
## Installation