| name | plannotator-specs |
| description | Interactive spec review via Plannotator. Use after writing a spec document (design doc, SPEC file) to let the user review it with inline annotations before committing. Auto-detects the most recently written spec file. |
| allowed-tools | Bash(plannotator:*), Bash(find:*), Bash(git status:*), Read, Edit |
| tags | ["plannotator"] |
Spec Review via Plannotator
Review a spec document interactively using Plannotator annotations, then iterate on feedback until the user approves.
Context
- Recent spec files: !
find specs -name "*.md" -type f 2>/dev/null | head -10
- Git status: !
git status --short 2>/dev/null | head -20
Instructions
Step 1: Identify the spec file
Determine which spec file to review:
- If
$ARGUMENTS is provided, use that as the file path
- Otherwise, look at the conversation context for the most recently written or modified spec file (typically in
specs/)
- If still unclear, check
git status for recently added or modified .md files in spec directories
- If no spec file can be found, tell the user and stop
Step 2: Open Plannotator
Run the plannotator annotate command on the identified spec file. The user will review it in their browser and leave inline comments.
If $ARGUMENTS was provided and you identified the file in step 1, run:
plannotator annotate <spec-file-path>
If $ARGUMENTS was not provided, you must first identify the file (step 1), then run the command with the resolved path.
Step 3: Address feedback
After the user submits their annotations:
- Read each annotation carefully
- Make the requested changes to the spec file
- Do NOT commit yet — the spec is still under review
Step 4: Re-open for review
After addressing all comments, re-open the spec in Plannotator so the user can verify the changes and leave additional comments if needed.
Step 5: Loop until approved
Repeat steps 3-4 until the user has no more comments. The user signals approval by submitting with no annotations or by saying they approve.
Step 6: Return control
Once the user approves:
- Tell the caller the spec is approved and ready
- Do NOT commit the spec — let the calling workflow handle that
The spec file is now reviewed and ready for the next step in whatever workflow invoked this skill.
