Imported from akillness/jeo-skills (.agent-skills/plannotator/SKILL.md) via skills.sh. Install upstream with npx skills add akillness/jeo-skills --skill plannotator. Copyright stays with the author (MIT).

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

• 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

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

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

  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