proposal: Add visual PFM packets for annotate gate

[leoreisdias]

Context

This PR explores a Plannotator-native version of the richer visual planning experience that tools like Agent-Native make feel so useful: a plan can be more than a wall of markdown, with file maps, diagrams, callouts, checklists, questions, and reviewable structure.

The important boundary here is that this is inspiration, not runtime compatibility. The source stays Plannotator Flavored Markdown, the renderer uses constrained built-in PFM directives, and visual packets still move through the existing plannotator annotate --gate <file-or-folder> workflow instead of introducing a new public command or MDX/React component execution surface.

This can land as a first concept if the direction feels right, while leaving room for follow-up work: more custom PFM blocks, a future extension contract for user-defined blocks, and eventually a visual review mode alongside Code Tour that reuses the same PFM component vocabulary.

What Changed

• Adds visual PFM packet detection for markdown annotate sessions and Pi parity.
• Renders native visual directives in the shared block renderer:
  • callout
  • file-map
  • diagram
  • checklist
  • open-questions
  • annotated-diff
  • code-walkthrough
• Keeps annotate gate behavior intact for approve, close, feedback, JSON/plaintext/hook output, folder browsing, source save, and the agent terminal rules.
• Makes visual checklist toggles create annotation feedback instead of being cosmetic-only.
• Adds the optional plannotator-visual-plan extra skill to author PFM visual plan packets and open them with annotate gate.
• Updates installer optional-extra lists and Kiro docs/agent wiring so the new skill is discoverable where the other extras are.

Screenshots

I am leaving these slots open intentionally so we can paste screenshots from the generated test packet before marking this ready for review.

For a local visual smoke test, open pfm-kitchen-sink.md with plannotator annotate --gate pfm-kitchen-sink.md; it exercises the current visual PFM blocks in one packet.

Callout

File Map

Diagram

Checklist

Open Questions

Annotated Diff

Code Walkthrough

Review Focus

• The PFM contract: visual packets should stay readable markdown and should not imply MDX, Agent-Native block compatibility, or arbitrary runtime component execution.
• Annotate gate preservation: visual packets should behave like annotate sessions with extra rendering, not like a new plan mode.
• Parser and renderer boundaries: unknown directives should degrade gracefully, while supported visual directives should route through the native renderer.
• Installer/docs surface: plannotator-visual-plan should be treated as an optional extra skill, not a new default command surface.

Future Work This Enables

• Add more Plannotator-native PFM blocks once the first vocabulary proves useful.
• Define a future extension model where user-provided PFM blocks register schemas and renderer adapters, instead of executing arbitrary MDX/React.
• Build a visual review mode in the review app, likely as a sibling option to Code Tour, backed by the same constrained visual block renderer.

Test Plan

• bun test --timeout 15000 apps/hook/server/cli.test.ts apps/hook/server/annotate-outcome.test.ts packages/server/annotate.test.ts packages/shared/agent-terminal.test.ts apps/pi-extension/server.test.ts
• bun test apps/skills/extra/plannotator-visual-plan/SKILL.test.ts packages/server/annotate.test.ts packages/ui/components/BlockRenderer.visual.test.tsx scripts/install.test.ts
• bash apps/pi-extension/vendor.sh && node node_modules/.bun/typescript@5.8.3/node_modules/typescript/bin/tsc --noEmit -p packages/shared/tsconfig.json && node node_modules/.bun/typescript@5.8.3/node_modules/typescript/bin/tsc --noEmit -p packages/ai/tsconfig.json && node node_modules/.bun/typescript@5.8.3/node_modules/typescript/bin/tsc --noEmit -p packages/server/tsconfig.json && node node_modules/.bun/typescript@5.8.3/node_modules/typescript/bin/tsc --noEmit -p packages/ui/tsconfig.json && node node_modules/.bun/typescript@5.8.3/node_modules/typescript/bin/tsc --noEmit -p apps/pi-extension/tsconfig.json
• bun run build:hook
• bun build apps/hook/server/index.ts --target=bun --define "__CLI_VERSION__=\"0.0.0-test\"" --outfile /tmp/plannotator-hook-server-test.js