chore(voyage): release v5.0.1 — drop standalone HTML render; print literal /playground document-critique invocation
The v5.0.0 stop-gap had /trekbrief, /trekplan, and /trekreview each render
a read-only {artifact}.html (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 and the instruction
wasn't copy-paste-ready — the operator had to guess the right invocation.
v5.0.1 deletes scripts/render-artifact.mjs + its test + npm run render,
and makes each producing command end with a single boxed, literal,
copy-paste-ready line:
/playground build a document-critique playground for {artifact_path}
One paste from the operator launches the official playground skill's
document-critique template, which builds an interactive HTML — artifact
on the left, per-line Approve/Reject/Comment cards on the right, Copy
Prompt button at the bottom. Mark suggestions, click Copy Prompt, paste
back, Claude revises the .md. Doc-consistency test pins the literal
invocation so the prose cannot soften back into vagueness.
npm test green: 503 tests, 501 pass, 0 fail, 2 skipped.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
916d30f63e
commit
2e0892cdaf
15 changed files with 206 additions and 563 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# trekplan — Brief, Research, Plan, Execute, Review, Continue
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -19,9 +19,9 @@ 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` also render their artifact to a self-contained `.html` next to it and print the `file://` link — annotate via the official `/playground` plugin (`document-critique`) and paste its prompt back.
|
||||
`/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).
|
||||
|
||||
Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md` (+ `brief.html`), `research/NN-*.md`, `plan.md` (+ `plan.html`), `sessions/`, `progress.json`, and `review.md` (+ `review.html`).
|
||||
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`.
|
||||
|
||||
### Division of labor
|
||||
|
||||
|
|
@ -503,37 +503,55 @@ Both arguments are required. No interactive prompt — headless-safe.
|
|||
|
||||
---
|
||||
|
||||
## Rendered artifacts & annotation (v5.0.0)
|
||||
## Reviewing and annotating artifacts (v5.0.1)
|
||||
|
||||
`/trekbrief`, `/trekplan`, and `/trekreview` each finish by rendering their
|
||||
just-written `.md` to a self-contained `.html` next to it
|
||||
(`{project_dir}/brief.html`, `plan.html`, `review.html`) and printing the
|
||||
`file://` link. The renderer (`scripts/render-artifact.mjs`) is a small,
|
||||
zero-dependency Node script: it folds frontmatter into a `<details>` block,
|
||||
puts code fences in styled `<pre>`, renders tables/lists/links, and inlines a
|
||||
compact design-system-aligned stylesheet. **No external network, no build
|
||||
step, no telemetry.** Two runs on the same input produce byte-identical HTML.
|
||||
`/trekbrief`, `/trekplan`, and `/trekreview` each end by printing a single
|
||||
copy-paste-ready command. After they finish, you see something like:
|
||||
|
||||
To **annotate** an artifact, run the official `/playground` plugin
|
||||
(`document-critique` template) on the `.md` file and paste the prompt it
|
||||
generates back into the conversation — Claude then revises the artifact
|
||||
freehand from your notes. The `/playground` plugin already produces clean,
|
||||
self-contained single-file HTML for exactly this; voyage no longer ships its
|
||||
own annotation UI.
|
||||
```
|
||||
────────────────────────────────────────────────────────────────────
|
||||
To review and annotate this brief, copy and paste this into Claude:
|
||||
|
||||
```bash
|
||||
# Render any artifact manually (the producing commands do this automatically):
|
||||
node plugins/voyage/scripts/render-artifact.mjs \
|
||||
.claude/projects/2026-05-09-feature/plan.md
|
||||
# → writes .claude/projects/2026-05-09-feature/plan.html, prints the path
|
||||
/playground build a document-critique playground for .claude/projects/2026-05-13-foo/brief.md
|
||||
|
||||
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.
|
||||
────────────────────────────────────────────────────────────────────
|
||||
```
|
||||
|
||||
> **Removed in v5.0.0.** v4.2/v4.3 shipped a ~388 KB bespoke playground SPA +
|
||||
> `/trekrevise` + Handover 8 (annotation → revision). A browser walkthrough
|
||||
> found it borderline unusable, and it duplicated the official `/playground`
|
||||
> plugin's `document-critique` / `diff-review` templates. All of it — the SPA,
|
||||
> the command, the supporting `lib/` modules, the anchor parser, the Playwright
|
||||
> e2e suite — was deleted. See [CHANGELOG.md](CHANGELOG.md) § v5.0.0.
|
||||
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:
|
||||
|
||||
- **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.
|
||||
|
||||
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.**
|
||||
|
||||
> **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.
|
||||
>
|
||||
> **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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -667,7 +685,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.
|
||||
|
||||
**Rendered HTML is read-only.** `scripts/render-artifact.mjs` produces a static, self-contained view for browsing — it is not an editor. To revise an artifact from operator feedback, run the `/playground` plugin (`document-critique`) on the `.md` and paste its prompt back. The markdown subset the renderer supports covers what the artifact templates emit (headings, lists, code fences, tables, links, blockquotes, bold/italic, inline code); exotic markdown extensions are not rendered.
|
||||
**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.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue