Canonical Markdown Authoring

canonical-markdown-authoring

Convert plain markdown contract drafts into OpenAgreements' canonical template.md authoring format. The canonical form is a single lawyer-editable file that compiles to a validated JSON contract spec plus a rendered DOCX via the shared template renderer.

Activation

Use this skill when the user wants to:

• Convert a plain-prose contract draft into a canonical OpenAgreements template.md
• Migrate an existing JSON-source template to canonical authoring
• Author a new template that compiles via npm run generate:templates
• Add or refactor a Defined Terms clause, oa:clause directives, or signer metadata
• Bring a template into parity with the Wyoming / Employee IP canonical patterns

This skill assumes:

• You are working inside an OpenAgreements repo checkout. Templates live at

content/templates//template.md.

• The shared canonical compiler (scripts/template_renderer/canonical-source.mjs)

and the cover-standard-signature-v1 layout are present.

Canonical structure overview

A canonical template.md has these parts in this order:

1. YAML frontmatter — template ID, source paths, layout, style, document

metadata, section labels.

1. # Title — H1 matching document.title in frontmatter.
2. ## Cover Terms — short subtitle paragraph followed by a

Kind | Label | Value | Show When table with {snake_case} field placeholders.

1. Optional recitals section — ``

followed by an H2 such as ## Recitals and one or more recital paragraphs.

1. Operative section — `` followed

by an author-chosen H2 such as ## Standard Terms, ## Resolutions, or ## Terms. Clauses live here, each preceded by `. The first clause should be Defined Terms with type=definitions` when a definitions clause is needed.

1. Signature section — `` followed by the

signature H2 and then `` plus the signer blocks.

Step-by-step conversion

Step 1 — Skeleton the frontmatter

---
template_id: openagreements-                # kebab-case, must match the directory slug
layout_id: cover-standard-signature-v1
style_id: openagreements-default-v1
outputs:
  docx: content/templates/openagreements-/template.docx
document:
  title:                          # MUST match the H1 below
  label: 
  version: "1.0"
  license: Free to use under CC BY 4.0
  defined_term_highlight_mode: definition_site_only   # see "Highlight modes"
  cover_row_height: 700
sections:
  cover_terms:
    section_label: Cover Terms
    heading_title: Cover Terms
  standard_terms:
    section_label: Standard Terms
    heading_title: Standard Terms
  signature:
    section_label: Signature Page
    heading_title: Signatures
---

Notes:

• Canonical sources do not declare source_json. npm run generate:templates

auto-discovers any content/templates//template.md whose frontmatter declares template_id, layout_id, and style_id, then writes the generated JSON to content/templates//.template.generated.json (a hidden, do-not-edit-by-hand artifact).

• Do not add output_markdown_path or outputs.markdown — the canonical

compiler rejects them. The canonical template.md is the source.

• For directive-backed sections, the body H2 that follows oa:section is the

rendered heading source of truth. Keep the frontmatter sections metadata in place, but treat the body heading as authoritative for the visible section title.

Step 2 — Title (H1)

# 

Keep the H1 text identical to document.title. There is no automatic cross-validation today, but drift between the two is a known footgun.

If the rendered title or section heading differs from the raw markdown, see "Sharp edges and renderer transforms" below for the body-vs.-frontmatter source-of-truth map.

Step 3 — Cover Terms section

Open with one short subtitle paragraph, then the Kind | Label | Value | Show When table:

## Cover Terms

The terms below are incorporated into and form part of this agreement.

| Kind | Label | Value | Show When |
| --- | --- | --- | --- |
| row | Company | {company_name} | always |
| row | Employee | {employee_name} | always |
| row | Effective Date | {effective_date} | always |
| group | Confidentiality |  | always |
| subrow | Trade Secrets Duration | {trade_secret_duration} | always |
| subrow | Other Confidential Information Duration | {other_confidentiality_duration} | confidentiality_other_included |

Rules:

• Kind is row, group, or subrow.
• row — single-line cover term.
• group — section header with no value (leave the Value column blank).
• subrow — child of the most recent group; rendered indented.
• Label is the lawyer-facing label.
• Value is either literal text or a {snake_case} field placeholder. Field

names must match ^[a-z_][a-z0-9_]*$.

• Show When:
• always — always rendered.
• `` — rendered only when the boolean field is truthy. The

field's name must satisfy ^[a-z_][a-z0-9_]*$.

Step 4 — Directive-anchored body sections

