Release Plannotator

Plannotator Release

The process has four phases. Phase 1 (release notes) is where most of the work happens — present the draft for review before proceeding to later phases.

Phase 1: Draft Release Notes

This is the most important phase. The release notes are the public face of each version and the primary way the community sees their contributions recognized.

Step 1: Determine scope

1. Find the latest release tag: git tag --sort=-v:refname | head -1 2. Determine the new version number. Ask the user if unclear (patch, minor, or major). 3. Gather all changes since the last tag:

• git log --oneline <last-tag>..HEAD for commit history
• git log --merges --oneline <last-tag>..HEAD for merged PRs

4. For each PR, use gh pr view <number> --json title,author,body,closedIssues,labels to get details.

Step 2: Research contributors

This is critical. Every person who participated in the release gets credit — not just PR authors.

For each PR and linked issue, collect:

• PR authors — the person who wrote the code
• Issue reporters — who filed the bug or feature request
• Issue commenters — who participated in the discussion with useful context
• Discussion creators — who started relevant GitHub Discussions
• Feature requestors — check the linked "closes #N" issues and their authors

Use the GitHub API via gh:

# Get issue details including author
gh issue view <number> --json author,title,body

# Get issue comments to find participants
gh api repos/backnotprop/plannotator/issues/<number>/comments --jq '.[].user.login'

# Get PR review comments
gh api repos/backnotprop/plannotator/pulls/<number>/comments --jq '.[].user.login'

Step 3: Write the release notes

Read the reference release notes in references/ for the canonical template structure. These are real release notes from previous versions — match their tone, structure, and level of detail.

• release-notes-v0.13.0.md — large release, 14 PRs, 3 first-time contributors, "New Contributors" + narrative "Contributors" section
• release-notes-v0.12.0.md — large community release, 14 PRs, 10 external, detailed narrative "Contributors" section
• release-notes-v0.13.1.md — small patch release, 2 PRs, no external authors, "Community" section focused on issue reporters

Pay attention to how each reference handles contributor crediting differently. Pick the pattern that fits the release's contributor profile — a release with many external PRs warrants a narrative "Contributors" section; a patch driven by issue reports uses a lighter "Community" section.

Write the file to the repo root as RELEASE_NOTES_v<VERSION>.md.

Structure

