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

docs(voyage): CLAUDE.md + README + CHANGELOG + annotation-quickstart + late doc-consistency pins — v4.2 Step 13

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-05-09 15:41:45 +02:00
commit de160d7da1
6 changed files with 296 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

50
plugins/voyage/README.md
View file

@ -8,7 +8,7 @@
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, independent post-hoc review, and zero-friction multi-session resumption. Six commands, one pipeline:
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, independent post-hoc review, operator-driven artifact annotation, and zero-friction multi-session resumption. Seven commands, one pipeline:
| Command | What it does |
|---------|-------------|
@ -17,6 +17,7 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep
| **`/trekplan`** | Plan — agent swarm exploration, Opus planning, adversarial review |
| **`/trekexecute`** | Execute — disciplined step-by-step implementation with failure recovery |
| **`/trekreview`** | Review — independent post-hoc review of delivered code against the brief, severity-tagged findings |
| **`/trekrevise`** | Revise — apply operator annotations from the playground back into brief/plan/review with audit trail (Handover 8, v4.2) |
| **`/trekcontinue`** | Continue — read `.session-state.local.json` and resume the next session in a multi-session project |
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`.
@ -30,6 +31,7 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s
| `/trekplan` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors when an opt-in upstream architect plugin (not bundled) is installed. | `plan.md` with Manifest blocks + `plan_version: 1.7` |
| `/trekexecute` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | `progress.json` + structured report + manifest-audit status |
| `/trekreview` | **Close the loop** — independent post-hoc reviewer reads `brief.md` and the diff produced by execute, runs brief-conformance + code-correctness reviewers in parallel, dedups via Judge Agent. Severity-tagged findings (Critical/High/Medium/Low/Info) feed back into planning via Handover 6. | `review.md` (`type: trekreview`) with stable 40-char hex finding-IDs |
| `/trekrevise` | **Re-fold operator annotations** — operator opens the playground, anchors comments on a brief/plan/review, exports the batch, pastes back as `/trekrevise --apply`. Round-trippable in-place revision: `revision:` counter, `source_annotations:` audit trail, deterministic `annotation_digest`. Single-iteration MVP per Handover 8. | revised `brief.md` / `plan.md` / `review.md` with frontmatter audit trail |
**Principle:** Each step consumes the previous step's structured artifact. If execute has to guess, the plan is weak and must be revised upstream — not patched downstream.
@ -501,6 +503,52 @@ Both arguments are required. No interactive prompt — headless-safe.
---
## `/trekrevise` — Annotation playground (v4.2)
Voyage's first interactive playground. Open `playground/voyage-playground.html`
in any modern browser, paste your `brief.md`, `plan.md`, or `review.md`, and
annotate the rendered artifact directly. The playground is a single
self-contained HTML file with vendored `markdown-it` + `highlight.js` —
no build step, no network calls, no telemetry.
The annotation lifecycle is **Handover 8 — annotation → revision** (see
`docs/HANDOVER-CONTRACTS.md`). Three stages:
1. **Annotate** — drag-select text or hover-anchor a paragraph; fill the
modal with comment + intent (`change` / `add` / `remove` / `clarify` /
`risk`). Anchors are placed only at block boundaries; the playground
refuses placement inside list items, mid-paragraph, or at line-start
collision points.
2. **Export** — click "Eksporter batch" to copy a complete
`/trekrevise --project <dir> --apply '{...JSON...}'` invocation to your
clipboard.
3. **Apply** — paste the command in Claude Code chat. `/trekrevise` parses
the batch, re-runs placement validation, atomically writes anchor comment
blocks back into the source artifact, increments `revision:`, appends to
`source_annotations:`, and recomputes the deterministic `annotation_digest`.
The artifact's body remains byte-identical outside anchor blocks (SC2). Re-applying
the same batch yields the same digest (idempotence — SC3). The frontmatter
audit trail makes every revision traceable in git.
```bash
# Open the playground (one-time)
open plugins/voyage/playground/voyage-playground.html
# Or render an artifact server-side via the CLI helper:
node plugins/voyage/scripts/render-artifact.mjs \
.claude/projects/2026-05-09-feature/plan.md \
--out /tmp/plan.html
```
For a step-by-step walkthrough, see
[`docs/annotation-quickstart.md`](docs/annotation-quickstart.md).
**Single-iteration MVP:** Each operator batch produces one `revision:` bump.
Multi-iteration loops (revise → re-review → revise again) are deferred
indefinitely per research-05; the brief's SC4 wording is single-revision.
---
## The full pipeline
```