2026-10-23 10:09:18 -07:00
# Release checklist
Run this before every release of the desktop app, on each system the release builds for: Windows
x64, macOS Apple silicon and Linux x64. Automated tests cover the logic and never start a real
window, a real terminal panel, or a real Claude, Devin or Codex, so everything here is by hand.
Work from the pre-release build: publish a GitHub pre-release so `release-app.yml` attaches the files,
then install from it. Tick each box per system and note anything that is a rough edge rather than a
failure.
2026-10-25 12:51:25 -07:00
`npm run build` here runs `tauri build` with bundling on, so a local build also produces `.msi` /NSIS
`.exe` /`.dmg` /`.deb` installer packages under `src-tauri/target/release/bundle/` . Ignore those: the
release workflow builds with `--no-bundle` and attaches only the plain executable per system (see
`.github/workflows/release-app.yml` ); `install.js` is the only installer, and it places that plain
file directly after checking it against the release's checksum list.
2026-10-23 10:09:18 -07:00
## Before you start
- [ ] `node scripts/check-versions.mjs --tag v<version>` passes (version.json, package.json,
CHANGELOG.md and the app's tauri.conf.json, package.json and Cargo.toml all agree)
- [ ] `npm test` passes at the repo root, with the app absent
2026-10-26 22:46:16 -07:00
- [ ] `cargo fmt --check` , `cargo clippy --workspace --all-targets -- -D warnings` and
`cargo test --workspace` pass in `plan2code-app/` , and the `app` workflow is green on all
2026-10-23 10:09:18 -07:00
three systems
- [ ] The pre-release has one `plan2code-app-<version>-<os>-<arch>` file per system and a
`plan2code-app-<version>-SHA256SUMS.txt`
## Install and launch (each system)
- [ ] Run the installer from the pre-release: it offers the app, downloads it, verifies the checksum
and places it in `~/.plan2code/app/`
- [ ] A deliberately corrupted download is rejected with the checksum message, and the skills and
the `plan2code` command are still installed
- [ ] `plan2code` in a project asks for the agent and model, then opens the app on that folder
- [ ] The agent and model picked in the launcher are the ones the app starts at once, with no
2026-10-25 12:50:11 -07:00
launch card or checklist shown first, and New Session keeps them
2026-10-23 10:09:18 -07:00
- [ ] `plan2code --classic` runs the agent in the terminal with the app installed
- [ ] Linux only: with `DISPLAY` and `WAYLAND_DISPLAY` unset, `plan2code` runs the terminal flow
2026-11-15 11:22:58 -08:00
- [ ] The desktop shortcut opens the folder menu (Choose a folder first, recent folders under it) and then the app
2026-10-23 10:09:18 -07:00
- [ ] macOS: the first start is stopped by Gatekeeper, **Open Anyway** in System Settings (Privacy &
Security) lets it through, and `docs/desktop-app.md` describes what you saw
- [ ] macOS and Linux: start the app from the Dock, Finder or a `.desktop` file (not a terminal) on
a machine where Node is only on PATH through nvm, Homebrew or Volta: the first-run checklist
still finds Node and the installed CLIs, and the console and an agent still start
- [ ] Windows: SmartScreen's **More info** , then **Run anyway** , lets it through, and
`docs/desktop-app.md` describes what you saw
- [ ] `plan2code update` updates the skills, the command and the app, including while the app is
running (Windows replaces the file by renaming the old one aside)
2026-11-17 18:07:58 -08:00
- [ ] **Update and restart** (bar, with a newer release out): the bar shows the installer's progress,
the app reopens on the same project, and says **Updated to vX** once; with an agent running it
asks first, and Stay leaves the app up with **Restart Plan2Code** offered; a failed update
(try it offline) leaves the old app running with a readable reason; **What's new** opens the
release page in the default browser
2026-10-23 10:09:18 -07:00
## The window (each system)
- [ ] The dashboard shows in the frame and the terminal panel is visible beneath it
- [ ] Resizing the window keeps both usable; dragging the handle resizes the panel
2026-10-25 12:50:11 -07:00
- [ ] The bar shows the project folder; the permission note appears only while an agent started
with checks off is running, never otherwise
- [ ] The OS window title (and so the taskbar entry) reads **Plan2Code - <folder name>** ,
not just **Plan2Code** ; open a second window on a different folder and confirm they read
apart in the taskbar without needing to restore either one
2026-10-23 10:09:18 -07:00
- [ ] The first run (no `firstRunDone` saved yet) shows the checklist (Node, an agent CLI, the
project folder, the skills version) before the launch card; a later launch goes straight to
the launch card
2026-11-03 04:08:36 -08:00
- [ ] The launch card offers agent, a model dropdown (the same models.json list the `plan2code`
launcher asks with, hidden for an agent with no listed models), effort (Claude and Codex
only) and permission mode (checks off is ticked by default, matching the plain `plan2code`
launcher; untick it for an agent that keeps its normal approval prompts); a CLI it could
not find is named, not just disabled
2026-11-17 18:07:58 -08:00
- [ ] **Dock the terminal to the right** : the splitter becomes vertical, and the
dashboard keeps the rest of the width; dock it back to the bottom (the dock button is an icon with a tooltip and a label)
- [ ] **Collapse** the terminal to a thin strip (either dock) and its expand button (**Show the terminal**) brings it
2026-10-27 10:09:50 -07:00
back; its size from before collapsing is remembered
2026-11-17 18:07:58 -08:00
- [ ] Docked right, collapsed: the strip holds only the expand button (and the pill, reading top-to-bottom),
with nothing running off the edge
2026-10-23 10:09:18 -07:00
- [ ] Collapse the terminal (or shrink it small), let the agent go quiet for a while mid-answer: the
2026-11-17 18:07:58 -08:00
**Agent may need you** pill appears on the strip; pressing it expands the terminal and focuses it, and the pill clears
- [ ] The splitter takes the keyboard (Tab to it, arrows step it 2%, Home and End go to the ends)
and a double-click returns it to the default width; Ctrl or Cmd with plus, minus and 0 change the
terminal's text size, and it is the same size after a relaunch
- [ ] Switch the theme (and the highlight) in User Preferences: the bar, the terminal frame, the terminal's
colors and the OS title bar all follow at once, and a relaunch opens in that theme with no flash of
the other one (check WebView2 on Windows, and WebKit on macOS and Linux: scrollbars, fonts, title bar)
- [ ] The window appears already painted (no white or blank frame), says "Starting Plan2Code" until the
first screen, remembers its size and position, and opens maximized only on the very first launch
- [ ] Narrow the window: the model text leaves the top bar first, then the status line (both then sit in
the agent menu), and the bar never scrolls; ** +N more** opens a list of the other steps
2026-10-25 12:50:11 -07:00
- [ ] The top bar's project and agent menus open under their name, close on a click elsewhere (the
console frame and the terminal included) or Escape, and are not cut off by the bar
- [ ] **Change project** in the top bar's project menu, with an agent running: it asks first, then the folder
2026-11-15 11:22:58 -08:00
picker (Choose a folder, then recent folders) opens; canceling the picker leaves the running agent and its project untouched
- [ ] Start the app with no arguments: it shows the folder picker, not the last project; a recent folder opens in one click
2026-10-23 10:09:18 -07:00
- [ ] Change project, pick a different folder: the old agent and console stop, the new folder opens
on the launch card (or the checklist, if its own first run has not passed yet)
- [ ] Reload the window (or navigate away and back) while an agent is running: the terminal redraws
from where it was, not blank, and the dashboard reconnects to the same session
2026-10-25 12:50:11 -07:00
- [ ] When the app and the installed skills differ in version, the bar's right end offers **Update
skills**, and nothing updates until it is pressed; with the console stopped as well, Reconnect
the console shows first and "+1 more" names the update
2026-10-23 10:09:18 -07:00
## The terminal panel, with each real agent (each system)
Do each of Claude Code, Devin and Codex for a few minutes:
- [ ] Startup screen draws correctly
- [ ] Typing a prompt and getting an answer
- [ ] A long streamed answer scrolls and stays readable
- [ ] Resizing the window reflows the agent's screen
- [ ] Pasting several lines
- [ ] A line with Unicode and emoji
- [ ] Select text in the terminal: it copies on its own; Ctrl+Shift+C (Windows, Linux) or Cmd+C
(macOS) copies the selection too; Ctrl+V / Cmd+V pastes
2026-10-25 12:50:11 -07:00
- [ ] Exiting the agent: the agent menu reads "ended" with the reason beside it, and New Session stays
just left of it
2026-10-23 10:09:18 -07:00
## Agent lifecycle
2026-10-25 12:51:21 -07:00
- [ ] Start, then **New Session** : it confirms once, with Planny on a coffee break and no claim about unsaved
2026-10-25 12:50:11 -07:00
work, then a fresh agent starts on the same agent, model, effort and permission mode, and the
dashboard shows the pick-up chip with a brief that matches the session
- [ ] An agent that ends by itself leaves the app asking nothing until New Session or **Change agent**
(in the agent menu) is pressed; Change agent reopens the launch card with a real choice to make again
2026-10-23 10:09:18 -07:00
- [ ] Closing the window while an agent runs asks first, and "no" keeps the window open
- [ ] Cmd+Q on macOS asks the same
2026-10-25 12:50:11 -07:00
- [ ] Windows only: start a CLI installed through npm (a `.cmd` shim), then New Session; check Task
2026-10-23 10:09:18 -07:00
Manager and confirm no leftover `node.exe` (or the CLI's own process) is left running
2026-10-26 06:36:45 -07:00
## Agents and the taskbar (each system)
2026-11-02 12:00:10 -08:00
- [ ] A custom agent added in the console's User Preferences → Agents & models (the fake agent in `fake-agent/` works) shows in the launch card's picker after the built-ins, starts, and **New Session** starts the same agent again; the bypass box adds its bypass arguments
2026-10-26 06:36:45 -07:00
- [ ] With no agent CLI on `PATH` and no custom agent, the first-run checklist and the launch card show the explainer with each install command and an **Install page** link, and Start is off
- [ ] Each **Install page** link opens the right page in the default browser (Claude Code, Devin, Codex)
- [ ] Install an agent (or add a custom one), press **Check again** : it appears and Start turns on without restarting the app
- [ ] With only one agent installed and nothing remembered, the launch card starts on that agent, not Claude Code
2026-10-27 18:20:32 -07:00
- [ ] Windows: the taskbar button shows a green dot when it is your move and a red dot when Plan2Code needs attention, a green dot on a finished screen that still offers a button (back to the dashboard, a review), and no dot while the agent is busy, once a finished step has nothing left to press, or after the agent ends
2026-10-26 06:36:45 -07:00
- [ ] Windows: with the window unfocused, the button gives one short burst of flashes when it becomes your move or needs attention (not again on a repeat) and stays lit until the window gets focus
- [ ] macOS: the dock shows a red `!` badge when Plan2Code needs attention (no badge on your move), and bounces once when it becomes your move or needs attention while the app is in the background
- [ ] Linux: where the desktop shows badges, a count of 1 appears on needs attention, and the window is marked as wanting attention while unfocused
- [ ] Reloading the window, or ending the agent, clears the dot
2026-11-02 12:00:10 -08:00
- [ ] User Preferences → System → Desktop app (shown only inside the app, not in a browser tab) has **Show on the taskbar when Plan2Code needs me** , on by default; switching it off clears the dot at once and stops flashes, and the choice is still off after quitting and reopening the app
2026-10-26 06:36:45 -07:00
2026-10-23 10:09:18 -07:00
## Standalone path
- [ ] `/plan2code` typed inside an agent with the app closed opens the dashboard exactly as before
- [ ] `npm test` still passes with the app installed on this machine