doc-review

name	doc-review
description	Open a plan, research, or design doc in Plannotator's browser UI for human review and act on the returned annotations. Use when the user says "review the plan", "open the doc in plannotator", "let me annotate the research", "review the latest doc", or returns to a session to gate work the agent produced.
allowed-tools	Bash(plannotator:*),Bash(hive ctx ls),Bash(ls:*),Bash(find:*),Bash(stat:*),Read
disable-model-invocation	true

Doc Review

Open a markdown document in Plannotator with --gate, then act on the user's annotations in the same conversation. The --gate flag blocks until the user approves or denies, and returns their feedback as command output.

Argument handling

$ARGUMENTS controls which doc opens:

Argument	Behavior
empty	Newest .md across .hive/plans/, .hive/research/, .hive/design-docs/
plans	Newest .md in .hive/plans/
research	Newest .md in .hive/research/
design-docs	Newest .md in .hive/design-docs/
any path	That file directly (relative to cwd or absolute)
any URL	That URL (Plannotator handles https:// natively)

To find the newest file, use find with -printf (or stat on macOS) and pick the highest mtime. Resolve .hive/ via the symlink — do NOT use Glob, it won't follow it. If the symlink doesn't exist, run hive ctx init first.

If no candidate file is found, tell the user which directory was empty and stop. Don't guess a path.

Run

plannotator annotate <resolved-path-or-url> --gate

Don't ask the user to copy the command into a terminal — run it yourself.

After plannotator returns

• Annotations returned — address each one in the same conversation. If the document needs edits, edit the file, summarize what changed, and offer to re-gate.
• Approval / LGTM — acknowledge briefly and continue with whatever the doc was setting up (implementation, next research question, etc.).
• Denied with no actionable feedback — ask the user what they'd like changed before re-gating.
• Session closed without feedback — say so in one sentence and continue.

Notes

• --gate is the right mode for this skill; it's the synchronous review primitive.
• Plannotator returns its result on the same CLI invocation, so the agent sees the annotations in the next tool turn — no polling, no separate hook.
• If the user wants async review (close the session, come back later), they should use hive todo add --uri "review://<path>" instead — that's a different workflow and not what this skill is for.