Repository navigation
Description
Use case
An agent writes a Guided Review of a PR itself (the guide.json + patch shape that plannotator guide export --guide --patch already accepts), then opens plannotator review so the reviewer can follow that guide next to the diff and comment.
Problem
An authored guide can be exported to HTML or shared to guides.show, but it cannot be opened in a review. The Guides panel lists only guides the review session generated or saved itself, and no CLI command or endpoint puts one there. plannotator guide has list, export, share and unshare, but no way in.
The only workaround is to write the saved-guide envelope by hand into <data dir>/guides/<repo key>/<id>.json plus <id>.patch, recomputing the repo key the way the session does. That is a private on-disk format, so it can break on any release.
Proposal
plannotator guide import --guide <guide.json> --patch <diff.patch | -> | --snapshot <snapshot.json> [--pr <url>]
- It takes the same sources as
export, validated the same way (buildAuthoredGuideSnapshot,parseGuideSnapshotJson). - It saves to the shelf the review session reads, keyed as the session keys it:
--pr(or the snapshot's own PR URL), else the origin remote, else the repo directory. The PR also sets the label (PR #7); otherwise the label is the branch. - It prints the saved id. The next
plannotator reviewof that repository lists the guide under Guides, andguide export --id/share --idwork on it like on a generated guide.
Scope
I have a working prototype on UberMouse:context-notes, off main (d5fe10a): its last commit, d750d612e. The four commits before it are #2588. It is about 105 lines of source, 65 lines of tests and 3 lines of docs:
packages/shared/guide-store.ts:saveImportedGuide(), the inverse ofbuildSavedGuideSnapshot(patch first, then the envelope).packages/server/guide/guide-cli.ts:runGuideImport, reusingparseSourceArgs/loadSnapshotSource; usage text.apps/hook/server/cli.ts, the plannotator skill and the portable-guides page: one line each.- Tests in
guide-cli.test.ts: a review session (createGuideStoreSession) of the same repository lists the imported guide,--prfiles it under the PR's repository, and invalid input saves nothing.
Happy to open it as a PR.
Alternatives considered
plannotator review --guide guide.json: open the review with the guide already loaded, without saving it. That is nicer for a one-shot agent flow, but it needs a new launch option in both server runtimes and the review UI.importreuses the store and the Guides panel as they are, and a review flag could be added later on top of it.POST /api/guideson a running review. Same runtime cost as above, and the guide is lost when the session ends unless it is also saved.- The Inbox's
submit_guide(Plannotator Inbox: guided reviews from agents (step 5) #1760). It delivers a guide to the Inbox's read-only viewer, not to a review session where the reviewer comments on the diff.
Open questions
-
A
review --patch-filesession has no git context, so it shelves guides by directory (<dir>-<hash>), not by the origin remote. Import follows git and PR reviews, so a guide imported for a repository is not listed in a--patch-filereview of the same checkout. Should--patch-filesessions read the cwd's remote when there is one, or should import take a--dirfor that case? -
Should import respect the guide-history setting (
resolveGuideHistory) that gates autosave? The prototype always saves, since import is an explicit request. -
Re-importing the same guide makes a second entry. Should it replace an earlier import with the same title and patch?
Posted by Claude Code
Activity
backnotprop commentedon Nov 4, 2026
Thanks for the clear write-up. Taking a look now.
Merge pull request #2603 from backnotprop/feat/guide-import