Every operative section starts with an oa:section directive. The H2 that follows may be author-chosen. Every clause inside the operative section then gets an oa:clause directive, a ### Heading, and prose paragraphs:

## Standard Terms

### Assignment of Inventions

Employee hereby assigns and agrees to assign to Company all right, title, and
interest in Covered Inventions, to the extent permitted by law.

### Non-Competition

During the Restricted Period, Employee must not engage in any Competitive Business
within the Restricted Territory.

If the document needs standalone WHEREAS-style recitals, author them in a separate recitals section before the operative section:

## Recitals

**WHEREAS**, Company is considering a financing transaction.

**WHEREAS**, the board has reviewed the proposed terms.

## Resolutions

oa:section types:

• standard_terms — required operative clause section
• signature — required signature section
• recitals — optional recital-only section

Directive attributes:

• id — slug, kebab-case, unique within the document. Used for stable

machine references.

• when= (optional) — clause is only included when the named

boolean field is truthy.

• omitted="" (optional) — text rendered in place of the body when

when evaluates false.

Step 4A — Present-tense IP assignment language

If a clause transfers inventions, work product, patent rights, copyrights, or other IP ownership, use a present-tense operative grant such as hereby assigns.

• Preferred baseline: Employee hereby assigns to Company all right, title, and interest in ...
• If future cooperation is also needed, add it after the present assignment:

... and will sign additional documents reasonably requested to confirm ownership.

• Do not rely on agrees to assign or will assign without a present-tense

grant. Federal Circuit contract law applied in the Stanford/Roche line of cases (FilmTec, DDB Techs, Rasmussen Instruments, the Federal Circuit decision in Stanford v. Roche, 583 F.3d 832) treats future-tense language as a promise to assign rather than a present transfer of rights — which diligence reviewers flag as a gap.

• This applies to employee invention-assignment agreements, contractor IP

assignment clauses, work-made-for-hire fallback assignments, and standalone assignment instruments. It does not apply to NDAs or services agreements without IP transfer.

• "Irrevocably" (e.g. hereby irrevocably assigns) is optional belt-and-

suspenders; "hereby assigns" is the doctrinal minimum.

Step 5 — Defined Terms clause (use when it earns its keep)

Use a Defined Terms clause as the first clause in the oa:section type=standard_terms operative section when a capitalized concept needs an explicit anchor or when a longer definition materially shortens later operative clauses.

Before adding a definition, ask:

1. Does the definition add real substantive content, or materially reduce

repetition by replacing a long phrase in operative clauses?

1. Is the term used enough in operative clauses that a short capitalized label

improves readability?

1. If the substance belongs in a Cover Terms value, can that Cover Terms value

remain the single source of truth?

Do not add pointer-only redefinitions for cover-page-only labels such as Company, Employee, Effective Date, Governing Law, or Venue. Those add a second lookup site without improving readability.

If a Cover Terms value contains the real substance of a defined concept, keep all substantive content there. Use the Defined Terms clause only as a short anchor when repeated capitalized use improves readability. Do not split one definition across two sites by writing [[X]] has the meaning given in Cover Terms ... and includes ....

If you remove a formal definition, do not leave behind an unexplained capitalized pseudo-term. Either use the exact Cover Terms label in prose (The Prior Inventions and Excluded Inventions identified in Cover Terms) or rewrite descriptively in lower-case prose.

### Defined Terms

[[Covered Inventions]] means inventions, software, works of authorship,
discoveries, designs, data models, and related intellectual property created
during employment that arise from Company work, use Company resources, or
relate to Company actual or anticipated business.

[[Confidential Information]] means non-public information that Employee
learns, accesses, or develops during employment, including business strategies,
customer and prospect data, trade secrets, technical and product information,
financial information, personnel information, and any additional information
described in Cover Terms under Confidential Information Definition.
Confidential Information does not include information that (a) was publicly
known when Employee learned it, (b) becomes publicly known through no fault
of Employee, (c) was lawfully known to Employee before employment without
confidentiality restriction, or (d) Employee independently develops outside
the scope of employment without using Confidential Information.

Definition rules:

• Every paragraph inside the definitions clause must start its definition body

with a [[...]] span — that span declares the canonical term.

• A leading article (A, An, The) before the first [[...]] is allowed

and is stripped from the canonical term.

• Optional aliases follow the canonical term immediately as

(Aliases: [[Alias 1]], [[Alias 2]]). Aliases never render in the legal output.

• Canonical terms must be unique. Aliases must be unique and may not collide

