Adeu — Tracked-Changes Redlining for .docx
Adeu is a Virtual DOM for Word documents. It translates .docx into LLM-friendly Markdown with CriticMarkup for tracked changes, lets you propose edits as native Word w:ins/w:del revisions, and writes the result back without destroying formatting, comments, or document structure.
When to use this skill
The user is working with an existing .docx and wants you to:
- Propose edits that show up as Word Track Changes
- Accept, reject, or reply to existing tracked changes and comments
- Compare two versions of a document
- Strip author metadata and lock a document for distribution
- Read a contract intelligently, including its defined terms and cross-references
If the user wants a fresh Word document built from nothing, defer to the docx skill instead.
Execution path — pick once, then forget
Adeu runs in two modes. Pick the first that applies and stop:
- MCP tools available. If you see Adeu MCP tools in the session (
read_docx, process_document_batch, accept_all_changes, diff_docx_files, finalize_document), use them. This is the preferred path on every platform. Load references/mcp-tools.md before planning any non-trivial batch.
- Bash available, no MCP tools. Shell out to the Python CLI:
uvx adeu <subcommand>. This is the only CLI Adeu ships — there is no Node CLI. Load references/cli-fallback.md for the command surface and the JSON shape adeu apply expects.
- Neither available. Tell the user. Suggested install lines, in this order:
- Claude Code plugin (covers everything):
/plugin marketplace add dealfluence/adeu then /plugin install adeu-redlining@adeu-skills
- Node MCP server (recommended for most users, zero Python required):
npx -y @adeu/mcp-server
- Python MCP server (required for Live MS Word integration on Windows, and for
protection_mode="encrypt" on finalize_document): uvx --from adeu adeu-server
- Python CLI only (for scripted/headless pipelines):
uv tool install adeu
Do not present these as options to the user mid-task. Pick the available path and proceed.
Core workflow
Every redlining task follows the same shape. Follow it in order:
- Read first. Always read the document before editing. Use
read_docx (MCP) or uvx adeu extract (CLI). For long contracts, start with mode="outline" to see the heading structure, then read specific pages.
- Plan the edits. Each edit is either a search-and-replace (most common), an accept/reject of an existing tracked change by ID, a reply to a comment by ID, or a structural table edit. Write the plan down explicitly before applying.
- Apply as one batch. Send all edits in a single
process_document_batch call (MCP) or one adeu apply invocation (CLI). Edits apply sequentially: each edit evaluates against the document state produced by the edits before it, so dependent edits may be chained — a later edit must target the text as it reads after the earlier edits.
- Verify. If the user asked for a specific outcome, re-read the modified file with
clean_view=true (MCP) or --clean (CLI) and confirm.
Batches are transactional: if any edit fails validation, the whole batch is rejected, nothing is written, and the error reports per-edit failures you can correct and resubmit.
Critical gotchas
These are environment-specific facts that will trip you up if you assume Word/.docx behaves like plain text. Read this section every time.
IDs are session-bound. Change IDs (Chg:12) and comment IDs (Com:5) shift every time the document state changes. Before any accept, reject, or reply action, call read_docx immediately before the batch. Never reuse IDs from earlier in the conversation. Never reuse IDs across a save/reload boundary.
Batches apply sequentially and reject transactionally. You can rename X → Y and then in the same batch modify Y — but the second edit must target Y (the text as it reads after the rename), not the original X wording. Stale targets fail validation, and any validation failure rejects the whole batch (nothing is applied) with per-edit errors explaining what to fix.
target_text must be unique by default. match_mode: "strict" (the default) requires a single match. Either add surrounding context to disambiguate, or explicitly set match_mode: "first" or "all". Set regex: true to use a regular expression; capture groups are available as $1, $2 in new_text.
Do not write CriticMarkup tags manually. Never put {++, {--, {>>, or {== into new_text. Use the comment field on the edit to attach a margin comment. Adeu generates the tracked-change XML from your plain replacement text.
new_text supports Markdown. Headings (# through ######), **bold**, _italic_ (not *italic* — strictly underscores), and \n\n to split into paragraphs. Empty string deletes.
Read the appendix before editing structural references. read_docx projects a semantic appendix at the bottom of the document containing defined terms, cross-references ([~text~](#_Ref)), internal anchors ({#_BookmarkName}), and footnotes ([^fn-id]). Anything inside the <!-- READONLY_BOUNDARY_START --> marker is read-only — attempting to modify it via search-and-replace will be rejected. Use mode="appendix" to see it explicitly.
clean_view toggles the document state you see. clean_view=false (default) shows the raw document with all pending tracked changes inline as CriticMarkup. clean_view=true shows what the document would look like if every pending change were accepted. Choose deliberately — comparing the wrong view to user intent is the most common source of confusion.
Page indexing. page=N paginates the body. page='all' or omitting page with a search_query searches the whole document. Don't assume page numbers from the user's PDF viewer match Adeu's pagination — they often don't.
Live Word (Windows COM) is Python-only. If the user is editing the active document in Word, only the Python adeu server supports it. The Node server does not. Table row inserts/deletes are also not supported in Live Word mode — fall back to disk editing.
Multi-author redlines. If the document has tracked changes from multiple authors, edits that overlap another author's pending insertion are rejected to prevent silent destruction of their work. Tell the user; don't try to force it.
Edit types — quick reference
Use references/mcp-tools.md for the full schema. The five operations:
| Type |
Purpose |
Required fields |
modify |
Search-and-replace as a tracked change |
target_text, new_text |
accept |
Finalize an existing tracked change |
target_id (e.g. Chg:12) |
reject |
Revert an existing tracked change |
target_id |
reply |
Reply to an existing comment |
target_id (e.g. Com:5), text |
insert_row / delete_row |
Add or remove a table row |
target_text (a cell value to anchor on), plus position/cells for inserts |
comment is optional on modify/accept/reject to attach a margin comment.
Reference loading
Load these only when relevant — they're not part of the base context:
references/mcp-tools.md — full MCP tool schemas, parameter details, process_document_batch discriminated union. Load before planning any non-trivial edit batch on the MCP path.references/cli-fallback.md — uvx adeu subcommands and the edits.json shape. Load on the CLI path.references/criticmarkup.md — CriticMarkup syntax and Adeu's semantic projections (footnotes, cross-refs, anchors, defined-terms appendix). Load when interpreting raw read_docx output or when the user asks about a marker like [^fn-3] or {#_BookmarkName}.
1---2name: adeu-redlining3description: Use this skill when reviewing, editing, redlining, or negotiating an existing Microsoft Word document (.docx) — including proposing edits as tracked changes, accepting or rejecting existing tracked changes, replying to comments, comparing two versions, sanitizing author metadata, or finalizing a contract for distribution. Use whenever the user mentions redlines, track changes, contract review, .docx editing, or a Word document they want changed, even if they don't name a specific tool. Do NOT use for creating a Word document from scratch with no source file — use the docx skill for that.4license: MIT (see LICENSE.txt)5---67# Adeu — Tracked-Changes Redlining for .docx89Adeu is a Virtual DOM for Word documents. It translates `.docx` into LLM-friendly Markdown with CriticMarkup for tracked changes, lets you propose edits as native Word `w:ins`/`w:del` revisions, and writes the result back without destroying formatting, comments, or document structure.1011## When to use this skill1213The user is working with an existing `.docx` and wants you to:1415- Propose edits that show up as Word Track Changes16- Accept, reject, or reply to existing tracked changes and comments17- Compare two versions of a document18- Strip author metadata and lock a document for distribution19- Read a contract intelligently, including its defined terms and cross-references2021If the user wants a fresh Word document built from nothing, defer to the `docx` skill instead.2223## Execution path — pick once, then forget2425Adeu runs in two modes. Pick the first that applies and stop:26271. **MCP tools available.** If you see Adeu MCP tools in the session (`read_docx`, `process_document_batch`, `accept_all_changes`, `diff_docx_files`, `finalize_document`), use them. This is the preferred path on every platform. Load `references/mcp-tools.md` before planning any non-trivial batch.282. **Bash available, no MCP tools.** Shell out to the Python CLI: `uvx adeu <subcommand>`. This is the only CLI Adeu ships — there is no Node CLI. Load `references/cli-fallback.md` for the command surface and the JSON shape `adeu apply` expects.293. **Neither available.** Tell the user. Suggested install lines, in this order:30 - Claude Code plugin (covers everything): `/plugin marketplace add dealfluence/adeu` then `/plugin install adeu-redlining@adeu-skills`31 - Node MCP server (recommended for most users, zero Python required): `npx -y @adeu/mcp-server`32 - Python MCP server (required for Live MS Word integration on Windows, and for `protection_mode="encrypt"` on `finalize_document`): `uvx --from adeu adeu-server`33 - Python CLI only (for scripted/headless pipelines): `uv tool install adeu`3435Do not present these as options to the user mid-task. Pick the available path and proceed.3637## Core workflow3839Every redlining task follows the same shape. Follow it in order:40411. **Read first.** Always read the document before editing. Use `read_docx` (MCP) or `uvx adeu extract` (CLI). For long contracts, start with `mode="outline"` to see the heading structure, then read specific pages.422. **Plan the edits.** Each edit is either a search-and-replace (most common), an accept/reject of an existing tracked change by ID, a reply to a comment by ID, or a structural table edit. Write the plan down explicitly before applying.433. **Apply as one batch.** Send all edits in a single `process_document_batch` call (MCP) or one `adeu apply` invocation (CLI). Edits apply _sequentially_: each edit evaluates against the document state produced by the edits before it, so dependent edits may be chained — a later edit must target the text as it reads _after_ the earlier edits.444. **Verify.** If the user asked for a specific outcome, re-read the modified file with `clean_view=true` (MCP) or `--clean` (CLI) and confirm.4546Batches are transactional: if any edit fails validation, the whole batch is rejected, nothing is written, and the error reports per-edit failures you can correct and resubmit.4748## Critical gotchas4950These are environment-specific facts that will trip you up if you assume Word/`.docx` behaves like plain text. Read this section every time.5152- **IDs are session-bound.** Change IDs (`Chg:12`) and comment IDs (`Com:5`) shift every time the document state changes. Before any `accept`, `reject`, or `reply` action, call `read_docx` _immediately_ before the batch. Never reuse IDs from earlier in the conversation. Never reuse IDs across a save/reload boundary.5354- **Batches apply sequentially and reject transactionally.** You can rename `X → Y` and then in the same batch modify `Y` — but the second edit must target `Y` (the text as it reads after the rename), not the original `X` wording. Stale targets fail validation, and any validation failure rejects the whole batch (nothing is applied) with per-edit errors explaining what to fix.5556- **`target_text` must be unique by default.** `match_mode: "strict"` (the default) requires a single match. Either add surrounding context to disambiguate, or explicitly set `match_mode: "first"` or `"all"`. Set `regex: true` to use a regular expression; capture groups are available as `$1`, `$2` in `new_text`.5758- **Do not write CriticMarkup tags manually.** Never put `{++`, `{--`, `{>>`, or `{==` into `new_text`. Use the `comment` field on the edit to attach a margin comment. Adeu generates the tracked-change XML from your plain replacement text.5960- **`new_text` supports Markdown.** Headings (`#` through `######`), `**bold**`, `_italic_` (not `*italic*` — strictly underscores), and `\n\n` to split into paragraphs. Empty string deletes.6162- **Read the appendix before editing structural references.** `read_docx` projects a semantic appendix at the bottom of the document containing defined terms, cross-references (`[~text~](#_Ref)`), internal anchors (`{#_BookmarkName}`), and footnotes (`[^fn-id]`). Anything inside the `<!-- READONLY_BOUNDARY_START -->` marker is read-only — attempting to modify it via search-and-replace will be rejected. Use `mode="appendix"` to see it explicitly.6364- **`clean_view` toggles the document state you see.** `clean_view=false` (default) shows the _raw_ document with all pending tracked changes inline as CriticMarkup. `clean_view=true` shows what the document would look like if every pending change were accepted. Choose deliberately — comparing the wrong view to user intent is the most common source of confusion.6566- **Page indexing.** `page=N` paginates the body. `page='all'` or omitting `page` with a `search_query` searches the whole document. Don't assume page numbers from the user's PDF viewer match Adeu's pagination — they often don't.6768- **Live Word (Windows COM) is Python-only.** If the user is editing the active document in Word, only the Python `adeu` server supports it. The Node server does not. Table row inserts/deletes are also not supported in Live Word mode — fall back to disk editing.6970- **Multi-author redlines.** If the document has tracked changes from multiple authors, edits that overlap another author's pending insertion are rejected to prevent silent destruction of their work. Tell the user; don't try to force it.7172## Edit types — quick reference7374Use `references/mcp-tools.md` for the full schema. The five operations:7576| Type | Purpose | Required fields |77| --------------------------- | -------------------------------------- | ------------------------------------------------------------------------------ |78| `modify` | Search-and-replace as a tracked change | `target_text`, `new_text` |79| `accept` | Finalize an existing tracked change | `target_id` (e.g. `Chg:12`) |80| `reject` | Revert an existing tracked change | `target_id` |81| `reply` | Reply to an existing comment | `target_id` (e.g. `Com:5`), `text` |82| `insert_row` / `delete_row` | Add or remove a table row | `target_text` (a cell value to anchor on), plus `position`/`cells` for inserts |8384`comment` is optional on `modify`/`accept`/`reject` to attach a margin comment.8586## Reference loading8788Load these only when relevant — they're not part of the base context:8990- **`references/mcp-tools.md`** — full MCP tool schemas, parameter details, `process_document_batch` discriminated union. Load before planning any non-trivial edit batch on the MCP path.91- **`references/cli-fallback.md`** — `uvx adeu` subcommands and the `edits.json` shape. Load on the CLI path.92- **`references/criticmarkup.md`** — CriticMarkup syntax and Adeu's semantic projections (footnotes, cross-refs, anchors, defined-terms appendix). Load when interpreting raw `read_docx` output or when the user asks about a marker like `[^fn-3]` or `{#_BookmarkName}`.
dealfluence