Skip to content

professional-appointment-manager

Generate and manage professional appointment documents - full lifecycle from draft to amendable Word file to final styled Typst PDF, plus Typst-native drafting of forensic legal reviews, commercial advisory reports, and appointment contracts (29-clause + 8-schedule structure, dual-column party blocks, hanging clause engine). Use when asked to create, edit, or convert a professional appointment/consultancy agreement, legal review, or advisory report.

Source: .opencode/skills/professional-appointment-manager/SKILL.md — site rebuilt 2026-09-05.

Professional Appointment Manager

This skill governs the entire lifecycle of a professional appointment document. It is a full round-trip workflow capable of generating drafts in Microsoft Word (using a mathematically locked HTML matrix), extracting amendments from that Word file back into Markdown, and compiling the final document to a premium PDF using Typst. For Typst-native drafting (no Word round-trip), it also carries the master templates/appointment_template.typ (29 clauses + 8 schedules) and the cover/geometry fragment resources/template.typ.

Dependencies

  • Pandoc
  • Typst
  • Python (with python-docx installed)

Workflow

When the user asks to create, draft, or finalize a professional appointment, follow these steps:

1. Information Gathering (OKF Extraction)

  • Check if the user has provided source material (e.g., a term sheet, email, or draft contract) to extract placeholder information from.
  • Read templates/okf_structure.json in the skill directory to see what values are required.
  • If information is missing (e.g., Client Name, Consultant Name, Dates, Fees), explicitly ask the user for it. Do not guess.
  • Once all data is gathered, compile it into a JSON file in your scratch workspace (e.g., config.json), mapping the exact placeholder string (e.g., "CLIENT COMPANY NAME") to the extracted value.
  • CRITICAL: Ask the user for final approval on the JSON configuration before generating anything.

2. Generate Word Document (Draft)

Once the JSON configuration is approved: - Pick the appropriate markdown template from templates/ based on the user's requirement (e.g., Architect, Principal-Designer, M&E, Structural-Engineer, BSR/Non-BSR, England/Scotland). - Run the CLI script to generate the locked Word document: 

python "<this skill's base directory>\scripts\manager.py" generate-word --input "path\to\template.md" --config "path\to\config.json" --output "draft_appointment.docx"
- Deliver the draft_appointment.docx to the user. Inform them they can amend it and return it for finalization.

3. Sync and Finalize (PDF Generation)

When the user returns an amended .docx file and asks to finalize it: - Use the CLI script to sync the amendments back into Markdown: 

python "<this skill's base directory>\scripts\manager.py" sync-from-word --input "amended_appointment.docx" --output "amended_appointment.md"
- Then, compile the amended Markdown into the final premium Typst PDF (no config is needed here if the placeholders were already replaced in step 2, but you can pass it if necessary): 
python "<this skill's base directory>\scripts\manager.py" generate-pdf --input "amended_appointment.md" --output "final_appointment.pdf"
- Deliver the final_appointment.pdf to the user.

Typst-Native Path (no Word round-trip)

For a direct Typst draft (legal review, advisory report, or appointment contract), bypass the Word stage: 1. Apply templates/okf_structure.json to extract all required entities from the user's source material; present the mapping for approval. 2. Inject the placeholders into templates/appointment_template.typ (the master: cover page, TOC, 29-clause body, Scotland/England execution blocks, Schedules 1-8). 3. Use resources/template.typ for the cover-page geometry and clause-engine functions when building a fresh .typ file. 4. Compile with typst compile <file>.typ <file>.pdf.

Document Architecture (8-part sequence, Typst-native)

  1. Cover page: 3cm uniform margins, clinical serif typography with fallbacks ("Libertinus Serif", "Times New Roman", "Georgia"), top-left grayscale logo (@preview/grayness:0.7.0), right-aligned title block, metadata grid (Client, Consultant, Date, Reference), horizontal rule, single-line imprint footer (The Building Law Practice Limited | Greenlaw Works, 6 S Greenlaw Way, Glasgow G77 6EF).
  2. Report geometry restore: 4.5cm left margin for binder binding, running top header and bottom page counter from Page 2+.
  3. Table of Contents: #outline(title: [Table of Contents], indent: 1.5em, depth: 2).
  4. 29-Clause Agreement Body via the #cl(num, body) hanging clause engine (dynamic level nesting, dx: -2.2cm primary numbers, grid indenting for sub-clauses).
  5. Execution Blocks (Scotland / England).
  6. Schedules 1-8 (BIM Protocol, Fees/Instalments/Time Charges, Personnel, Collateral Warranty, Third Party Agreements, Professional Team, Novation Agreement).

Typst Manual & Reference

Before drafting or when unsure of any Typst function, parameter, or syntax, consult the local, searchable mirror of the official Typst documentation at the _typst-manual folder (sibling of the skills root; from this skill's directory: ..\_typst-manual\).

  • Function/element/type reference (e.g. #outline, #counter, #block, #grid, #set, #pagebreak, #text, #image-grayscale, v, h, footnotes): search the Rust doc comments under _typst-manual\typst-src\crates\typst-library\src\ — every library item's full documentation and examples live there directly above its definition.
  • Language / syntax / scripting (#let, #set, #show, markup, math, context): _typst-manual\typst-src\docs\content\reference\language\*.typ and tutorial\.
  • Tutorials & guides: _typst-manual\typst-src\docs\content\tutorial\ and guides\.

See _typst-manual\README.md for lookup guidance.

Self-Learning: Runtime Environment Probe (RUN FIRST)

Before generating ANY document, probe the actual environment so you never ship a font or package that does not exist (Typst silently falls back, causing font discrepancies between the preview and the intended design):

powershell -ExecutionPolicy Bypass -File "..\_typst-manual\probe-fonts.ps1"

Read the output and the persisted report _typst-manual\font-probe-report.json. Then:

  • Rewrite every font stack so its FIRST member is an installed font from the report (e.g. this machine lacks Linux Libertine/Liberation Serif, so prefer a real installed serif such as Libertinus Serif, Georgia, Cambria, Palatino Linotype, or Times New Roman). Never leave a missing font as the leading choice.
  • Verify each @preview/... import is reported as cached; if missing, note that compilation needs network or the package must be cached first.
  • Only after resolving fonts/packages should you compile and generate the preview.

Utility Scripts

The central brain is scripts/manager.py. It exposes: - generate-word: Wraps Markdown into a strictly mathematically locked HTML matrix to enforce hanging indents and hard page breaks in MS Word. - sync-from-word: Pulls clean Markdown structure out of an amended MS Word file. - generate-pdf: Compiles Markdown into a beautifully styled Typst PDF (embedded header + clause engine, Scotland/England execution blocks).

Common Mistakes

  • Proceeding to generate the document without explicitly verifying the extracted JSON data with the user.
  • Using standard pandoc commands instead of the manager.py script; the script handles the proprietary HTML Matrix logic and python-docx hard page breaks.