Plannotator Review Gates — Spec Kit Extension

A Spec Kit extension that opens a Plannotator human review gate after every Spec Kit workflow step. The agent finishes a step, Plannotator opens in your browser, and the workflow blocks until you approve, send annotations, or dismiss. Annotations flow back to the agent as revision feedback.

What gets reviewed when

After	Review	Mode
/speckit.specify	spec.md	markdown annotation
/speckit.clarify	spec.md	markdown annotation
/speckit.plan	feature folder (plan.md, research.md, data-model.md, quickstart.md, contracts/)	markdown annotation
/speckit.checklist	checklists/	markdown annotation
/speckit.tasks	tasks.md	markdown annotation
/speckit.analyze	analysis.md (report saved to the feature folder first)	markdown annotation
/speckit.implement	full branch diff vs default branch	code review (plannotator review --git)

Document steps use plannotator annotate <target> --hook (three-button gate: Approve / Send Annotations / Close). The implement step uses Plannotator's code-review diff viewer instead — comments on code hunks, not prose.

Install

Prerequisite: the Plannotator CLI on your PATH.

bun add -g plannotator

Install the extension into a Spec Kit project:

specify extension add plannotator --from https://github.com/FNDEVVE/plannotator-spec-kit/archive/refs/heads/main.zip

Or pin a release: .../archive/refs/tags/v0.1.0.zip. Spec Kit shows a security warning for non-catalog URLs — expected.

For local development:

specify extension add --dev /path/to/plannotator-spec-kit

⚠️ Bash timeout (read this)

A human review can take longer than your agent's shell timeout. For Claude Code, raise the cap in the target project's .claude/settings.json:

{
  "env": {
    "BASH_MAX_TIMEOUT_MS": "86400000"
  }
}

Without this, the Bash call running the blocking review may be killed after the default maximum (10 minutes) while you're still reviewing.

Configuration

Per-event toggles live in .specify/extensions/plannotator/plannotator-config.yml:

review_gates:
  default: true
  after_specify: true
  after_clarify: true
  after_plan: true
  after_checklist: true
  after_tasks: true
  after_analyze: true
  after_implement: true

Set any event to false to skip that gate; unlisted events fall back to default.

How it works

Spec Kit's extension hooks fire once, after a command completes — not on every file write — so the gate opens when the artifact is actually done. Each hook invokes one of two extension commands:

• speckit.plannotator.annotate — maps the fired event to its artifact and runs plannotator annotate <target> --hook. Empty stdout means approved/dismissed; {"decision":"block","reason":"..."} means the agent revises the artifact per your annotations and reopens the review.
• speckit.plannotator.code-review — runs plannotator review --git over the branch diff; feedback loops the same way (fix → commit → re-review) until approved.

If plannotator is missing or a target file doesn't exist, gates skip with a warning — the Spec Kit workflow is never hard-blocked by the reviewer tooling.

Related

• The Plannotator Claude Code plugin provides manual /plannotator-* slash commands; this extension is the automatic Spec Kit gate layer on top of the same CLI.

License

Apache-2.0