1. X/Twitter follow link — first line, always the same:

   Follow [@plannotator](https://x.com/plannotator) on X for updates

2. "Missed recent releases?" collapsible table — copy from the previous release's notes, then:

• Add the previous release (the one you're succeeding) as the newest row
• Keep roughly 10-12 rows; drop the oldest if needed
• Each row: version link + comma-separated feature highlights (short phrases)

3. "What's New in vX.Y.Z" — the heart of the notes

• Open with 1-3 sentences summarizing the release theme and scope. Mention how many PRs, how many from external contributors, any first-timers.
• Each major feature/fix gets its own ### subsection with:
• A descriptive heading (not the PR title verbatim — rephrase for clarity)
• 1-4 paragraphs explaining what changed and why it matters. Be specific and concrete. Describe the problem that existed before, what the change does, and how users experience it.
• Credit line at the bottom: PR link, linked issues with closing [#N], and contributor attribution
• Minor changes go under ### Additional Changes as bold-titled bullets

4. Install / Update — standard block, read from the previous release notes and reuse verbatim

5. "What's Changed" — bullet list of every PR in the release:

   - feat: descriptive PR title by @author in [#N](url)

6. "New Contributors" — if any first-time contributors:

   - @username made their first contribution in [#N](url)

7. "Contributors" or "Community" — narrative section recognizing everyone who participated:

• PR authors get a sentence about what they built
• Issue reporters and commenters get listed with what they reported/discussed
• Group community issue reporters in a bullet list at the end

8. Full Changelog link:

   **Full Changelog**: https://github.com/backnotprop/plannotator/compare/<prev-tag>...<new-tag>

Writing guidelines

• Narrative over noise. Write in clear, readable prose. Not marketing-speak, not changelog-dump. Explain what changed and why someone should care, in plain language.
• Bullets where they help. Use bullet lists for enumerating discrete items (additional changes, contributor lists). Use paragraphs for explaining features.
• No cliches or buzzwords. Don't say "exciting", "game-changing", "seamless", "powerful". Just describe what happened.
• No punchlines. Don't end sections with a clever quip or a summary zinger. Let the feature speak for itself.
• Speak through practical benefit. Describe what changed and what it means for the user in concrete, reliable terms. Not aspirational, not hype — just what it does.
• Don't overuse em dashes. One or two per release is fine. If you notice them stacking up, restructure the sentence instead.
• Grammatical structure matters. Vary sentence structure. Active voice. Concrete subjects and verbs.
• Contributor tags. Use @username — bare at-mentions, not markdown links like [@user](url). GitHub renders bare @mentions with avatar icons in release notes. This is important for community recognition.
• Every contributor counts. Everyone who filed an issue, left a comment that shaped a decision, or participated in a discussion gets mentioned. This project's community is its lifeblood.

Step 4: Present for review

Write the draft to RELEASE_NOTES_v<VERSION>.md in the repo root and tell the user it's ready for review. Do not git add or commit this file — release notes are kept untracked by design. Wait for their feedback before proceeding to Phase 2.

---

Phase 2: Version Bump

Bump the version string in these 7 files (and only these — other package.json files use stub versions):

Read each file, confirm the current version matches expectations, then update all 7 atomically.

Do not bump the VS Code extension (apps/vscode-extension/package.json) — it has independent versioning.

---

Phase 3: Build

Run builds in dependency order:

bun run build:review    # 1. Code review editor (standalone Vite build)
bun run build:hook      # 2. Plan review + hook server (copies review's built HTML into hook dist)
bun run build:opencode  # 3. OpenCode plugin (copies built HTML from hook + review)
bun run build:pi        # 4. Pi extension (chains review → hook → pi internally, safe to run after 1-2)

build:pi chains review and hook internally, so after steps 1-2 it only runs the pi-specific build.

Verify all builds succeed before proceeding.

Pi Parity Gate

After builds pass, audit the Pi extension to ensure all server-side imports resolve in the published package. This catches missing files before they reach npm.

1. Check imports vs `files` array. Trace all local imports (starting with ./ or ../) from index.ts, server.ts, tool-scope.ts, and every file in server/. Verify each target is covered by a pattern in the files array of apps/pi-extension/package.json.

2. Check `vendor.sh` covers all shared/ai imports. Every ../generated/*.js import in the server files must have a corresponding entry in vendor.sh's copy loops. If a new shared module or AI module was added to packages/shared/ or packages/ai/ and is imported by Pi's server code, it must be added to vendor.sh.

3. Dry-run the pack. Run cd apps/pi-extension && bun pm pack --dry-run and verify the output includes every file the server imports. Look specifically for any newly added files since the last release.

4. Quick smoke test. Confirm generated/ contains all expected files after build, especially any new ones (e.g., a new shared module added in this release cycle).

If anything is missing, fix it before proceeding to Phase 4. Common fixes:

• Add the file to vendor.sh's copy loop
• Add the file or directory to the files array in package.json
• Add an import path fix (Pi uses ../generated/ not @plannotator/shared or @plannotator/ai)

---

Phase 4: Commit, Tag, and Release

1. Commit the version bump:

   chore: bump version to X.Y.Z

Stage only the 7 version-bumped files. Do not stage the release notes file (it's untracked by design).

2. Create and push the tag:

   git tag vX.Y.Z
   git push origin main
   git push origin vX.Y.Z

The v* tag push triggers the release pipeline (.github/workflows/release.yml).

3. The pipeline handles everything else:

• Runs tests
• Cross-compiles binaries for 6 platforms (macOS ARM64/x64, Linux x64/ARM64, Windows x64/ARM64)
• Compiles paste service binaries (same 6 platforms)
• Generates SLSA build provenance attestations for all 12 binaries via actions/attest-build-provenance (signed through Sigstore, recorded in Rekor)
• Creates the GitHub Release with all binaries attached
• Publishes @plannotator/opencode and @plannotator/pi-extension to npm with provenance

Note on immutable releases: The repo has GitHub Immutable Releases enabled, so once the v* tag is pushed and the release is created, the tag→commit and tag→asset bindings are permanent. You cannot delete and re-create a tag to "fix" a bad release — you must ship a new version. Release notes remain editable (see step 5), but everything else is locked.

4. Monitor the pipeline: Watch the release workflow run until it completes:

   gh run list --workflow=release.yml --limit=1
   gh run view <run-id> --log

Verify:

• All jobs pass (test, build, release, npm-publish)
• The GitHub Release was created with all binary artifacts
• npm packages published successfully (check with npm view @plannotator/opencode version and npm view @plannotator/pi-extension version)

If anything fails, investigate the logs and report to the user before retrying.

5. Replace the release notes: Once the release is live and verified, replace the auto-generated notes body with the drafted release notes:

   gh release edit vX.Y.Z --notes-file RELEASE_NOTES_v<VERSION>.md

---

Checklist

Before tagging, verify:

• [ ] All 7 version files bumped consistently
• [ ] Release notes drafted and reviewed
• [ ] bun run build:review succeeded
• [ ] bun run build:hook succeeded
• [ ] bun run build:opencode succeeded
• [ ] bun run build:pi succeeded (or pi-specific build step)
• [ ] Version bump committed
• [ ] Pi parity gate passed (imports, vendor.sh, dry-run pack)
• [ ] No stale build artifacts (clean builds, no cache issues — run bun install first if dependencies changed)

After tagging, verify:

• [ ] Release workflow completed (all 4 jobs green)
• [ ] GitHub Release created with all binaries
• [ ] npm packages published at correct version
• [ ] Release notes replaced via gh release edit

Follow @plannotator on X for updates

---

<details> <summary><strong>Missed recent releases?</strong></summary>

</details>

---

What's New in v0.12.0

This is the community release. Ten of the fourteen PRs in v0.12.0 were authored by external contributors, spanning three major features and a sweep of cross-platform fixes. The annotation system gained preset labels for one-click feedback — no typing, just click and move on. The plan viewer now renders Graphviz diagrams alongside Mermaid, inline markdown images with a lightbox zoom, and renders all diagrams by default instead of showing raw source. And the entire UI works on mobile.

Quick Annotation Labels

Reviewing a plan often means the same feedback applies to multiple sections — "clarify this," "verify this assumption," "match existing patterns." Quick Labels turn those into one-click preset chips that appear above the annotation toolbar. Select text, click a label, done. No typing required.

Ten default labels ship out of the box, each with an emoji and a color-coded pill:

❓ Clarify this · 🗺️ Missing overview · 🔍 Verify this · 🔬 Give me an example · 🧬 Match existing patterns · 🔄 Consider alternatives · 📉 Ensure no regression · 🚫 Out of scope · 🧪 Needs tests · 👍 Nice approach

Several labels carry agent-facing tips that get injected into the feedback. For example, selecting a section and clicking "🔍 Verify this" tells the agent: "This seems like an assumption. Verify by reading the actual code before proceeding." The "🧬 Match existing patterns" label instructs the agent to search the codebase for existing solutions rather than introducing a new approach. These tips are invisible to the reviewer but shape how the agent responds.

When the feedback is exported, labeled annotations are grouped into a Label Summary section at the bottom — **🔍 Verify this**: 3 — so both the reviewer and the agent can see at a glance which patterns recur across the plan.

Labels are fully customizable in Settings. Add up to 12, reorder them, pick custom colors and tips, or remove the ones you never use. Settings persist across sessions via cookies.

A follow-up PR introduced a dedicated Quick Label editing mode alongside Markup, Comment, and Redline. In this mode, selecting text immediately shows a floating label picker — no toolbar intermediary. Alt+1 through Alt+0 keyboard shortcuts work in any mode for power users who prefer not to reach for the mouse.

• Authored by @grubmanItay in #268 and #272

Mobile Compatibility

Plannotator was desktop-only. That mattered less when the tool was purely a local dev workflow, but with shared URLs and team reviews becoming common, people were opening plan links on phones and tablets and getting a broken layout.

The UI now adapts fully below 768px. The header collapses into a hamburger menu. The annotation panel renders as a full-screen overlay with a backdrop and close button. Touch support covers resize handles, pinpoint annotations, text selection, and the toolstrip. Card action buttons are always visible on touch devices instead of appearing on hover. The Settings modal switches to a horizontal tab bar. The CommentPopover width is capped to the viewport so it doesn't overflow off-screen.

Desktop layout is completely unchanged — this is additive, not a redesign.

• Authored by @grubmanItay in #260

Graphviz Diagram Rendering

Plannotator has supported Mermaid diagrams since v0.6.8. Plans that use Graphviz for architecture diagrams, dependency graphs, or state machines were stuck with raw DOT source in a code block. The Viewer now renders graphviz, dot, and gv fenced code blocks using @viz-js/viz, with the same UX conventions as Mermaid: source/diagram toggle, zoom and pan controls, and an expanded fullscreen view.

• Authored by @flex-yj-kim in #266

Mermaid Diagram Improvements

The Mermaid viewer received a substantial UX overhaul. Diagrams now open in a proper expanded fullscreen mode with zoom in/out, fit-to-view, and wheel zoom. The source/diagram toggle was reworked for clarity. Wide diagrams no longer clip against container edges in both plan view and plan diff view. Safari stability issues with SVG rendering were resolved.

A separate PR changed both Mermaid and Graphviz diagrams to render by default instead of showing raw source code first — the source toggle is still one click away, but the visual rendering is now the default state.

• Authored by @flex-yj-kim in #264 and #279
• Issue #275 filed by @flex-yj-kim

Markdown Image Rendering

Markdown ![alt](path) syntax was silently treated as plain text — the ! character wasn't in the inline scanner, so images never rendered. They do now. Local image paths are proxied through the existing /api/image endpoint, and relative paths resolve correctly when annotating files outside the project root.

Clicking any rendered image opens a full-screen lightbox with the alt text as a caption. Press Escape or click the backdrop to dismiss.

• Authored by @dgrissen2 in #271

Linked Doc Navigation in Annotate Mode

The /plannotator-annotate command lets you annotate any markdown file, but clicking .md links inside that file would break — the annotate server was missing a /api/doc endpoint, so link requests returned raw HTML instead of JSON. This release adds the missing route and supports chained relative link navigation, so you can follow links between sibling markdown files without leaving annotate mode.

• Authored by @dgrissen2 in #276

VS Code Extension in SSH Remote Sessions

The VS Code extension sets PLANNOTATOR_BROWSER to its own open-in-vscode handler so plans open in editor tabs instead of external browsers. In SSH remote sessions, the shared openBrowser() function skipped browser launch entirely — ignoring the custom handler. The fix is a one-line condition change: if PLANNOTATOR_BROWSER is set, always call openBrowser() regardless of remote detection. This covers plan review, code review, and annotate mode.

• Authored and reported by @7tg in #274, closing #259

Additional Changes

• Windows markdown path support — plannotator annotate now handles Windows drive-letter paths (C:\..., C:/...), Git Bash/MSYS paths (/c/...), and Cygwin paths (/cygdrive/c/...) in the shared markdown resolver (#267 by @flex-yj-kim)
• OS-aware update banner — the update banner now detects the user's OS and shows the correct install command: bash/curl on macOS and Linux, PowerShell on Windows (#270, reported by @eromoe in #265)
• Pi origin in code review — the code review UI now recognizes Pi as a first-class origin with a violet badge, correct install command in the update banner, and proper agent name in the completion overlay (#263)
• Codex support — documentation and install instructions for running Plannotator inside Codex, which uses the CLI directly without a plugin (#261)
• Welcome dialog cleanup — removed three first-run dialogs (UI Features Setup, Plan Diff Marketing, What's New v0.11.0) that had outlived their usefulness. The only remaining first-open dialog is the Permission Mode Setup, which directly affects agent behavior (#280)

---

Install / Update

macOS / Linux:

curl -fsSL https://plannotator.ai/install.sh | bash

Windows:

irm https://plannotator.ai/install.ps1 | iex

Claude Code Plugin: Run /plugin in Claude Code, find plannotator, and click "Update now".

OpenCode: Clear cache and restart:

rm -rf ~/.bun/install/cache/@plannotator

Then in opencode.json:

{
  "plugin": ["@plannotator/opencode@latest"]
}

Pi: Install or update the extension:

pi install npm:@plannotator/pi-extension

---

What's Changed

• docs: add Codex support by @backnotprop in #261
• feat: add Pi origin support to code review UI by @backnotprop in #263
• feat: Improve Mermaid diagram viewing experience by @flex-yj-kim in #264
• feat: Add Graphviz diagram rendering in plan mode by @flex-yj-kim in #266
• fix: Support Windows markdown paths in CLI annotate flow by @flex-yj-kim in #267
• feat: add quick annotation labels for one-click preset feedback by @grubmanItay in #268
• fix: detect OS for update banner install command by @backnotprop in #270
• feat: render markdown images with lightbox zoom by @dgrissen2 in #271
• feat: add quick label selection mode for one-click annotations by @grubmanItay in #272
• fix: open browser in SSH remote when PLANNOTATOR_BROWSER is set by @7tg in #274
• fix: enable linked doc navigation in annotate mode by @dgrissen2 in #276
• feat: render diagrams by default in plan review by @flex-yj-kim in #279
• feat: add mobile compatibility by @grubmanItay in #260
• chore: remove non-critical welcome dialogs by @backnotprop in #280

Contributors

@grubmanItay was a major contributor to this release with three PRs — Quick Annotation Labels, Quick Label Mode, and full mobile support. The labels system touched the annotation pipeline end-to-end: new UI components, settings persistence, keyboard shortcuts, export formatting, and share URL backward compatibility.

@flex-yj-kim continues as the project's most prolific external contributor. Four PRs in this release: Graphviz rendering, Mermaid viewer overhaul, render-by-default diagrams, and Windows path support. Across v0.9.3 through v0.12.0, Yeongjin has authored twelve merged PRs spanning both the plan and code review UIs.

@dgrissen2 shipped two PRs — markdown image rendering with the lightbox viewer and the annotate-mode linked doc navigation fix. Both address gaps where the viewer silently dropped content instead of rendering it.

@7tg authored the SSH remote fix for the VS Code extension, which he also reported in #259 with a thorough diagnostic of the underlying IPC issue.

Community members who reported issues and participated in discussions that shaped this release:

• @eromoe — #265 (OS detection for update banner install command)
• @grubmanItay — #278 (quick label defaults discussion)

Full Changelog: https://github.com/backnotprop/plannotator/compare/v0.11.4...v0.12.0

Follow @plannotator on X for updates

---

<details> <summary><strong>Missed recent releases?</strong></summary>

</details>

---

What's New in v0.13.0

v0.13.0 brings built-in themes, annotatable plan diffs, file-scoped code review comments, and deeper platform parity for the Pi extension. Six of the fourteen PRs in this release came from external contributors, three of them first-time.

Built-in Theme System

The UI now ships with eighteen built-in themes across dark, light, and system-adaptive modes, from high-contrast terminals to soft pastels. A theme grid in Settings lets you preview and switch instantly; your choice persists via cookies across sessions. Under the hood, all color tokens were consolidated into packages/ui/theme.css as CSS custom properties, which means the plan viewer, code review, and annotate UIs all share a single source of truth for color.

• #294

Annotatable Plan Diffs

Plan diff view (the comparison that appears when a coding agent resubmits after a denial) now supports annotations directly on diff content. Hover over an added, removed, or modified section and the annotation toolbar appears. Each annotation carries a diffContext field (added, removed, modified) that is included in the exported feedback, so the agent knows exactly which part of the diff your comment targets. This was a major refactor: the annotation highlighting infrastructure was extracted into a shared useAnnotationHighlighter hook, and the diff view uses its own block-level hover system rather than web-highlighter.

File-Scoped Comments in Code Review

The /plannotator-review UI now supports file-level comments in addition to line-level annotations. Each file header has a comment composer that lets you leave feedback about the file as a whole. These comments appear in the Review Panel alongside line annotations and are included in the exported feedback. Useful for high-level observations like "this file should be split" or "the approach here needs rethinking" that don't attach to any specific line.

• Authored by @sercantor in #303, closing #302

Octarine Notes Integration

Octarine joins Obsidian and Bear as a third notes app integration. Plan snapshots can be saved directly to Octarine on approval or denial. All three integrations now support an auto-save toggle. Enable it once in Settings and every plan decision writes to your notes app without prompting. Under the hood, all integration saves run in parallel with Promise.allSettled, so a slow or failing integration doesn't block the others.

• #297

Pi Extension: Remote Session Support

The Pi extension now detects SSH and devcontainer environments the same way the Claude Code hook does, using PLANNOTATOR_REMOTE, SSH_TTY, and SSH_CONNECTION. In remote sessions, it uses a fixed port and returns the URL for manual browser opening instead of trying to launch one. This brings Pi to full parity with Claude Code and OpenCode for remote development workflows.

• Authored by @fink-andreas in #299

Unified Review Core (Bun + Pi)

The review server had two implementations: one in the Bun-compiled hook, one in the Pi extension. They drifted apart over time, causing bugs like missing untracked file support in Pi. This release extracts a runtime-agnostic review core that both platforms consume. Diff assembly, file content retrieval, worktree handling, and stage/unstage all live in one place now. Regression tests cover the shared surface.

• #310, closing #307 reported by @0xbentang

Shared Feedback Templates

The deny feedback message that gets sent back to the agent was inconsistent across plan review, code review, and annotate mode. Each had its own phrasing and structure. This release unifies them into shared templates. It also adds an instruction to preserve the plan's # Title heading on resubmission, which fixes a version history issue where title changes would break slug-based plan grouping.

• #298, addressing #296 reported by @MarceloPrado

Configurable Bear Tags

Bear integration previously hardcoded the tag. You can now set custom tags and choose whether tags are prepended or appended to the note body. This PR also fixes a double-title bug where both the URL parameter title and the H1 in the note body were rendering.

• Authored by @MarceloPrado in #283

Additional Changes

• Favicon. All three server modes (plan review, code review, annotate) now serve an SVG favicon: purple rounded square with a white "P" and gold highlight stripe (#312 by @dgrissen2, idea from Discussion #269)
• LGTM approval fix. Approving in code review no longer tells the agent to "address all feedback." If you clicked LGTM, there is no feedback to address (#293, reported by @tobeycodes in #284)
• Non-blocking browser launch (Pi/Linux). execSync(xdg-open) blocked the Pi extension's event loop on Linux. Replaced with detached spawn().unref() (#292, reported by @dvic in #288)
• Mobile context menu fix. Suppresses the native iOS Safari callout and Android Chrome context menu during text selection so the annotation toolbar isn't obscured (#281 by @grubmanItay)
• Tater sprite z-index fix. The tater mascot was rendering in front of the plan document due to a stacking context created by the mobile compat PR. Fixed (#308)
• review-renovate skill. New agent skill at .agents/skills/review-renovate/ for automated supply chain review of Renovate dependency PRs (#306)

---

Install / Update

macOS / Linux:

curl -fsSL https://plannotator.ai/install.sh | bash

Windows:

irm https://plannotator.ai/install.ps1 | iex

Claude Code Plugin: Run /plugin in Claude Code, find plannotator, and click "Update now".

OpenCode: Clear cache and restart:

rm -rf ~/.bun/install/cache/@plannotator

Then in opencode.json:

{
  "plugin": ["@plannotator/opencode@latest"]
}

Pi: Install or update the extension:

pi install npm:@plannotator/pi-extension

---

What's Changed

• fix: suppress native mobile context menu on text selection by @grubmanItay in #281
• feat: configurable Bear tags + fix double-title bug by @MarceloPrado in #283
• fix: non-blocking browser launch in Pi extension (Linux) by @backnotprop in #292
• fix: don't ask agent to address feedback on LGTM approval by @backnotprop in #293
• feat: built-in theme system with 18 themes by @backnotprop in #294
• feat: Octarine notes integration + auto-save for all integrations by @backnotprop in #297
• refactor: shared feedback templates + preserve plan title on deny by @backnotprop in #298
• feat(pi-extension): add remote session support for SSH/devcontainer by @fink-andreas in #299
• feat: add file-scoped comments to /plannotator-review by @sercantor in #303
• chore(deps): update github actions by @renovate in #305
• feat: add review-renovate agent skill for CI dependency audits by @backnotprop in #306
• fix: tater sprite z-index regression from mobile compat PR by @backnotprop in #308
• Unify review core across Bun and Pi by @backnotprop in #310
• feat: add favicon (Purple P + gold highlight) by @dgrissen2 in #312

New Contributors

• @MarceloPrado made their first contribution in #283
• @fink-andreas made their first contribution in #299
• @sercantor made their first contribution in #303

Contributors

@sercantor authored file-scoped comments for code review (#303), a feature he also requested in #302. First contribution to the project.

@fink-andreas brought remote session support to the Pi extension (#299), also a first contribution.

@MarceloPrado authored configurable Bear tags (#283) and reported the version history title issue (#296) that led to the shared feedback template refactor. First contribution.

@grubmanItay continues contributing with the mobile context menu fix (#281), a follow-up to the mobile compat work shipped in v0.12.0.

@dgrissen2 added the favicon across all server modes (#312), sparked by Discussion #269.

Community members who reported issues that drove changes in this release:

• @0xbentang: #307 (missing untracked files in Pi review)
• @tobeycodes: #284 (LGTM approval still asking agent to address feedback)
• @dvic: #288 (Pi extension blocking on Linux browser launch)
• @MarceloPrado: #296 (version history title preservation)
• @sercantor: #302 (file-scoped comments request)

Full Changelog: https://github.com/backnotprop/plannotator/compare/v0.12.0...v0.13.0

Follow @plannotator on X for updates

---

<details> <summary><strong>Missed recent releases?</strong></summary>

</details>

---

What's New in v0.13.1

v0.13.1 rewrites how Plannotator works with OpenCode's plan mode. The plugin now intercepts plan mode, injects its own planning workflow, and gives OpenCode users the same interactive browser-based review that Claude Code and Pi users already have. This release also fixes an Obsidian save failure on certain Bun versions.

OpenCode Plan Mode Rewrite

Previous versions of the OpenCode plugin had a fragile plan mode integration. Long plans caused JSON parse errors because the entire plan was passed as a tool call string argument. The agent wrote to a custom directory that OpenCode's permission system blocked. The browser review UI often failed to open. There was no support for the agent asking clarifying questions during planning.

This release replaces all of that with file-based plan storage. The agent writes its plan to a markdown file on disk, then calls submit_plan with the file path. Plans live in ~/.local/share/opencode/plans/, which is the XDG data path that OpenCode's permission system already allows. The agent picks the filename, and on feedback it revises the same file and resubmits. No content is lost between rounds.

The planning prompt now follows an exploration-first workflow: Explore the codebase, ask clarifying questions, write the plan, submit for review. Previously, agents would jump straight into writing a plan before understanding the code. For greenfield tasks where there is no codebase to explore, the agent skips to questions. The prompt is tool-neutral and avoids referencing specific tool names like write or edit, so it works with GPT models that use apply_patch.

Under the hood, the plugin strips OpenCode's native "STRICTLY FORBIDDEN: ANY file edits" directive from the system prompt and replaces it with Plannotator's own scoped rules, which allow the agent to create and edit plan files while still preventing codebase modifications. The submit_plan tool is hidden from subagents by default; users running custom subagent workflows like Superpowers or OhMyOpenCode can set PLANNOTATOR_ALLOW_SUBAGENTS=1 to make it visible.

Shared checklist utilities were extracted to @plannotator/shared for cross-plugin reuse of plan execution tracking.

• #318, closing #63 (file-based plans, requested by @DanielusG), #129 (JSON parse error, reported by @5trongHust), #152 (question support, requested by @fidelix), #183 (browser not opening, reported by @eromoe), and #289 (subagent access, reported by @sfpmld)

Obsidian Save Fix

Bun versions 1.1.43 through 1.1.45 introduced a regression where mkdirSync({ recursive: true }) throws EEXIST when the directory already exists. This broke Obsidian saves on the second attempt. The fix adds an existsSync guard before the mkdir call. It's a no-op on unaffected Bun versions and prevents the save failure on affected ones.

• #319, fixing #315 reported by @Pollux12

---

Install / Update

macOS / Linux:

curl -fsSL https://plannotator.ai/install.sh | bash

Windows:

irm https://plannotator.ai/install.ps1 | iex

Claude Code Plugin: Run /plugin in Claude Code, find plannotator, and click "Update now".

OpenCode: Clear cache and restart:

rm -rf ~/.bun/install/cache/@plannotator

Then in opencode.json:

{
  "plugin": ["@plannotator/opencode@latest"]
}

Pi: Install or update the extension:

pi install npm:@plannotator/pi-extension

---

What's Changed

• feat: Pi-style iterative planning for OpenCode plugin by @backnotprop in #318
• fix: guard Obsidian mkdir against Bun EEXIST regression by @backnotprop in #319

Community

Five long-standing feature requests and bug reports drove this release:

• @DanielusG requested file-based plans in #63, the oldest open issue on the tracker
• @5trongHust reported the JSON parse error on long plans in #129
• @fidelix requested question/answer support during planning in #152
• @eromoe reported the browser not opening after plan mode in #183
• @sfpmld reported subagent access to submit_plan in #289
• @Pollux12 reported the Obsidian save failure in #315

Full Changelog: https://github.com/backnotprop/plannotator/compare/v0.13.0...v0.13.1