with any canonical term.

Step 6 — Explicit references

Anywhere outside the definitions clause, [[Term]] is an explicit reference and must resolve to a canonical term, an alias, or a clause ID via [[clause:]]. Plain-text mentions are valid — you do not need to wrap every "Confidential Information" in brackets. Use [[...]] only when you want explicit linking semantics.

Step 7 — Signatures section

## Signatures

By signing this agreement, each party acknowledges and agrees to the obligations
above.

**Company**

Signature: _______________
Print Name: {company_name}
Title: _______________
Date: _______________

**Employee**

Signature: _______________
Print Name: {employee_name}
Title: _______________
Date: _______________

Strict rules (the cover-standard-signature-v1 layout enforces these):

• Exactly two signers. Schema rejects any other count.
• Same row IDs across signers. Both signers should declare the same set

of row IDs (e.g. signature, print-name, title, date) in the same order. The renderer unions row IDs in declaration order.

• Matching labels and hints. When both signers declare the same row ID,

their label and hint must match. Mismatches are rejected with a clear error.

• arrangement is entity-plus-individual or stacked. Defaults to stacked.
• kind is entity, individual, or acknowledging-individual.
• capacity is through_representative, personal, or acknowledging.

Sharp edges and renderer transforms

A few parts of canonical template.md are structural-only in source or normalized by the renderer. If the artifact looks different from the raw markdown, check these first:

• Body H1 is anchor-only. Keep the # ... line readable for humans

navigating the raw .md, but the rendered title comes from frontmatter document.title. If they drift, the artifact follows frontmatter.

• **The H2 after `` becomes the in-document section

heading.** Post-#285, that H2 is the visible section title in the body, so choose names that read well in the output. Example: ` + ## Resolutions renders Resolutions as the in-document heading; the same directive + ## Standard Terms renders Standard Terms. Note that on cover-standard-signature-v1, the **running page header** is separately driven by frontmatter sections..sectionlabel — if you rename the body H2 but leave sectionlabel` alone, the page header will not change.

• [Signature Page Follows] is renderer-inserted. Authors do not write

that string in canonical source. The traditional-consent-v1 layout always inserts [Signature Page Follows] between the operative section and the signature section, so seeing it in output but not source is expected.

• **Signer row values in repeat-backed signature sections get $

auto-prefixed.** In a repeat-backed signature section, write {stockholder.name} in canonical source. The parser rewrites it to {$stockholder.name} in generated artifacts, so do not "fix" the $ you see there. This rewrite is scoped to signer row values; it does not fire for other loop contexts.

Use this quick source-of-truth map when deciding where authored text will show up:

• Body # -> anchor-only for raw .md; not rendered in the artifact
• Body ## immediately after `` ->

rendered as the in-document section heading

• Body ### plus following paragraphs -> rendered
• Frontmatter sections..section_label -> running page header in

cover-standard-signature-v1 (independent of the body H2)

• Body recital paragraphs under `` ->

rendered in the optional recital section (currently only traditional-consent-v1 emits a recital section; cover-standard-signature-v1 ignores it)

• Frontmatter document.title -> rendered as the document title
• Frontmatter document.opening_recital -> rendered before the operative

section by traditional-consent-v1; not consumed by cover-standard-signature-v1

• Frontmatter document.label and document.version -> rendered in the

layout footer; exact placement varies by layout

• Frontmatter document.license -> consumed in the Markdown export, but

both current DOCX layouts hardcode the footer license string as "Free to use under CC BY 4.0." rather than reading frontmatter. All first-party templates currently use that license so the output happens to match, but don't expect a non-CC-BY-4.0 license to flow through to the DOCX footer today.

Step 8 — Generate and verify

npm run generate:templates

The canonical compiler:

1. Parses template.md → normalized model.
2. Validates definitions, references, signers, and field-name shapes.
3. Writes the regenerated JSON to content/templates//.template.generated.json.
4. Renders the DOCX via the shared layout to outputs.docx.

After generation:

• git diff content/templates//.template.generated.json — should be empty

if your source matches the previously committed JSON.

• npx vitest run integration-tests/canonical-source-sync.test.ts — proves the

canonical → JSON projection is in sync.

• `npx vitest run integration-tests/canonical-source-authoring.test.ts integration-tests/template-r

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: open-agreements
• Source: open-agreements/open-agreements
• License: Apache-2.0
• Homepage: https://openagreements.org

Install and usage instructions live in the source repository linked above.