plannotator

Use this skill when the job is to classify one review packet, open the smallest honest visual review path, and leave broad planning / PR policy / UI critique work outside the front door.

plannotator is not the planner. It is the human approval gate that sits between:

• plan/spec creation (task-planning, ralph)
• orchestration/runtime ownership (jeo, task-planning, bmad)
• broader PR/code judgment (code-review)
• rendered-UI bug markup (agentation)
• clean browser verification (browser-harness)

Read these support docs first:

• references/intake-packets-and-route-outs.md
• references/platform-setup.md
• references/notes-and-troubleshooting.md

When to use this skill

• A coding agent already produced an implementation plan and a human must approve or request changes before coding starts.
• A concrete git diff, commit range, or PR exists and the reviewer wants browser-based line-targeted feedback.
• A markdown artifact such as a spec, PRD, architecture note, or generated plan package needs visual review and revision feedback.
• The user needs to connect plannotator to Claude Code, Gemini CLI, Codex CLI, or OpenCode and the main job is setup for the review loop.
• The review flow exists but remote mode, stable URLs/ports, or platform-specific behavior is flaky and needs targeted troubleshooting.

When not to use this skill

• The main job is writing or refining the plan/spec itself → task-planning, ralph, or survey
• The main job is broad PR policy, merge criteria, risk judgment, or code-owner approval → code-review
• The main job is exact rendered-UI critique that should drive frontend fixes → agentation
• The main job is clean disposable browser automation or deterministic website verification → browser-harness
• The main job is task orchestration, board state, or multi-agent routing → jeo, task-planning, bmad
• The main job is note taxonomy, wiki curation, or long-term note-system management → obsidian, llm-wiki

Instructions

Step 1: Classify the review packet first

Normalize the request into one primary packet before discussing commands.

plannotator_intake:
  primary_packet: plan-review | diff-review | markdown-review | platform-setup | troubleshooting
  artifact_ready: yes | no
  artifact_type: plan | git-diff | pr | markdown-spec | generated-response | unknown
  platform: claude | gemini | codex | opencode | mixed | unknown
  trigger_mode: native-hook | manual-review | unknown
  feedback_goal: approve | request-changes | annotate | archive | unknown
  repo_context: git-repo | markdown-only | remote-container | unknown
  confidence: high | medium | low

Default to the smallest obvious interpretation:

• existing implementation plan → plan-review
• existing code changes / PR / commit range → diff-review
• existing spec or markdown artifact → markdown-review
• install/integration question → platform-setup
• flaky remote/browser/status issue → troubleshooting

Step 2: Verify the concrete artifact exists

plannotator only helps once something concrete can be reviewed.

Checklist:

1. A plan, diff, PR, markdown file, or generated response already exists.
2. The user wants review, not plan generation.
3. For diff review, a git repo, PR URL, or explicit commit range exists.
4. For markdown/spec review, the file or generated artifact is identifiable.
5. For note export, save/integration is configured; treat it as secondary, not the main packet.

If the artifact is missing, route out instead of forcing the review tool.

Step 3: Choose exactly one review packet

Use the router in references/intake-packets-and-route-outs.md and pick one primary packet:

• plan-review
• diff-review
• markdown-review
• platform-setup
• troubleshooting

List anything else as follow-up, not as a co-owner.

Step 4: Run the chosen packet

• Plan review → confirm the runtime can hand the plan into plannotator, use the native/hook path when real, annotate one issue per step, and end with approve, request changes, or archive/save.
• Diff review → use a concrete target and launch the smallest diff packet:

  bash scripts/review.sh
  bash scripts/review.sh HEAD~1
  bash scripts/review.sh main...HEAD
  

  Copy
• Markdown review → confirm the spec/PRD/architecture file exists, use annotation/review mode directly, and be explicit when the runtime only supports annotation rather than a stronger approval path.
• Platform setup → start with:

  bash scripts/install.sh
  bash scripts/check-status.sh
  

  Copy
  then use references/platform-setup.md.
• Troubleshooting → start with:

  bash scripts/check-status.sh
  bash scripts/configure-remote.sh
  

  Copy
  then use references/notes-and-troubleshooting.md.

Step 5: Keep manual-vs-hook reality explicit

• Claude and Gemini are the clearest native/hook-driven plan-review fits.
• Codex has public hooks, but upstream plannotator still documents the practical path as manual diff/markdown review or partial setup.
• OpenCode users explicitly asked for more manual control when auto-invocation is too eager.

Do not flatten this into “all platforms work the same.”

Step 6: Route adjacent work aggressively

• planning/spec creation or refinement → task-planning, ralph, survey
• orchestration state or multi-agent routing → jeo, task-planning, bmad
• broad PR policy, merge gating, or risk judgment → code-review
• rendered UI bug markup → agentation
• clean disposable browser verification → browser-harness
• note/vault/wiki administration beyond saving reviewed artifacts → obsidian, llm-wiki

Step 7: Use a short output contract

Preferred output:

# plannotator Review Packet
- Primary packet:
- Artifact:
- Platform + trigger mode:
- Next action:
- Outcome or limitation:
- Route-outs:

For setup-heavy asks, use a short setup brief with:

• platform
• native-hook vs manual-review status
• install commands
• verification steps
• caveats

Examples

Example 1: Approve a concrete plan

Input

The agent already proposed a 6-step implementation plan. I want to inspect it visually and either approve it or send corrections back before coding starts.

Good output direction

• choose plan-review
• verify the plan already exists
• use the runtime's real review surface
• annotate one issue per step
• end with approve vs request-changes
• route plan creation back out if the plan is still immature

Example 2: Review a diff

Input

The agent already changed three files. Open the visual diff review for main...HEAD and let me leave targeted feedback.

Good output direction

• choose diff-review
• verify git context / diff range
• use bash scripts/review.sh main...HEAD
• keep broader PR-policy review routed to code-review

Example 3: Review a PRD/spec artifact

Input

I want to mark up this architecture note and either accept it as-is or send revision feedback before we continue.

Good output direction

• choose markdown-review
• verify the markdown artifact exists
• explain whether the current platform supports native approval or manual annotation only
• keep note export secondary and route wiki/vault management outward

Example 4: Codex setup reality check

Input

Set up plannotator for Codex so I can review plans before code runs.

Good output direction

• choose platform-setup
• start with install + status verification
• explain the current Codex manual/partial reality honestly instead of promising parity that upstream docs do not show
• route broad hook/platform policy work outward if needed

Best practices

1. Treat plannotator as a visual approval gate, not the planning engine.
2. Review one concrete artifact at a time.
3. Keep manual-review vs native-hook differences explicit.
4. Use one annotation per issue whenever possible.
5. End with a clear outcome: approve, request changes, annotate only, or archive.
6. Keep note export secondary to the review packet.
7. Route PR policy, orchestration, and rendered-UI critique to neighboring skills instead of stretching plannotator.

References

• GitHub: backnotprop/plannotator
• Official site: plannotator.ai
• references/intake-packets-and-route-outs.md
• references/platform-setup.md
• references/notes-and-troubleshooting.md
• references/review-modes-and-boundaries.md