annotate-md

Annotate Markdown

Open one or more Markdown files in the md-annotator browser UI so the user can review them — selecting text to mark deletions, adding comments, or inserting text — then apply the feedback they submit.

Arguments: $ARGUMENTS

If the arguments contain Markdown file path(s), use those. Otherwise, ask the user which Markdown file they want to annotate.

Run the annotator

Run the md-annotator CLI with your shell tool, passing --origin vibe and the file path(s). This command blocks until the user submits a decision in the browser:

md-annotator --origin vibe <file1.md> [file2.md ...]

The command prints the result to stdout:

• APPROVED: → the user approved the file with no changes. Confirm and stop.
• APPROVED WITH NOTES: → the user approved the file as-is but left annotations. Do not edit the file; read the notes as context, acknowledge them, and stop.
• Structured annotation feedback → apply the requested edits to the file(s):
  • "Remove this" entries: delete the quoted text.
  • "Comment on" entries: apply the user's comment as a change to the referenced text.
  • "Insert text" entries: insert the provided text at the specified location.

Requires the md-annotator CLI on your PATH (npm install -g md-annotator, or npm link from a local checkout).

Re-review loop

Unless the user said otherwise, after applying all changes:

1. Build feedback notes describing what you changed — a JSON array of { "text": "...", "line": <number> } entries. line is the line number in the updated file; omit it for general notes.

2. Re-open the annotator with the notes so the user sees what changed:

   md-annotator --origin vibe --feedback-notes '[{"text":"Rewrote intro for clarity","line":5},{"text":"Removed redundant section"}]' <file1.md> [file2.md ...]
   

3. Evaluate the result:

   • APPROVED: → the user is satisfied. Done.
   • APPROVED WITH NOTES: → the user is satisfied. Summarize the notes without editing. Done.
   • More feedback → apply the changes and repeat from step 1.