UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

565 lines (459 loc) • 25.1 kB
--- name: canonical-markdown-authoring description: >- Convert plain markdown contract drafts into OpenAgreements' canonical template.md authoring format — YAML frontmatter, Kind|Label|Value|Show When cover-term tables, oa:clause directives, [[Defined Term]] paragraphs, and oa:signer directives that compile to validated JSON specs and DOCX artifacts. Use when the user says "convert this to canonical markdown," "author a new OpenAgreements template," "migrate template to template.md," or "write a canonical-form contract." license: Apache-2.0 compatibility: >- Requires read/write access to an OpenAgreements repo checkout (the canonical compiler at scripts/template_renderer/canonical-source.mjs and the cover-standard-signature-v1 layout must be available). Works with any agent that can edit local files and run `npm run` commands. metadata: author: open-agreements version: "0.1.0" internal: true catalog_group: Template Authoring catalog_order: 10 --- # 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 `templates/<template-id>/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. 2. **`# Title`** — H1 matching `document.title` in frontmatter. 3. **`## Cover Terms`** — short subtitle paragraph followed by a `Kind | Label | Value | Show When` table with `{snake_case}` field placeholders. 4. **Optional `recitals` section** — `<!-- oa:section type=recitals -->` followed by an H2 such as `## Recitals` and one or more recital paragraphs. 5. **Operative section** — `<!-- oa:section type=standard_terms -->` followed by an author-chosen H2 such as `## Standard Terms`, `## Resolutions`, or `## Terms`. Clauses live here, each preceded by `<!-- oa:clause id=... -->`. The first clause should be `Defined Terms` with `type=definitions` when a definitions clause is needed. 6. **Signature section** — `<!-- oa:section type=signature -->` followed by the signature H2 and then `<!-- oa:signature-mode arrangement=... -->` plus the signer blocks. ## Step-by-step conversion ### Step 1 — Skeleton the frontmatter ```yaml --- template_id: openagreements-<slug> # kebab-case, must match the directory slug layout_id: cover-standard-signature-v1 style_id: openagreements-default-v1 outputs: docx: templates/openagreements-<slug>/template.docx document: title: <Document title> # MUST match the H1 below label: <Catalog label, e.g. "OpenAgreements XYZ"> 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 `templates/<slug>/template.md` whose frontmatter declares `template_id`, `layout_id`, and `style_id`, then writes the generated JSON to `templates/<slug>/.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) ```markdown # <Document title> ``` 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: ```markdown ## 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. - `<field_name>` — 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: ```markdown <!-- oa:section type=standard_terms --> ## Standard Terms <!-- oa:clause id=assignment-of-inventions --> ### 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. <!-- oa:clause id=non-competition when=noncompete_included omitted="[Intentionally Omitted.]" --> ### 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: ```markdown <!-- oa:section type=recitals --> ## Recitals **WHEREAS**, Company is considering a financing transaction. **WHEREAS**, the board has reviewed the proposed terms. <!-- oa:section type=standard_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=<field_name>` (optional) — clause is only included when the named boolean field is truthy. - `omitted="<text>"` (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? 2. Is the term used enough in operative clauses that a short capitalized label improves readability? 3. 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. ```markdown <!-- oa:clause id=defined-terms type=definitions --> ### 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:<id>]]`. **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 ```markdown <!-- oa:section type=signature --> ## Signatures <!-- oa:signature-mode arrangement=entity-plus-individual --> By signing this agreement, each party acknowledges and agrees to the obligations above. <!-- oa:signer id=company kind=entity capacity=through_representative label="Company" --> **Company** Signature: _______________ Print Name: {company_name} Title: _______________ Date: _______________ <!-- oa:signer id=employee kind=individual capacity=personal label="Employee" --> **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 `<!-- oa:section -->` 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: `<!-- oa:section type=standard_terms -->` + `## 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.<name>.section_label` — if you rename the body H2 but leave `section_label` 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 `# <H1>` -> anchor-only for raw `.md`; not rendered in the artifact - Body `## <heading>` immediately after `<!-- oa:section type=... -->` -> rendered as the in-document section heading - Body `### <clause heading>` plus following paragraphs -> rendered - Frontmatter `sections.<name>.section_label` -> running page header in `cover-standard-signature-v1` (independent of the body H2) - Body recital paragraphs under `<!-- oa:section type=recitals -->` -> 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 ```bash 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 `templates/<slug>/.template.generated.json`. 4. Renders the DOCX via the shared layout to `outputs.docx`. After generation: - `git diff templates/<slug>/.template.generated.json` — should be empty if your source matches the previously committed JSON. - `npm run generate:templates && git diff --exit-code` — proves the canonical → JSON projection is in sync. - `npx vitest run integration-tests/canonical-source-authoring.test.ts packages/contract-templates-mcp/tests/tools.test.ts` — broader coverage. ## Highlight modes `document.defined_term_highlight_mode` controls how defined terms are visually highlighted in the rendered DOCX: | Mode | Behavior | When to use | | --- | --- | --- | | `definition_site_only` | Highlights only at the definition paragraph; brackets are stripped from prose. | **Default for templates with a Defined Terms clause.** Avoids "too much blue" in body text. | | `all_instances` | Highlights every occurrence of any term in `style.defined_terms`. | Templates without a Defined Terms clause that still want emphasis on a small fixed list (e.g. Company, Employee). | | `none` | No highlighting. | Plain-text outputs. | If you add a Defined Terms clause, switch to `definition_site_only`. The template-wide `style.defined_terms` list still applies as a fallback for `all_instances` mode. ## Reference templates Working canonical templates already in the repo: - `templates/openagreements-restrictive-covenant-wyoming/template.md` — feature-rich: substantive defined terms paired with narrow cover-term anchors for operative concepts, group/subrow cover terms, and conditional clauses. - `templates/openagreements-employee-ip-inventions-assignment/template.md` — simpler: 2 substantive defined terms (`Covered Inventions`, `Confidential Information`), present-tense IP assignment language, and all-row cover terms. When migrating a JSON-sourced template, copy the closer of these two as a shape reference and adapt. ## Pitfalls | Pitfall | Symptom | Fix | | --- | --- | --- | | Edited `template.md` but forgot to regenerate | `npm run generate:templates` leaves a dirty diff | Run `npm run generate:templates` and commit the regenerated `.template.generated.json` diff. | | H1 doesn't match `document.title` | Silent drift; renders the frontmatter title | Keep them in sync manually until cross-validation lands. | | `output_markdown_path` left in frontmatter | Compiler throws | Remove `outputs.markdown` and any top-level `output_markdown_path`. | | `source_json` left in frontmatter | Quietly ignored today; will become an error | Remove `source_json` — JSON paths are now derived from the slug. | | Same-id signer rows with different labels | Layout throws "mismatched labels" error | Make both signers' row labels identical, or rename one row's ID. | | Three signers | `cover-standard-signature-v1` rejects at render | Reduce to two signers, or add a new layout that supports N signers. | | Field placeholder uses `camelCase` | Validation rejects | Use `snake_case` matching `^[a-z_][a-z0-9_]*$`. | | Definitions paragraph without a `[[...]]` declaration | Compiler throws | Every paragraph in a definitions clause must declare a canonical term. | | Alias collides with a canonical term or another alias | Compiler throws | Choose a unique alias. | | Adding `[[...]]` everywhere in prose | "Too much blue" in DOCX | Reserve `[[...]]` for definition sites and explicit references; let plain prose stay plain. | | Pointer-only redefinition of a cover-page-only term | Second lookup site with no readability gain | Omit the defined-term entry; use the Cover Terms label directly in prose. | | One term split across Cover Terms and Defined Terms | Reader must combine two sources for one definition | Put all substantive content in one place — usually a substantive body definition with optional Cover Terms supplementation. | | Capitalized pseudo-term with no exact anchor | Reader cannot tell where the term is defined | Keep an exact anchor (`identified in Cover Terms`) or rewrite in descriptive lower-case prose. | | Bare `agrees to assign` in an IP assignment clause | Diligence flag — not a present transfer of rights | Use `hereby assigns and agrees to assign` (see Step 4A). | ## Minimal complete example ```markdown --- template_id: openagreements-example-nda layout_id: cover-standard-signature-v1 style_id: openagreements-default-v1 outputs: docx: templates/openagreements-example-nda/template.docx document: title: Example Mutual NDA label: OpenAgreements Example Mutual NDA version: "1.0" license: Free to use under CC BY 4.0 defined_term_highlight_mode: definition_site_only cover_row_height: 600 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 --- # Example Mutual NDA ## Cover Terms The terms below are incorporated into and form part of this agreement. | Kind | Label | Value | Show When | | --- | --- | --- | --- | | row | Disclosing Party | {disclosing_party_name} | always | | row | Receiving Party | {receiving_party_name} | always | | row | Effective Date | {effective_date} | always | | row | Confidentiality Term | {confidentiality_term} | always | <!-- oa:section type=standard_terms --> ## Standard Terms <!-- oa:clause id=defined-terms type=definitions --> ### Defined Terms [[Confidential Information]] means non-public information disclosed by a party that is identified as confidential at the time of disclosure or that a reasonable person would understand to be confidential given the nature of the information and the circumstances of disclosure. <!-- oa:clause id=use-restrictions --> ### Use Restrictions The Receiving Party identified in Cover Terms will use Confidential Information solely to evaluate the business relationship contemplated between the parties and will not disclose Confidential Information to third parties without the Disclosing Party's written consent. <!-- oa:clause id=term-and-survival --> ### Term and Survival Each party's confidentiality obligations apply for the Confidentiality Term listed in Cover Terms, beginning on the Effective Date. Trade-secret obligations survive indefinitely. <!-- oa:section type=signature --> ## Signatures <!-- oa:signature-mode arrangement=stacked --> By signing this agreement, each party acknowledges and agrees to the obligations above. <!-- oa:signer id=disclosing kind=entity capacity=through_representative label="Disclosing Party" --> **Disclosing Party** Signature: _______________ Print Name: {disclosing_party_name} Title: _______________ Date: _______________ <!-- oa:signer id=receiving kind=entity capacity=through_representative label="Receiving Party" --> **Receiving Party** Signature: _______________ Print Name: {receiving_party_name} Title: _______________ Date: _______________ ``` ## Notes - Canonical authoring is the standard authoring format for OpenAgreements templates. New templates and migrations of existing JSON-source or Contract-IR-source templates should land in canonical `template.md` form and be picked up automatically by `npm run generate:templates`. - This tool does not provide legal advice — consult an attorney. ## Connectors For setup of the OpenAgreements repo / CLI, see [CONNECTORS.md](./CONNECTORS.md).