Every prompt deserves a receipt.
promptsyntax.org · Specification · Syntax reference · Trace schema
When you use an AI assistant today, you cannot see what your prompt becomes before it
reaches a model, you cannot guarantee which model or tools actually run, and when the
system quietly swaps a cheaper model or drops a setting you asked for, nothing tells you.
The same @ you type means three different things across three products. This is not a
minor inconvenience. As AI moves into higher-stakes work, and increasingly runs while
no one is watching, an interface layer that is merely opaque today becomes
infrastructure-grade opacity tomorrow.
Prompt Syntax is a proposal that the chat box should be a designed language, not an accidental one.
PS is a vendor-neutral specification for expressing authorized prompt-execution intent, together with a conformance protocol, the Prompt Trace, or execution receipt, reporting how that intent was resolved and fulfilled.
Prompts stay natural language. Optional syntax islands add control that degrades gracefully:
@opus!(temperature: 0.2) limit(wall_time: 5s) else @haiku
Summarize @file:q3-report.md /concise
A novice reads that as a sentence. It also carries a strict model binding, a latency budget, a fallback route, a deterministic file inclusion, and a skill invocation, each optional, each honored or reported.
Every request returns a receipt: per requirement, requested → applied, with typed reasons for anything that changed. No silent substitution. No silent drop. No silent anything.
| Path | Contents |
|---|---|
spec/SPEC.md |
The specification (four layers: Core / Capabilities / Execution / Trace) |
spec/SYNTAX-REFERENCE.md |
The full syntax on a few pages |
schemas/ |
Normative JSON Schema for the Prompt Trace |
examples/ |
Machine-validated example trace |
decisions/ |
Design decision records (with rejected alternatives) |
profiles/ |
Externalized mappings: vendor, oversight, policy bindings |
conformance/ |
Language-independent requirements, vectors, schemas, reports, and Rust runner |
Draft v0.2.1 with experimental implementations. Not yet stable. Rust and TypeScript Core parsers and a candidate Trace conformance suite are under active review; a formative multi-stakeholder study and academic paper are in preparation. This is a proposal seeking scrutiny, not a finished standard.
Graceful degradation · familiarity borrowing · progressive disclosure · content safety · contract-not-presentation · minimal reserved surface · one reference grammar · non-escalation · intent portability (not execution portability) · security by provenance, not by escaping.
Per-layer, versioned, and named, e.g. PS/Core 0.2 + PS/Trace 0.2 (user tier, routing-complete/assembly-partial). Unqualified conformance claims are
non-conformant: an implementation must state what it covers.
The draft suite is self-contained in this repository. Its stable-Rust runner has no provider, model, Node, or Python dependency:
cargo test --manifest-path conformance/runner/Cargo.toml
cargo run --manifest-path conformance/runner/Cargo.toml -- \
check-requirements conformance/requirements.json
cargo run --manifest-path conformance/runner/Cargo.toml -- run-suite .
cargo run --manifest-path conformance/runner/Cargo.toml -- \
compare-core-adapters conformance/cases/core-parser.json \
/tmp/promptsyntax-rs-core.json /tmp/promptsyntax-ts-core.json
cargo run --release --manifest-path conformance/runner/Cargo.toml -- \
generate-core-differential 100000 20270803 > /tmp/core-generated.json
cargo run --release --manifest-path conformance/runner/Cargo.toml -- \
compare-core-streams 100000 20270803 \
/tmp/promptsyntax-rs-generated.jsonl /tmp/promptsyntax-ts-generated.jsonlCandidate 0.1.0-rc.1 currently executes 34 Trace document and producer cases with full
coverage of its explicitly named 22-requirement profile. It also carries 101 Core parser
vectors, compares full normalized Rust and TypeScript outputs, runs a deterministic
100,000-input grammar differential, and runs ten real Trace producer cases against
independent transcripts. Candidate status is not a released or unqualified
implementation-conformance claim.
This is a draft seeking exactly the scrutiny that hardens a specification. Feedback is
welcome, especially from platform operators, enterprise administrators, compliance
practitioners, and anyone who has been silently rerouted and wanted to know why. Open an
issue; substantive design proposals should follow the decision-record format (context,
options, chosen, rejected-with-reasons). See decisions/ for the
pattern.
This repository is also the source of promptsyntax.org, a
SolidJS + Rsbuild single-page app (src/, styled with Tailwind CSS 4 and
@pathscale/ui). The /spec and /syntax pages render
the same documents that live in spec/.
bun install
bun run dev # dev server on :3000
bun run build # typecheck + production build into dist/Pushes to master build and deploy to BunnyCDN via
.github/workflows/pipeline.yml.
Specification text and schemas: CC BY 4.0 (proposed, confirm before relying on it). The intent is maximal openness: PS is only useful if anyone can implement it.