Systematic guidance for WeaveMark authors.

Core syntax

Directive families

Imports and modules

Modules use dotted logical names, not file paths. A module file may contain one module and no unrelated outside content. Importing with @use makes definitions available; it does not inject the module body. Use @refine module:<name> to semantically compose reusable body content.

File references are separate from modules. Use @reference path keep:true|false when source material should inform compilation; retained references are appended after a document break, while compilation-only references are omitted from generated prompt artifacts.

Module discovery is deterministic. Every effective promplet-library root participates in one shared dotted namespace. The weavemark.* namespace is reserved for built-ins; duplicate module names are errors.

{
  "library_dirs": ["/work/team-promplets"]
}

Every reusable module promplet declares its logical identity, for example @module company.writing. A body-bearing module may be refined with @refine module:company.writing; definitions are imported with @use. Definition modules may also package inactive default host bindings.

@use company.writing as writing exposing calm_voice

@calm_voice
  Draft the release note.

@refine module:company.writing

@use weavemark.domains.finance.market_research exposing fetch_asset_snapshot search_asset_context

Importing selects module-owned default @bind metadata, with helper paths relative to the declaring module. No Python runs during composition; runtime protection still authorizes execution. A local binding with the same capability name overrides one default.

Macros and semantic functions

@define has two major uses. Without effects, it defines a deterministic macro that expands WeaveMark source before ordinary composition. With @effect, @phase, and @returns, it defines a semantic function whose behavior is planned or executed according to its phase.

@define summarize_source
  @param body implicit: true mode: subspec
    Source material to summarize.

  @body
    Summarize the following material:
    @{body}

Output shapes

@compile context: auto|cascade|local controls whether root text is shared with named blocks: auto keeps the disposition default, cascade includes shared context, and local keeps each block self-contained.

@prompt agent role: system format: mustache
  You are a careful research assistant.

@prompt agent role: user format: mustache
  Research {{query}} for @{audience}.

Execution reference

Functional scheduler values

• sequential: execute surviving nodes top-to-bottom.
• graph: build a dependency DAG from uses: edges.
• graph-strict: graph mode plus strict unknown dependency and effect validation.

Functional compilation is side-effect free. During --run, the built-in FunctionalEngine imports only the authorized Python bindings needed by the validated nodes, records per-node evidence, substitutes named results, and completes the rendered document.

FSLM prompt contract

@execute fslm loads an external machine with machine:, validates all required prompts before the initial snapshot is created, and injects runtime context into every prompt call. Use initial_event: or runtime-config events: to feed the machine.

@execute fslm
  machine: support-triage.fslm.yaml
  initial_event: user_message
  prompt_contract: strict

@prompt guard.has_answerable_question
  Decide whether the event contains an answerable support question.

@prompt output.final_answer
  Return only the final user-facing answer.

Inline machine sugar is available by explicitly importing weavemark.experimental.fslm. It compiles to the same event-driven execution metadata:

@use weavemark.experimental.fslm exposing machine state transition input guard action

@execute fslm
  machine: support_triage

@machine support_triage initial: triage
  Support workflow.

  @state triage
    The request is being triaged.

    @transition gather_evidence target: triage internal: true external: false
      Search docs before answering.

      @input query
        Search query.

      @guard needs_more_evidence
        Choose this only when evidence is insufficient.

      @action search_docs tool: search_docs
        Search docs using matching transition inputs.

Surface adapters

Surface adapters let programmers author WeaveMark using host-format syntax sugar. The sugar is lowered to standard WeaveMark before macro expansion, scanning, and composition, so the WeaveMark Processor sees normal directives.

Activate a surface adapter with the surface: key on the @promplet pragma:

@promplet version: 0.7 surface: markdown

Markdown surface — directive headings

A Markdown heading whose heading text begins with a directive name is lowered to a canonical directive block. The body is the section until the next heading of equal or higher level.

## @prompt extract role: user

Extract claims from @{passage}.

## @prompt critique

Critique each claim.

Lowers to:

@prompt extract role: user
  Extract claims from @{passage}.

@prompt critique
  Critique each claim.

Markdown surface — WeaveMark callouts

A Markdown blockquote whose first quoted line is [!PROMPLET <directive> <args>] is lowered to a canonical directive. For body-transforming directives such as @style, the callout arguments describe the operation and the quoted body is the target.

> [!PROMPLET style "Crisp, direct, professional."]
> Explain @{feature} to a busy product leader.

Lowers to:

@style "Crisp, direct, professional."
  Explain @{feature} to a busy product leader.

Body-transforming stdlib directives

@style, @normalize, and @revise all transform the subspec in their body. The body is not extra criteria; it is the material being transformed.

@normalize "Use consistent product terminology." scope: semantic intensity: medium
  The dashboard calls the same object a project, board, and workspace.

@revise "Remove contradictions while preserving the launch constraints." mode: editorial
  The pilot must be offline-first.
  The pilot may require cloud access for every save.

CLI commands

Common pitfalls

• Use @{name} for WeaveMark variables. Do not use Mustache for WeaveMark inputs.
• Use standard helpers such as @style, @assert, and @output directly; they are loaded by default.
• For @style, @normalize, and @revise, put the operation instruction inline and indent the subspec being transformed below it.
• Do not mix role-tagged and role-less @prompt blocks in a spec without @execute.
• Do not put @promplet below title text. If present, it must be first.
• Use @bind for helper implementations. Do not put implementation paths in @tool.
• Use quoted values when inline arguments contain whitespace, colons, commas, or escaped quotes.
• Keep helper file paths relative and let the execution runtime enforce sandboxing.