Collect and validate inputs
In guided mode, the Processor asks for missing variables,
@match choices, and conditional flags. In batch
mode, it fails clearly instead of guessing.
What is WeaveMark?
WeaveMark is a small, opinionated specification
language for prompts. A .weavemark.md file is
plain Markdown sprinkled with line-leading directives such
as @refine, @style, @match,
and @execute that specify abstract intent rather
than exact wording. It can be read by a human as a document and
compiled by the WeaveMark Processor — which uses a language model to
realize that intent, with deterministic structure around it — into
structured prompt artifacts.
The core idea is simple: keep intent in prose, then make important structure explicit. Deterministic parsing handles the mechanical parts — module resolution, macro expansion, branching, emitted files, output shaping, and execution checks — while the meaning-level work (realizing abstract intent, refining, restyling, condensing) is done by a language model. So compilation is largely LLM-based, with deterministic structure as scaffolding.
What is a promplet?
A promplet is an individual reusable prompt specification written in WeaveMark. It can define instructions, variables, branches, tools, output contracts, prompt execution behavior, and refinements
Promplets are compositional. A promplet can stand alone as a concrete prompt specification, or it can be made from other promplets: shared personas, policies, reasoning methods, domain constraints, tool definitions, and output structures. The idea is that the final prompt is made out of several little prompts.
The word specification is deliberate: a promplet states properties that its realized prompt or system should preserve while leaving implementation choices open. Refinement adds detail and narrows those choices without discarding the original obligations. The Principles page gives this relationship a precise definition.
@embed files, PDFs, and Markdown
![images]). The WeaveMark Processor compiles, validates,
and executes it — clarifying with you (@ask),
self-improving through an @iterate LLM-as-judge
loop, and running tools and effects —
to produce artifacts that go where you need them: a
pastable prompt for an AI assistant, emitted
files for an LLM app, an execution that
returns output directly, or a running app.
What is the WeaveMark Processor?
The WeaveMark Processor is the tool invoked as
weavemark. It is the command-line entry point for working
with promplets: it compiles them into usable prompt artifacts, shows
structured metadata for tools and editors, and executes prompts when
a promplet declares executable behavior.
Compile promplets into artifacts
It resolves modules, applies directives, expands reusable fragments, materializes emitted files, and returns a structured result that other programs can inspect.
Expose metadata and diagnostics
--scan, JSON output, warnings, errors, tools, and
execution metadata make promplets usable from editors, scripts,
CI checks, and Python applications.
Run prompts through engines
When a promplet uses @execute or the caller requests
--run, the Processor executes the prompt through the
declared or configured engine instead of merely producing text.
The compilation model
The WeaveMark Processor receives a promplet plus variable values. It returns a structured envelope containing the primary prompt, named prompts, compile options, tools, companion-implementation bindings, execution metadata, emitted files, warnings, errors, and suggestions. The first steps are deterministic scaffolding; the final step is where a language model does most of the work.
Parse the shape
Recognize directive lines, indentation, variables, comments, strings, inline lists, and opaque bodies.
Preprocess modules and macros
Resolve @module, @use,
@include, and source-to-source macro
definitions before ordinary directive evaluation.
Substitute variables
Replace @{name} with provided values. Preserve
Mustache templates such as {{name}} as ordinary
prompt content.
Apply structural directives
Deterministically evaluate branches, remove notes, collect tools and bindings, compose prompt blocks, and materialize emitted files.
Realize semantic intent with a model
A language model performs the meaning-level moves —
@refine, @style, @revise,
@summarize, and the rest — turning abstract intent
into concrete prompt text. This is where most of the compilation
happens, and why it is not a template engine.
The interpretation model
Every run starts with successful compilation, but the compiled artifact is not yet the final answer. An execution engine interprets that artifact as a runtime plan: it assigns roles to named prompts, orchestrates model and tool calls, carries intermediate results forward, and produces an execution record. The model supplies semantic power; the engine provides the machinery that directs it.
Compilation
Promplet source → structured prompt artifact
Interpretation
Structured artifact → engine run → result
Start from the compiled artifact
The engine receives the compiled prompts, tools, bindings, output contracts, image inputs, and execution metadata. It does not reinterpret the raw source notation.
Resolve the engine and runtime
An explicit caller choice wins, followed by runtime
configuration, the promplet’s @execute
declaration, and finally the safe single-call
default. Runtime settings resolve models, temperatures, policy,
and engine-specific options.
Validate the engine contract
Each strategy expects particular prompt roles and capabilities. Missing roles or unsupported modalities fail explicitly before the engine proceeds.
Interpret through runtime steps
The selected engine performs one or more model, image, or tool calls according to its pattern. Intermediate outputs may feed later stages, searches, votes, critiques, revisions, or state transitions.
Return output with an execution record
The run returns the final output, ordered step records, metadata and call-setting provenance, plus any streamed artifacts. The public result retains both the compiled artifact and its interpretation.
The boundary stays explicit
Most directives transform or organize the specification.
@execute declares when the artifact may cross into
runtime interpretation and which orchestration pattern should
govern it.
Advanced engines can also interpret finite-state linguistic machines whose guards, actions, and outputs are named prompts. Required roles are validated before execution.
@execute tree-of-thought
branching_factor: 3
max_depth: 2
@prompt generate
Generate candidate solutions to @{problem}.
@prompt evaluate
Evaluate the candidates.
@prompt synthesize
Produce the final answer.The main language pieces
| Piece | Purpose | Example |
|---|---|---|
@{variable} |
External input supplied by the caller or CLI. | @{company} |
| Source references | Files used during compilation, optionally retained in a final appendix. | @reference terminology.md keep:false |
| Core directives | Structural language features always available. | @prompt, @emit, @execute |
| Stdlib semantic functions | Default-loaded helpers for common prompt operations. | @style, @normalize, @revise, @assert, @refine |
| Macros | Reusable source-to-source expansions. | @define reviewer(...) |
| Modules | Named files that export definitions and reusable bodies. | @module company.writing |
| Tools and bindings | Function schemas and companion implementation metadata. | @tool search_web, @bind search_web ... |
A small macro
@define review_block(subject: thing being reviewed, focus: review priority, body: review material)
## Review: @{subject}
Focus on @{focus}.
@{body}
@review_block subject: "API design" focus: "clarity and safety"
Assess the endpoint naming, error shapes, and auth flow.Three output shapes
Single prompt
No @prompt and no @execute. The whole
document compiles into one primary prompt.
Prompt execution
A top-level @execute turns a promplet into an
executable prompt specification that runs through an engine.
Emission
Without @execute, role-tagged
@prompt blocks compile into named prompt files.
A practical workflow
- Write the smallest readable Markdown prompt that captures intent.
- Add variables where caller input should enter.
- Add semantic helpers such as
@style,@normalize,@revise,@output, and@assert. - Use
@matchand@iffor genuine variation. - Compose with
weavemark --batch-onlyand inspect the artifact. - Add tools, bindings, emission, or execution only when the composed prompt is clear.
Next: follow the step-by-step
technical tutorial, or jump to the
Python API guide for app integration,
or the reference for systematic guidance.
Frequently asked questions
If AI assistants can already program for me, why use WeaveMark?
Not at all mutually exclusive — they reinforce each other. WeaveMark and AI-assisted programming tools (Copilot CLI, Claude Code, and the like) are complementary, not competing. WeaveMark is itself built almost entirely with such tools.
An AI assistant can also use WeaveMark to organize its own work. Instead of regenerating sprawling, ad-hoc prompts every time, it can capture reusable intent as promplets — shared personas, policies, reasoning methods, and output contracts — and compose more organized, effective, and repeatable systems for itself. A specification language gives the model durable structure to build on, not just one-shot text.
It also makes human–AI collaboration easier. Because a promplet is a precise, readable surface, a person can limit their touch to exactly the parts that matter — a variable, a constraint, an output contract — and leave the rest to the AI. Those boundaries can even be drawn by the AI: it drafts the promplets, and a human reviews or adjusts only the well-scoped pieces. You keep the leverage of AI generation together with the reviewability and control of a specification.
What do the names “WeaveMark” and “promplet” mean?
WeaveMark joins weave and mark.
Weave is about composition: a promplet is
woven together from reusable prose, refinements, and directives. It
also nods to literate programming and its classic
WEAVE tool, which likewise wove documentation and code
into a single readable source. Mark signals that this is a
markup notation: like Markdown or HTML, it stays
minimally invasive and keeps the focus on the underlying prose, only
marking the few seams where composition, reuse, branching,
and output happen. “Mark” also carries the sense of tracing
boundaries and of something worth remarking — taking careful
notice.
WeaveMark names the language, toolchain, and ecosystem; a promplet is the native artifact you write in it. The word promplet itself has two complementary readings: prompt + -let, a small modular prompt artifact in the spirit of applet, servlet, and cmdlet (fitting, since some promplets are executable); and prompt + let, an allusion to declarations such as “let x be…” in mathematics and programming languages, emphasizing specification, binding, and composition.
And a small confession: finding a name that was not already taken by some related project turned out to be surprisingly hard. The prompt and LLM space is crowded, and several earlier candidates were already claimed by other tools before WeaveMark finally stuck.
Where does the promplet concept come from?
The concept grew out of my own work; I developed it during 2025 without being aware of anyone else using a similar term. Since then I have been glad to find that a few other people have independently explored kindred ideas under the similar name promptlet — each in their own way: a reusable prompt snippet, a weighted segment of a Midjourney multi-prompt, and a unit of prompt reuse and structure.
None of these are the same as WeaveMark, and that is part of the fun: the idea of a small, named, reusable unit of prompting seems to be in the air, and each project takes it somewhere different. WeaveMark simply develops it in its own direction — toward composable, refinable specifications you can compile. These related efforts are a genuinely welcome source of ideas and inspiration. (WeaveMark spells it promplet; several of them use promptlet.)
Why does the notation use @ and indentation for scoping?
The goal is to keep promplets as readable as Markdown. The notation
introduces as little new syntax as possible: @ marks
the few places where WeaveMark adds a directive, and indentation
scopes the directive body without braces, closing tags, or a
separate block language. Most of a promplet should still look and
read like ordinary Markdown prose.
Why Markdown instead of HTML or another markup language?
Markdown is the starting point because it is already popular for
prompts: readable in plain text, familiar to LLM users, and easy to
paste into chat, docs, issues, and agent tools. WeaveMark is not
fundamentally limited to Markdown, though. Future versions could
support HTML or other notations, and the @-based
directive style is intentionally compatible with many text and
markup languages.
LLM-based compilation? Are you insane?
A little, of course; where would the fun be otherwise? But bear with me. Language — natural language, programming languages, logic, mathematical notation — is the ultimate thinking tool. What if natural language could help us design new useful languages more easily? LLMs let us try. So let's experiment.
Why not a template engine?
Template engines are excellent when the result shape is known precisely: replace this variable, include that partial verbatim, repeat this block exactly here. Promplets, on the other hand, allow more abstract compositions, at the cost of requiring a generative model to realize the final prompt. This makes promplets more reusable, since they can be applied directly in more contexts, and more readable, giving the approach a literate-programming feel.
Promplets can also go beyond merely generating prompt text. Some promplets are executable: they can run compiled prompts through engines such as reflection, self-consistency, or tree-of-thought. They can also bind trusted programs, such as Python companion functions, to the prompt specification. In that sense, WeaveMark is not only a language; it can also act as a prompting engine.
This is not literate programming!
Well, we are not weaving programs from prose, true. Our final “program” is, rather, the final prompts to be used. We weave them from more abstract, readable prose, much like in literate programming. So if we take a liberally minded view of “program” as “a set of instructions to be executed”, then WeaveMark is indeed a form of literate programming, albeit for instructions in a natural rather than formal language. Perhaps we should invert the terminology and call the method “programmatic literature”, “programmatic writing”, or “programmatic prompting” instead?
Don't you have an actual job and a family to feed?
Why, yes — but what's the problem? Some people watch the World Cup. Others spend a full waking day every week doomscrolling Instagram. Still others feed the poor. And who sleeps before midnight anyway? I do this. It is my idea of fun - and of contributing to the community.
Is this a harness?
As much as a car is a "fuel harness".