Skip to content

Comment Workflow

Jump to bottom
xirothedev edited this page Aug 25, 2026 · 1 revision

Comment Workflow

Sync source: docs/COMMENT-WORKFLOW.md, src/core/format/ooxml/

For files that already have content, propose changes as suggestion comments instead of overwriting text. Each proposal lives in a comment and stays visible until explicitly approved.

Flow

  1. edit the existing file to open its draft (auto-acquires the lock)
  2. Attach a suggestion comment to the changed spot
  3. list-comments to inspect pending suggestions
  4. approve to apply one suggestion into the draft (comment removed)
  5. accept to write the file

DOCX example

officecli(action="edit", filePath="/path/to/report.docx", content="# Updated draft")
officecli(action="comment", filePath="/path/to/report.docx",
  commentId="c1", author="AI Agent", commentText="Tighten summary",
  suggestedText="Revised paragraph text",
  rangeStartParagraph=0, rangeStartOffset=0, rangeEndParagraph=0, rangeEndOffset=10)
officecli(action="list-comments", filePath="/path/to/report.docx")
officecli(action="approve", filePath="/path/to/report.docx", commentId="c1")
officecli(action="accept", filePath="/path/to/report.docx")

Supported formats

Format Comments Track changes
DOCX yes (range anchor) yes, via track-insert / track-delete (w:ins/w:del)
XLSX yes (cellRef anchor, value suggestions) no — use comment with suggestedText
PPTX yes (slide anchor) no — use comment with suggestedText

API

Add comment

officecli(action="comment", filePath="...", commentId="c1", author="AI Agent", commentText="...")

Anchor per format:

  • DOCX (range-based): rangeStartParagraph, rangeStartOffset, rangeEndParagraph, rangeEndOffset
  • XLSX (cell-based): cellRef (e.g. "B4")
  • PPTX (slide-based): slide (index)

Optional: suggestedText makes the comment an approvable suggestion; targetText anchors the comment near matching text.

Approve

officecli(action="approve", filePath="...", commentId="c1")

Applies the suggestion's suggestedText into the draft and removes the comment. approve only accepts comments that carry suggestedText; approving a plain note is an error.

Track changes (DOCX only)

officecli(action="track-insert", filePath="...", commentId="c1", author="AI Agent", content="inserted text", paragraph=0, offset=5)
officecli(action="track-delete", filePath="...", commentId="c1", author="AI Agent", content="deleted text", paragraph=0, offset=5)

Returns an error for XLSX/PPTX (no track-changes representation in those formats) — use comment with suggestedText there.

List / review

officecli(action="list-comments", filePath="...")   # → { count, comments: [...] }
officecli(action="review", filePath="...")          # → comments + track changes (DOCX)

Comments survive Office round-trips, so a user can review/resolve them in Word/Excel/PowerPoint.

Lock states

  • acquired — a session is editing the draft
  • in-review — a user is reviewing in Office
  • stale — lock timeout exceeded; eligible for force-release

Limitations

  • Suggestions and track changes live in the draft until accept.
  • approve applies text substitution at the anchor point; it does not reflow surrounding content.

Clone this wiki locally