typst-planner

Plan ANY Typst document before drafting — classify the document type, route to the correct typst generator skill, gather every required variable binding, and emit a structured plan for sign-off. Use when the user asks to create, draft, generate, or produce any Typst document (letter, report, adjudication pleading, building contract, appointment). Gate the drafting.

Source: .opencode/skills/typst-planner/SKILL.md — site rebuilt 2026-09-05.

Typst Planner — the plan-gate for every Typst document¶

MANDATORY RULE: before ANY Typst work is done, it MUST be planned. No .typ file is written, no typst compile is run, and no typst generator skill is invoked until a typst-planner plan has been emitted AND signed off by the user. This is a hard gate, not a suggestion — drafting without a plan is forbidden.

This skill is the entry point for any request to produce a Typst document in the OKF workspace. It does not itself draft. It classifies the request, routes it to the correct typst generator skill, gathers the variable bindings that generator needs, and emits a single structured plan that the user signs off before any .typ is written.

This mirrors the drafting discipline of submission-planner (plan-gate before drafting): nothing is generated until the plan is approved. It is the typst family's equivalent of a submission plan — it turns "make me a letter/contract/report" into a concrete, parameter-complete brief for one of the generator skills below.

The "typst expert" knowledge this skill carries is the shared institutional memory of the whole typst family (the four generator skills plus the _typst-manual docs mirror), consolidated so a planner can route correctly without opening each generator first.

0. When to use this skill¶

Trigger typst-planner whenever the user asks for a Typst output, including: - "draft a letter / report / contract / adjudication pleading in Typst" - "make me a [document] as a pdf" where the workspace convention is Typst - any request naming a .typ file or the typst tool - "plan the typst document first" / "what do I need for this typst doc"

If the user has already specified the exact generator and supplied all variables, you may skip straight to that generator — but still route through this planner's plan step so the brief is explicit and the font/package probe (Step 2) is not missed.

1. Step 0 — Classify and route¶

Pick exactly ONE target generator. Use this routing table:

Document the user wants	Route to skill	Document-type variable
Formal legal letter / correspondence / statutory notice on firm letterhead	`typst-letter-generator`	(letter)
Legal/regulatory report, review, or contract document with hanging clause engine	`typst-report-generator`	(report)
Adjudication pleading: Notice of Adjudication, Referral, Response, Reply, Rejoinder, Surrejoinder, Rebutter	`typst-adjudication-generator`	`document-type` (NoA / REFERRAL / RESPONSE / REPLY / REJOINDER / SURREJOINDER / REBUTTER)
Building / sub-contract agreement with Scots execution block	`typst-building-contract-generator`	(contract)
Professional appointment / engagement (Word lifecycle + Typst-native master)	`professional-appointment-manager`	(appointment)

If the request is ambiguous (e.g. "a document about the dispute"), ask the user which of the five families it falls into before proceeding. Never guess the document type silently.

2. Step 1 — Gather the required variable bindings¶

Each generator needs a fixed set of bindings at the top of its .typ. Collect them now; the plan is incomplete until every required field is filled or explicitly marked "to be supplied by user". Do not draft with gaps.

Letter (`typst-letter-generator`)¶

Recipient name / firm
Recipient address (and email line)
Date
Our Ref
Salutation (Dear Sirs, / Dear [Name],)
Subject / Re: block
Confidentiality line (STRICTLY PRIVATE & CONFIDENTIAL)
Sign-off role (Solicitors for the [Party])
Body structure: which #sec(...) sections and #item(...) numbered paragraphs

Report (`typst-report-generator`)¶

Cover title + metadata block (client, ref, date, author)
Section sequence (clause engine #cl("P.1", [...]), #cl("1.1.1", [...]))
TOC required? (yes by default)
Any unnumbered verbatim front section (e.g. a Letter of Instruction) — note it explicitly
Schedules (one per page)

Adjudication (`typst-adjudication-generator`)¶

document-type (see routing table)
Referring party + company no + address
Respondent + company no + address
Sequence fidelity check: which round this is (NoA → Referral → Response → Reply → Rejoinder → Surrejoinder → Rebutter); this doc must answer only the immediately preceding round
Exemplar to mirror (FORM ONLY — never content): check resources/Adjudication_Exemplars/CATALOG.md

Building contract (`typst-building-contract-generator`)¶

project-name
Contractor + company no
Subcontractor (or other second party) + company no
contract-sum
start-date
ref-no
Definitions list (#definition(term, def))
Execution parties (Scots law block)

Appointment (`professional-appointment-manager`)¶

Hand off to that skill; its own 29-clause + 8-schedule master template governs bindings.

3. Step 2 — environment probe (RUN FIRST, before compiling anything)¶

Before drafting, the generator must probe the machine so it never ships a missing font or package (Typst silently falls back, causing preview/design mismatch). The planner records this as a mandatory pre-compile step in the plan:

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

Read _typst-manual\font-probe-report.json and ensure every font stack's FIRST member is an installed font (this machine typically lacks Liberation Sans/Linux Libertine/Liberation Serif — prefer Arial, Libertinus Serif, Georgia, Cambria, Palatino Linotype, Times New Roman). Verify each @preview/... import is cached.

4. Step 3 — emit the plan (sign-off gate)¶

Output a plan in this shape. Do not open the generator skill / write .typ until the user approves.

TYPST DOCUMENT PLAN
===================
Target skill:   <generator from Step 1>
Document type:  <type/variable>
Output file:    <name>.typ  (+ previews\<name>-page-{0p}.png)
Grey scale:     YES (mandatory — no colour anywhere; greyscale logo via @preview/grayness)

VARIABLES (bindings)
--------------------
<each required field from Step 2, filled or marked "USER TO SUPPLY">

STRUCTURE / SEQUENCE
--------------------
<the document's section order, clause engine, schedules, sign-off>

FONT & PACKAGE PROBE
--------------------
probe-fonts.ps1 run: <pending / done>
leading fonts resolved to installed: <yes/no>
@preview imports cached: <yes/no>

PREVIEW WORKFLOW
----------------
compile -> previews\<name>-page-{0p}.png (--ppi 144) -> document_preview.md carousel

STATUS: AWAITING SIGN-OFF

Only after the user replies "go" / "approved" do you (a) load the target generator skill via the skill tool and (b) draft and compile.

5. Shared typst conventions (carry into every plan)¶

Greyscale mandate: every element black or luma(...) shade — never colour. Cover logo uses #image-grayscale(read("LOGO.png", encoding: none), width: 2.4cm) from @preview/grayness:0.7.0, never plain #image(...).
Docs mirror: when unsure of any Typst function/syntax, consult ..\_typst-manual\ (Rust doc comments under typst-src\crates\typst-library\src\; language/syntax under typst-src\docs\content\reference\language\*.typ and tutorial\). See _typst-manual\README.md.
Native preview: every generated document MUST be compiled to PNGs (typst compile <doc>.typ "previews\<doc>-page-{0p}.png" --ppi 144) and surfaced via a document_preview.md carousel artifact (UserFacing: true). For adjudication, append a unique version tag to the PNG filename so the UI does not cache stale images.
Exemplar discipline (adjudication only): exemplars in typst-adjudication-generator/resources/Adjudication_Exemplars/ are FORM ONLY — layout, numbering, signature blocks. Never echo their content (parties, sums, facts, phrasing).

6. Session learnings¶

Add here: routing edge cases, binding gaps that recur, font/pkg surprises found via the probe, sequencing lessons. Keep the plan-gate strict — a complete plan prevents the generator skills from silently falling back on missing fonts or guessing document type.