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.
Compilation and execution share one text model, set with
--model. gpt-5.6-terra is the default and
the current recommendation; --verbose closes a run with
its token counts, cache hits, and cost.
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?
They reinforce each other; WeaveMark is itself built almost entirely with such tools. An assistant can also use WeaveMark to organize its own work: instead of regenerating sprawling ad-hoc prompts, it captures reusable intent as promplets — personas, policies, reasoning methods, output contracts — and composes repeatable systems from them. That also makes human–AI collaboration easier, since a person can review just the parts that matter (a variable, a constraint, a contract) and leave the rest to the model.
Why is the language called WeaveMark and the artifacts called promplets?
WeaveMark is a markup notation for prompts. Like any markup language — think HTML — it shapes the content around it, but minimally invasively, keeping the focus on the underlying prose (usually Markdown). The name also plays on mark: to trace boundaries, to assemble marked pieces toward a goal, and to take careful notice, something worth remarking.
A promplet is one artifact written in WeaveMark: a reusable unit of prompt composition. The name reads two ways — prompt + -let (a small, modular artifact, like an applet, especially when executable) and prompt + let (as in “let x be…”, emphasizing binding and composition).
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 realized that a few other people have independently explored kindred ideas under the similar name promptlet — each in their own way: composable prompt artifacts, 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. But 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. (WeaveMark spells it promplet; several of them use promptlet.)
Why does the notation use @ and indentation for scoping?
To stay as readable as Markdown as possible. @ marks the
few places WeaveMark adds a directive, and indentation scopes its body
with minimal visual noise. Most of a promplet should still read like
ordinary prose, except those that are entirely just compositions of
other pieces.
Why Markdown instead of HTML or another markup language?
Markdown is already the lingua franca of prompts: readable in plain
text, familiar to LLM users, and easy to paste anywhere. WeaveMark is
not fundamentally limited to it: the @-based directive
style is compatible with many markup languages, including HTML, and
future versions could support those better.
LLM-based compilation? Are you insane?
A little, of course; where would the fun be otherwise? Language is the ultimate thinking tool. What if natural language could help us design useful new languages more easily? LLMs let us try — so let's experiment.
Why not a template engine?
Template engines are perfect when the result shape is known exactly: substitute this variable, include that partial verbatim. Promplets allow more abstract composition, at the cost of a generative model realizing the final prompt. That makes them more reusable and more readable. Some promplets also go further — running compiled prompts through engines like reflection or tree-of-thought, and binding trusted companion programs — so WeaveMark can act as a prompting engine, not only a language.
This is not literate programming!
Not quite: our final “program” is the prompts to be used, woven from abstract, readable prose. Under a liberal reading of “program” as “instructions to be executed,” WeaveMark is a kind of literate programming for natural-language instructions — call it “programmatic prompting” if you prefer.
Is this a harness?
As much as a car is a "fuel harness".
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.