Brand DOCX

brand-docx

Use this skill when the user wants a reusable Word brand kit or wants to create a new on-brand .docx from a company template and variable content.

This is an AI-agent skill for Codex and Claude Code. The user should not need to write JSON or run shell commands. The agent converts the user's content into an IntermediateDocument, invokes the internal engine, verifies the output, and returns the generated .docx.

The seven verbs: three deterministic + four model-assisted

Every brand skill (brand-docx, brand-pptx, brand-xlsx) implements the same contract. The deterministic core is extract / verify / generate; on top of it sit the optional learning verbs comprehend / learn / propose-overrides / refine, each fail-closed (the engine validates every proposal and authors every value).

comprehend is optional: generate works on the deterministic profile alone. When a current comprehension is present, generate additionally reconciles the template's preserved cover/index structures with the new content. See reference/comprehension.md for the full step.

Hard Rules

• Treat python scripts/cli.py ... as an internal engine command, not the user-facing workflow.
• scripts/cli.py is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set BRAND_DOCS_ROOT to override). Never guess deeper paths like scripts/brandkit/....
• Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
• Extract opens the source template read-only and saves brand-kit/<name>/template/shell.docx byte-for-byte.
• Generate opens the saved shell and resolves every semantic block through profile.json.
• Do not put style names, colors, fonts, or brand identifiers in an IntermediateDocument.
• If the user did not provide a template or enough content, ask for the missing input.
• Return the generated file path plus a QA summary.
• Consult profile.json.artifact_catalog before generation when the user asks to mimic a specific piece of the template.

Preflight (always first)

Before doing any work, run:

python scripts/cli.py doctor

Use its output to decide the run mode:

• If a required Python dependency is missing, install/repair it before extraction or generation; the core engine is not ready.
• If only visual renderers are missing or unusable (soffice plus pdftoppm or optional PyMuPDF/fitz), the core L0 workflow can still run, but a full visual audit cannot be claimed. Tell the user what is missing, include the install/repair hint printed by doctor, and either proceed with degraded QA or install the renderer first.
• If optional OCR (tesseract) is missing, the visual audit can still run, but rendered residual-text proof is incomplete. Report that limitation when judging stale placeholders or field caches.
• For --qa deep or --qa strict, prefer repairing/installing renderers before generation. If the environment cannot run them, deep generates a degraded manifest and strict fails with a visual proof blocker.

Agent Workflow

1. Run the dependency preflight above and report any degraded capability.
2. Determine the brand name and locate the user-provided .docx template.
3. If no matching brand-kit/<name> exists, extract one.
4. Comprehend the template (optional, model-driven; see below). Skip when a current comprehension is already cached or no model is available.
5. Convert the user's requested content into IntermediateDocument JSON.
6. Generate the .docx with the internal engine.
7. Run QA and report any warnings honestly.
8. Feedback (only after returning the file): invite a refinement of the understanding for future documents (see below).

Before generation, inspect profile.json.artifact_catalog when the user asks to mimic a specific template piece. It records OOXML parts, media parts, paragraph/table styles, style details, sections/margins, paragraph samples, and table counts.

Authoring the IntermediateDocument

The IDoc is where "correct document" becomes "great document". Author it role-first, against the profile, never style-first:

1. Read brand-kit/<name>/PROFILE.md before writing a block. It lists the role table (with scope, placement, required slots), the brand palette tokens, and the template's structural order. Choose every block by MEANING from that table; the engine resolves it to the template's own artifacts.
2. Respect the skeleton. Cover fields first (cover.title, cover.subtitle, extra cover fields), a toc block only where the template keeps one, then the freeform body.
3. Shape the body for the reader. One heading level 1 per major section and a real 1-2-3 hierarchy below it (the TOC regenerates from exactly these headings); paragraphs of 2-5 sentences; list blocks for enumerations (bullet for unordered, number for sequences); every table and image with a caption block so derived indexes regenerate from real content; callout sparingly, for genuinely load-bearing notes; quote only for actual quotations.
4. Color discipline. The named style already carries the brand: the default is NO run color. When emphasis is truly needed, reference a palette role (primary, text, ...) or a theme slot (accent1) from PROFILE.md, never a hex.
5. Reuse before re-deriving. When a comprehension is present, prefer its component / section fragments (comprehension.fragments in profile.json) with {{slot}} values over hand-building a recurring layout.
6. Never name a style, font, size, or hex. If a block needs something the role table cannot express, say so in the QA summary instead of inventing formatting: the resolver is the only author of values.

Feedback (end of generation)

Ask for feedback only after you have returned the generated .docx and its QA summary - never before or during generation. Invite the user to reply with text or a screenshot of the document, and name the roles, palette colors, and sections you actually used so the answer is concrete. A screenshot is your own multimodal read; the engine only ever ingests the structured JSON delta you distil from it.

Turn the answer into a small refinement delta of verbatim ids and merge it with the refine verb (see reference/comprehension.md):

python scripts/cli.py refine --name <brand> --input refinement.json --accept

A refinement improves FUTURE generations of this brand only - it mutates the saved profile, never the .docx you just produced. To apply it, generate again.

When the SAME QA finding recurs across runs, you can also propose a shell-bound correction with propose-overrides: the comprehend-input bundle surfaces the recurring generation_history, and you NAME a shell-backed re-point (a stub role to an existing healthy role, a number_format mask the shell uses, or a captured demo value) that the engine binds fail-closed (see reference/comprehension.md). It is advisory until --accept, improves FUTURE generations only, and every live correction surfaces as an INFO override_applied finding in QA.