Adds two session-only flags to plannotator review, parsed in the shared
parser so every host inherits them together:
- --base <ref> opens the session against a caller-chosen compare target
(branch, origin/<branch>, tag, SHA, HEAD~N), probed with git rev-parse
--verify --end-of-options before the server starts so a typo'd ref is a
startup error with near-match suggestions instead of a silently
mislabelled merge-base->HEAD diff.
- --diff-type <id> opens the session in one of the nine flat git diff
modes (REVIEW_OPEN_DIFF_TYPES, pinned against GIT_DIFF_TYPES).
The flags are a seed, never a setting: nothing writes config.json or any
review cookie, and the UI stays fully mutable. Validation is pure in
packages/shared/review-open-state.ts (provider matrix errors on
jj/GitButler/P4/workspace/PR mode, promote-with-notice when the saved
default is base-irrelevant, fatal explicit contradiction).
A flagged base rides explicitBase semantics: the new initialBaseExplicit
server option (both runtimes) seeds baseExplicitlyChosen, suppressing the
startup origin/* upgrade and canonicalization, and openStatePinned rides
/api/diff so the client neither offers the first-run setup dialog (its
one-time cookie is NOT consumed) nor runs the panel-pair self-heal for a
pinned session. The since-base dropdown label now renders from the live
active base, matching the adjacent base picker.
Coverage: Bun CLI, opencode-review bridge, OpenCode embedded plugin, and
the Pi extension (re-vendored; strict validation on the slash-command
path only, programmatic callers unchanged). Skills, command stubs, help
text, and docs updated across every host surface.
Two agent command-surface cleanups. Both remove only the command entry points; all underlying infrastructure stays.
1. /plannotator-status (Pi): removed — it echoed phase/plan-file/progress on
demand, but that state is already shown ambiently (status bar + live
checklist widget). The phase/checklist state machine is untouched.
2. /plannotator-archive (all agents): removed the command/skill entry points
across every surface — Claude/Codex/Kiro skills, Pi, OpenCode (handler +
dispatch + cli-bridge + embedded + stub), Droid, the Kiro agent prompt, all
three installers, docs, marketing, and the CI deprecated-command guard. The
installers also gained a stale-skill cleanup so upgraders drop a previously
installed plannotator-archive skill.
Kept (infrastructure) — archive browsing stays available in-review via the
sidebar: the `plannotator archive` CLI subcommand (apps/hook/server), the
mode:"archive" server path + /api/archive endpoints, ArchiveBrowser/useArchive,
the sidebar Archive tab, sessions.ts "archive" mode, and ~/.plannotator/plans
storage.
Verified: bun test scripts/install.test.ts → 72 pass; pi-extension typecheck +
build:opencode pass; repo-wide residual scan clean; KEEP-set integrity
confirmed; one orphaned import (opencode commands.ts) caught in self-review and
removed.
Universal, auto-detected Kiro CLI support — no flag, no separate installer.
When ~/.kiro exists (or kiro-cli is on PATH), the installer copies Plannotator
skills and a custom agent into ~/.kiro, the same convention used for Codex and
Gemini.
- packages/shared: add the kiro-cli agent origin (badge, prompt runtime,
PLAN_TOOL_NAMES). Origin is cosmetic for Kiro (no dedicated AI provider).
- apps/kiro-cli: 3 origin-baked skills (review/annotate/archive) + an example
custom agent that wires every skill via skill:// resources and a
plannotator-scoped shell tool. setup-goal + visual-explainer install from
apps/skills (no content duplication).
- scripts/install.sh: auto-detect ~/.kiro, sparse-checkout apps/kiro-cli,
install 3 kiro + 2 shared skills + the agent (never clobbering an existing
one); covered by scripts/install.test.ts.
- scripts/install.ps1 + install.cmd: Windows parity mirroring the Codex
pattern. Statically verified only; not yet runtime-tested on Windows.
- docs: installation + Kiro guides, AGENTS.md, env-var reference updated.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Michael Ramos