DocCraft

Overview

Use this skill in two layers:

1. 1. Build grounded text from source materials and a target framework.
2. If needed, create or revise the final .docx deliverable.

Keep Markdown or plain text as the working source of truth until the wording and structure are stable. Move into DOCX creation, formatting, tracked changes, or comments only after the content is sufficiently mature.

This skill vendors the DOCX capability locally. Do not assume a separate $docx skill is installed.

Some upload targets reject bundled OOXML schema files such as .xsd. When preparing a publishable package, use the packaged upload-safe variant from this skill. That variant keeps document generation and editing workflows, but omits the strict schema-validation bundle.

When the final deliverable is a Word document, always determine the format authority before finalization:

1. 1. User-provided template or existing target document.
2. Explicit written formatting requirements from the user.
3. An accepted sample deliverable in the same domain.
4. The default format profile in this skill.

Workflow Decision Tree

A. Build a new document from existing materials

Use the source-grounded text workflow:

1. 1. Normalize the task inputs.
2. Build a source manifest.
3. Create section briefs from the target outline.
4. Draft section files.
5. Run document-level consistency review.
6. Assemble the final Markdown or text output.

B. Read, create, or edit a Word document

Use the DOCX workflows in this skill:

1. 1. Read existing .docx content with pandoc when text extraction is enough.
2. Create a new .docx from scratch only after fully reading docx-js.md.
3. Edit or redline existing .docx files only after fully reading ooxml.md.
4. Default to tracked changes or comments for government, legal, academic, commercial, or third-party documents.

C. Do both

Split the work into phases:

1. 1. Draft and stabilize text first.
2. Freeze the source-backed wording.
3. Move into .docx generation or .docx editing.

Do not mix heavy content generation and low-level OOXML editing in the same pass unless the task is trivial.

Source-Grounded Text Workflow

1. Normalize the inputs

Confirm these four inputs before drafting:

• - Source corpus: directories and files that contain the facts.
• Target structure: required outline, template, or chapter list.
• Writing rules: tone, exclusions, terminology, formatting, review constraints.
• Output contract: section files, merged Markdown, DOCX, review memo, or tracked-change file.

If any input is missing, infer the minimum safe default and state the assumption in the working notes, not in the final deliverable.

If the output contract includes .docx, also determine the format authority early. Read references/word-format-profile.md and use scripts/initformatprofile.py when a format profile needs to be captured or confirmed.

If the task is to produce a formal, complete Word deliverable, capture a delivery brief before drafting. Read references/word-delivery-brief.md and use scripts/initdeliverybrief.py to record what the user must specify and what still needs confirmation.

2. Build a source manifest

Before writing, create a manifest of the available materials. Read references/source-manifest.md when the corpus has more than a few files.

Use scripts/build_manifest.py to generate a first-pass inventory. Then enrich or trim it manually as needed.

The manifest should separate:

• - Authoritative source files.
• Derivative files such as extracted text, drafts, or previous outputs.
• Template or outline files.
• Files that are only useful for lookup, not for quoting.

3. Create section briefs

Do not draft directly from a large corpus into the final chapters. First create a section brief for each target section.

Read references/section-briefs.md when building the planning layer. Use scripts/plansections.py to bootstrap the outline into brief stubs.

Each section brief should contain at least:

• - Section id and title.
• Purpose of the section.
• Must-cover points.
• Allowed generic material.
• Primary and secondary sources.
• Expected figures, tables, and checklists.
• Exclusions and collision boundaries with nearby sections.
• Open questions or unresolved source gaps.

For large projects, section briefs are the shared contract between multiple agents.

4. Draft sections

Read references/drafting-rules.md before drafting.

Draft against the section brief, not against the whole corpus. This keeps the writing grounded and reduces repetition.

Rules:

• - Keep verifiable facts tied to source material.
• Allow generic boilerplate only for management, quality, safety, process, or industry-standard measures that do not conflict with the source corpus.
• Prefer concrete implementation language over slogan-style abstractions.
• Integrate figures and tables into nearby prose. Do not create headings that only say "figure" or "table".
• If the final deliverable must not show source notes, keep any evidence notes in working files only.

5. Run consistency review

Read references/consistency-review.md before merging the full document.

Run a full-pass review for:

• - Terminology consistency.
• Number, quantity, scope, and interface consistency.
• Duplicate or contradictory paragraphs.
• Section boundary collisions.
• Heading numbering and naming consistency.
• Hidden source labels that should not appear in final copy.

6. Assemble the output

Use scripts/assemble_markdown.py to merge ordered chapter files into a single Markdown draft when needed.

Keep a clear distinction between:

• - Working drafts with evidence or TODO notes.
• Clean deliverables prepared for DOCX conversion.

Default Execution Pattern

Single-agent mode

Default to a single agent when:

• - The outline is short.
• The source corpus is small.
• Cross-section dependencies are high.
• The user mainly wants a coherent draft, not parallel throughput.

Multi-agent mode

Use multiple agents only when:

• - The source corpus is large.
• Sections are sufficiently independent.
• A shared glossary, writing rules, and section-brief set can be produced first.

In multi-agent mode, create these shared artifacts before splitting work:

1. 1. Source manifest.
2. Section brief pack.
3. Glossary or terminology list if naming is fragile.
4. Shared writing rules.

Do not let agents improvise different naming systems, evidence rules, or section boundaries.

DOCX Workflows

Read or analyze .docx

If only the text is needed, convert the file with:

CODEBLOCK0

If structure, comments, media, or tracked changes matter, unpack the OOXML package and inspect the XML.

Create a new .docx

Before writing any code, fully read docx-js.md without truncation.

Use the bundled docx JavaScript workflow when:

• - Creating a new Word document from stable text.
• Rebuilding a formatted deliverable from Markdown or structured content.
• Generating tables, headings, page settings, headers, or footers programmatically.

Before final DOCX generation, lock the format profile. If no authoritative template exists, use the default profile in references/word-format-profile.md.

Before final DOCX generation, also resolve the delivery brief items that affect document completeness, review mode, and output packaging.

Before final DOCX generation, run scripts/resolvewordjob.py or follow references/word-assembly-plan.md to determine whether the Word job is actually ready for delivery, which package components will be generated, and which blockers remain.