open/voyage
1
0
Fork 0
Code Issues Releases 13 Activity

feat(skills): voyage:annotating, the operator-annotation loop as one skill (order B)

Browse source 
The three producing commands name voyage:annotating where they build the page; the description of the page and the freehand revision left them. The skill: the person writes every note, Fix/Change edit only the quoted text, a Question is answered and changes nothing, the approval an edit costs is said before the edit, the page is rebuilt. Research documents on request (decision 62). Red baseline 3 runs per scenario without and with the skill; six eval cases; 11 pins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-10-19 18:36:00 +02:00
commit 843897ae33
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
25 changed files with 550 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

19
commands/trekbrief.md
View file

@ -831,14 +831,11 @@ sub-point) and `BRIEF_SC_BASH_NOT_PINNED` (the brief requires bash 3.2 but a
criterion runs plain `bash`: offer `/bin/bash`).
**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.
brief is validated, run `scripts/annotate.mjs` to build the page where the
operator writes their own notes. The loop that follows is the skill
`voyage:annotating`: call it when the operator pastes the notes back (a
Question is answered, not applied; after Phase 4h, a note on `## Intent` or
`## Goal` makes the approval stale, and that is said before the edit).
```bash
ANNOT_HTML=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/annotate.mjs "{PROJECT_DIR}/brief.md" 2>&1)
@ -867,9 +864,9 @@ To review and annotate this brief, open the HTML above in a browser:
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.
Paste that prompt back into this chat: Claude answers each Question
and revises brief.md from your Fix and Change notes. Annotations
persist in your browser if you close the tab and reopen the same file.
────────────────────────────────────────────────────────────────────
```

20
commands/trekplan.md
View file

@ -1184,15 +1184,11 @@ plan mode's restrictions). Until an operator has run it, both paths stay.
### Build the operator-annotation HTML and print the link
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.
After the plan summary, run `scripts/annotate.mjs` to build the page
where the operator writes their own notes on `plan.md`. The loop that
follows is the skill `voyage:annotating`: call it when the operator pastes
the notes back (a Question is answered, not applied; an approved plan that
changes needs a new approval before `/trekexecute`, said before the edit).
```bash
ANNOT_HTML=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/annotate.mjs "{plan_path}" 2>&1)
@ -1216,9 +1212,9 @@ To review and annotate the plan, open it in a browser:
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.
Paste that prompt back into this chat: Claude answers each Question
and revises plan.md from your Fix and Change notes. Annotations
persist in your browser if you close the tab and reopen the same file.
────────────────────────────────────────────────────────────────────
```

18
commands/trekreview.md
View file

@ -695,13 +695,11 @@ the main workflow, but it is reported, not skipped silently.
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.
`stdout` is the absolute path to the `.html` on success: the page where the
operator writes their own notes on `review.md`. The loop that follows is the
skill `voyage:annotating`: call it when the operator pastes the notes back.
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`)
@ -821,9 +819,9 @@ To review and annotate the review, open it in a browser:
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.
Paste that prompt back into this chat: Claude answers each Question
and revises review.md from your Fix and Change notes. Annotations
persist in your browser if you close the tab and reopen the same file.
────────────────────────────────────────────────────────────────────
You can also: