jaw-docx

# DOCX Skill Use this skill for any `.docx` task: create, read, edit, review, template-fill, or QA verification. Triggers: `"Word doc"`, `".docx"`, reports, memos, letters, templates. **OfficeCLI routing and consent rule:** - First check whether `officecli` is available with a probe that works in the agent's actual shell: `command -v officecli` on POSIX, `Get-Command officecli -ErrorAction SilentlyContinue` in PowerShell. **`command -v` is not a PowerShell builtin or cmdlet** — on Windows it prints nothing, sets no exit code, and raises no error, so it is indistinguishable from "not installed" and the agent asks to install a tool that is already there (#298). `officecli --version` is the portable fallback: a non-zero exit or no output means missing. - If installed, recommend OfficeCLI first for high-fidelity DOCX mutations, validation, query, batch/resident flows, track changes, and CJK/rhwp-aware work. - If missing, do not auto-install. Present choices before proceeding: 1. Install forked OfficeCLI from `https://github.com/lidge-jun/OfficeCLI` via `bash "$(npm root -g)/cli-jaw/scripts/install-officecli.sh"`. 2. Continue with lightweight fallback tools for the current task, with limitations stated. 3. Stop or cancel. - Before taking a lightweight fallback path, ask the user again and state what fidelity/features may be lost. - If the user chooses lightweight mode, save that preference to memory for future Office work. - Use upstream/vanilla `iOfficeAI/OfficeCLI` only when the user explicitly asks for upstream behavior. OfficeCLI is the recommended advanced backend for add/set/remove, validate, query, and track-change accept/reject workflows. Lightweight fallback: **Python OOXML scripts** (`scripts/*.py`) for what OfficeCLI cannot do, or when the user chooses lightweight mode: tracked-change **creation**, OMML equations, bulk pattern matching, unpack/edit/repack. See §3. **DOCX only.** Do NOT use this skill for PDFs, spreadsheets, HWPX, Google Docs, or any other format. **OfficeCLI discovery rule:** before guessing paths, element names, or properties, ask the installed CLI. Use `officecli --help` for workflow entry points and `officecli help docx ... --json` for machine-readable schema. **Same-file execution rule:** run OfficeCLI commands against the same `.docx` sequentially. Do not run `officecli view`, `officecli validate`, `officecli query`, or `officecli get` in parallel against one package. If a file lock occurs, stop and report the exact command and path before making a copy or retrying. --- ## 1. Quick Decision | Task | Tool | Command pattern | Notes | |------|------|-----------------|-------| | **Format like existing doc** | shell + officecli | `cp source.docx target.docx && officecli open target.docx` | **Inherit styles/headers/footers. See §2.** | | Create blank DOCX | officecli | `officecli create report.docx` | Start from real Office file | | Add paragraph | officecli | `officecli add FILE /body --type paragraph --prop text="..."` | Primary write path | | Edit paragraph/run | officecli | `officecli set FILE /body/p[N] --prop ...` | Exact path targeting | | Read text/outline/stats | officecli | `officecli view FILE text` | Modes: `text`, `annotated`, `outline`, `stats`, `issues`, `html` | | Query document | officecli | `officecli query FILE "p[style=Heading1]"` | CSS-like selectors | | Template-safe replacement | officecli | `officecli set FILE / --prop find="{{X}}" --prop replace="Y"` | Preserves template structure | | Validation / issue scan | officecli | `officecli validate FILE` | Pair with `view FILE issues` | | Accept/reject tracked changes | officecli | `officecli set FILE / --prop accept-changes=all` | Also `reject-changes=all` | | **CREATE tracked changes** | officecli (native) | `add ... --prop revision.type=ins --prop revision.author=...` | **Native create + accept/reject** (v1.0.115); Python only for bulk redline diffs | | **OMML equations** | Python (L4) | Unpack → inject `<m:oMath>` → repack | **officecli cannot generate OMML** | | **Complex anchored comments** | Python (L3) | `python3 scripts/comment.py IN OUT --text "..." --anchor "..."` | For comments beyond officecli | | PDF conversion / visual QA | soffice | `soffice --headless --convert-to pdf FILE` | Screenshot-based QA | | Edit existing document | -- | Read [editing.md](./editing.md) | Detailed editing guides | | Create from scratch | -- | Read [creating.md](./creating.md) | Detailed creation recipes | --- ## 2. Reference-Based Editing (Edit > Create from Scratch) When the user says "format like X.docx", "match existing style", "based on template", or provides a source file — **start from the source file. Don't rebuild from scratch.** ### Workflow 1. **Copy the source**: `cp source.docx target.docx` — inherits all styles, margins, numbering, headers, footers 2. **Open** with `officecli open target.docx` — daemon starts; command returns immediately (do NOT run as `run_in_background` shell) 3. **Remove body content only** — keep `/styles`, `/numbering`, `/header`, `/footer` 4. **Add new paragraphs** using style names that already exist (e.g. `--prop style=Heading1`) — they auto-apply ### Why This Matters Pandoc-generated and Word-generated documents have specific style IDs (e.g. `Heading1`, `BodyText`, `FirstParagraph`) unique to that document. Adding a new style with the same name causes: - `officecli validate` errors about duplicate style IDs - Word/LibreOffice rendering falls back to defaults - The task takes 10× longer than necessary ### Template Sources (priority order) 1. **User-provided source file** — first-class template 2. **`tests/fixtures/*.docx`** — pre-built working examples shipped with this skill 3. **`officecli create`** blank — only when nothing else applies ### Example — Assignment Case ```bash # CORRECT: inherit Pandoc styles cp Assignment1.docx Assignment2.docx officecli open Assignment2.docx officecli remove Assignment2.docx "/body/p[1]" # remove old body (keep styles/headers/footers) # ... remove more paragraphs ... officecli add Assignment2.docx /body --type paragraph --prop text="New title" --prop style=Heading1 officecli close Assignment2.docx # WRONG: recreate styles that already exist — validate fails officecli add doc.docx /styles --type style --prop name=Heading1 --prop size=20pt ... ``` --- ## 3. Reference Materials & Script Map officecli covers most DOCX tasks. For the rest, use these reference docs + Python scripts. ### References (`references/`) | File | Read when | Contains | |------|-----------|----------| | `references/cjk-handling.md` | Korean text / East Asian font / wrapping issues | `rFonts` East Asian fonts, `lang` tags, accessibility | | `references/tracked-changes.md` | Track changes / comments / redline work | `w:ins`, `w:del`, comments XML, script usage examples | | `references/docx-js-api.md` | **DEPRECATED** — npm `docx` library API, not applicable to officecli ecosystem | Ignore — kept for historical reference only | ### Scripts (`scripts/`) — Python OOXML Toolkit | Script | Run when | Command | |--------|----------|---------| | `scripts/docx_cli.py` | Unified Python CLI — unpack, save, validate, repair, search, TOC, chunk, comment, accept-changes, merge-runs | `python3 scripts/docx_cli.py {open\|save\|validate\|repair\|text\|search\|toc\|chunk\|comment\|accept-changes\|merge-runs}` | | `scripts/accept_changes.py` | Accept all tracked changes (alternative to officecli) | `python3 scripts/accept_changes.py IN.docx OUT.docx` | | `scripts/comment.py` | Add W3C-compliant OOXML comments anchored to text | `python3 scripts/comment.py IN.docx OUT.docx --text "..." --anchor "..."` | | `scripts/ooxml/merge_runs.py` | Merge adjacent runs with identical formatting (post-edit cleanup) | `python3 scripts/ooxml/merge_runs.py unpacked/` | | `scripts/ooxml/redline_diff.py` | Validate tracked-change correctness vs original | `python3 scripts/ooxml/redline_diff.py unpacked/ original.docx` | | `scripts/ooxml/simplify_tracked.py` | Simplify same-author adjacent tracked changes | `python3 scripts/ooxml/simplify_tracked.py unpacked/` | ### Editing Escalation Ladder When officecli can't do the job, escalate in this order: | Level | When | Tool | |-------|------|------| | **L1** officecli high-level | Typical add/set/remove operations | `officecli add/set/remove/query/view` | | **L2** officecli `raw-set` | XML injection — PAGE field, fldChar, hyperlink anchor, custom attributes | `officecli raw-set FILE PATH --xpath X --action A --xml ...` | | **L3** Python script | Bulk tracked-change ops, comment add, merge runs, redline validation | `python3 scripts/*.py` | | **L4** Unpack → edit XML → repack | OMML equations, custom style injection, pattern-match editing, anything L1-L3 can't reach | `scripts/docx_cli.py open FILE work/` → edit `work/word/*.xml` → `scripts/docx_cli.py save work/ OUT.docx` | **Escalation signals:** - officecli shows **"silently ignored"** → **L2** (raw-set) - Need **OMML/MathML equations** → **L4** (inject `<m:oMath>` XML — officecli cannot generate these) - Need to **CREATE** tracked changes (officecli only accepts/rejects) → **L3** or **L4** - **Bulk find/replace** across 100+ targets → **L3** (`docx_cli.py search/replace`) - **Pandoc-generated** doc with custom style IDs → **§2 Reference-Based Editing** first - Task **still fails after L1+L2** → Read relevant `references/*.md` BEFORE giving up --- ## 4. Subskill References Additional detail lives in companion files. Load only the one you need. | Subskill | Path | When to use | |----------|------|-------------| | **officecli-academic-paper** | `./officecli-academic-paper/SKILL.md` | Academic papers, citations, bibliography, TOC for papers | | **creating.md** | `./creating.md` | Detailed creation recipes (new documents from scratch) | | **editing.md** | `./editing.md` | Detailed editing guides (modify existing documents) | ### Decision flow ``` Is the document an academic paper (thesis, journal, conference)? YES --> read officecli-academic-paper/SKILL.md NO --> continue with this file User provided a source file to match? YES --> §2 Reference-Based Editing + ./editing.md NO --> ./creating.md ``` --- ## 5. Design Principles for Business Documents ### 5.0 Design Read & Document Anti-Slop **Intent discovery (before building):** ask audience (board / exec / internal team / public), formality register (formal report · memo · whitepaper · proposal), and density (dense reference vs spacious) — then match the type scale, palette restraint, and whitespace. If the user names a target ("McKinsey-style", "academic", "startup memo"), map to it. **Named document anti-slop (AI-tells — pattern → fix):** 1. **Calibri-everything** — single default font → a deliberate heading+body pair (§5.3), committed. 2. **Fake-heading bold** — manual bold+size instead of real styles → use Heading 1/2/3 styles (§5.1) so TOC/navigation work. 3. **Wall of text** — dense unbroken prose → break into lists, callouts, tables, sectioned headings. 4. **Default-Word-template look** — no palette/style identity → a restrained palette (§5.2) + consistent scale. 5. **Over-coloring** — many accents / colored body text → one accent; body near-black. 6. **Justified-everything + orphan headings** — full-justify body, headings stranded at page bottom → left-align body; keep headings with content. 7. **Placeholder leakage** — "Acme Corp"/lorem/TBD in delivered output → realistic specific content, never invented data. > Named palettes + font pairings + personality→doc-type map: `references/design-system.md`. ### 5.1 Heading Hierarchy - **H1**: Document title (one per document) - **H2**: Major sections - **H3**: Subsections under H2 - Never skip levels (H1 -> H3 is invalid). Table of Contents depends on correct heading structure. ```bash # Verify heading hierarchy officecli view report.docx outline ``` ### 5.2 Color Palette Use professional, muted tones only: | Purpose | Allowed colors | Hex examples | |---------|---------------|--------------| | Headings, emphasis | Navy | `#003366`, `#1B2A4A` | | Body accents, borders | Charcoal | `#333333`, `#4A4A4A` | | Highlights, callouts | Forest green | `#2E5E3F`, `#1A4731` | **NEVER** use rainbow colors, bright primary colors, or more than 3 accent colors in a single document. ### 5.3 Font Selection | Script | Primary font | Fallback | |--------|-------------|----------| | Korean | Malgun Gothic | Pretendard | | English / Latin | Calibri | Aptos | The CJK fork auto-applies East Asian fonts, but verify with: ```bash officecli raw report.docx /document | grep rFonts ``` ### 5.4 Typography