spec.md: Structured Specification Interface

• spec.md is a structured specification artifact that standardizes representations for scientific simulations, imaging designs, and software architectures.
• It enforces explicit schemas and eliminates hidden defaults, enabling automated validation, compilation, and agentic workflows.
• Its versatile format produces machine-readable artifacts that enhance reproducibility, accuracy, and interoperability in varied applications.

Across recent literature, the name spec.md is used for several structured specification artifacts: a six-tuple for scientific simulation, an eight-field format for imaging-system design, a repository-anchored architecture document in AI-assisted software development, and a clean Markdown input to template-constrained LaTeX conversion. In each case, the document is intended to move problem statements out of informal prose and into a representation that is machine-readable, inspectable, and suitable for downstream checking, compilation, proof, or execution (Yang, 26 Mar 2026, Yang, 26 Mar 2026, Grabowski, 25 Jun 2026, Hei et al., 22 Jun 2026).

1. Conceptual role of spec.md

The central role of spec.md is to act as an explicit interface between intent and mechanism. In scientific simulation, it serializes a problem as the six-tuple $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$ so that a Judge Agent can check well-posedness, convergence, and computable error bounds before or after code generation. In computational imaging, it fully determines an imaging-system design through eight ordered fields, with the forward_model field expressed as a composition of primitives from a finite basis. In software architecture, each SPEC.md file becomes a node in a graph whose public contract and private design are consumed differently by tools and agents. In template-constrained document conversion, spec.md is the clean Markdown source that a hybrid pipeline parses, segments, and maps into manifest-constrained LaTeX (Yang, 26 Mar 2026, Yang, 26 Mar 2026, Grabowski, 25 Jun 2026, Hei et al., 22 Jun 2026).

A recurrent design objective is the removal of hidden defaults. The simulation format requires all six sections; the imaging format fixes eight fields in order; the software-engineering framework requires explicit ownership and dependency declarations; and the LaTeX pipeline extracts template constraints into a reusable manifest rather than inferring them ad hoc at runtime. This structure is meant to make omission detectable and to support automated validation gates instead of informal review alone (Yang, 26 Mar 2026, Yang, 26 Mar 2026, Grabowski, 25 Jun 2026, Hei et al., 22 Jun 2026).

2. Core structures and formal grammars

The principal spec.md variants differ in their concrete syntax but converge on fixed schemas and typed field semantics.

Setting	Core structure	Mandatory or checked elements
Scientific simulation	Six-tuple $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$	Domain, Equations, Boundary Conditions, Initial Conditions, Observables, Tolerance
Imaging-system design	Structured 8-field plaintext specification	modality, carrier, geometry, object, forward_model, noise, target, system_elements
AI-assisted software development	One SPEC.md per graph node	kind, id, owner, depends_on, children, plus Contract and Design views
Template-constrained conversion	Clean Markdown parsed to AST and chunks	Headings, assets, semantic metadata, citation data, manifest-constrained layout

For scientific simulation, the published EBNF defines spec_file ::= header domain equations boundary initial observables tolerance { extension }, with all six domain sections mandatory. The mathematical payload is not merely descriptive: well-posedness is checked through a Lipschitz condition, primitive-level convergence is modeled as $\epsilon_i \le C_i h_i^{q_i}$ with $q_i>0$, and error propagation through a primitive DAG is bounded by

$$\epsilon_{\text{total}} \le \sum_i \ell_i \epsilon_i.$$

The parser produces an AST and then a typed six-tuple object in Python, which the Judge Agent uses both before execution and during post-execution audit (Yang, 26 Mar 2026).

For imaging, the formal grammar centers on the forward_model field as a left-to-right chain over an 11-element Finite Primitive Basis:

$\{\Pi, F, M, C, P, W, \Sigma, S, D, R, \Lambda\}.$

The chain must form a DAG, satisfy type compatibility between adjacent primitives, respect node count ≤ 20 and depth ≤ 10, constrain nonlinear primitives to ≤ 2 parameters within known physical bounds, admit an adjoint, and achieve representation error < 1%. This grammar makes the spec simultaneously descriptive of the physical apparatus and compilable into a forward operator (Yang, 26 Mar 2026).

For software architecture, the formal object is a directed graph $G=(N,E_o,E_d)$ in which each node corresponds exactly to one SPEC.md file. Each node has a C4 kind ∈ {system, container, component, code} and two orthogonal views: Contract, containing invariants, types, error behaviour, and acceptance criteria; and Design, containing children, code ownership, implementation constraints, and internal relations. Ownership edges form a rooted tree, dependency edges form a DAG, and both are constructed by indexing front matter such as kind, id, owner, depends_on, and children (Grabowski, 25 Jun 2026).

3. Verification, compilation, and agentic workflows

In the simulation setting, spec.md is embedded in a five-gate pre-execution workflow and a post-execution audit. Gate 1 checks dimensional consistency and variable definitions; Gate 2 checks BC/IC compatibility and existence of unique solution spaces; Gate 3 applies well-posedness criteria such as coercivity, Poincaré inequality, and CFL while estimating Lipschitz constants; Gate 4 requires classification into supported primitive decompositions; and Gate 5 checks that the mesh resolution needed to satisfy the tolerance is computationally feasible. After execution, the Judge Agent computes residuals $R=Au-f$, checks conservation laws, symmetry, and monotonicity, and recomputes the bound $\epsilon_{\text{total}} \le \sum \ell_i \epsilon_i$. In the reported benchmark, silent failures drop from 42 % → 6 % in pre-gates and 6 % → 1.5 % after audit (Yang, 26 Mar 2026).

The imaging workflow uses a parallel Plan–Judge–Execute decomposition. The Plan Agent maps a one-sentence natural-language description into the eight fields of spec.md, the Judge runs structural compiler checks C1–C6 and triad gates G1–G3, and the Execute Agent emits an approximate forward operator $\hat A$, a recommended reconstruction method, and an explicit error-bound report. The associated design-to-real error theorem decomposes reconstruction error into $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$0, $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$1, $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$2, $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$3, $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$4, and $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$5, with each term linked to a corrective action such as chain correction, parameter calibration, or tier-lifting to fuller physics (Yang, 26 Mar 2026).

In software development, the same specification artifact becomes a merge-blocking governance device. The context assembler computes

$$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$6

excluding sibling specs, dependency code, and transitive dependency designs. The drift gate then compares an Intent Graph from SPEC.md files against an Evidence Graph from static code analysis. Hard-error conditions include orphan code, undeclared dependency, dependency bypass, and missing dependency contract; warnings cover declared dependencies with no code evidence, public exports absent from the contract, and contract behaviour lacking test evidence. The gate is explicitly boolean rather than threshold-based: drift is enforced as a blocking merge condition (Grabowski, 25 Jun 2026).

Related verification ecosystems illuminate how structured specifications are stress-tested. K-YAML in the K Framework encodes specifications as matching-logic implications over pre- and post-state cell patterns, supports incremental rule construction with inherits:, and uses mutation testing over 32 mutants to detect specification gaps: a healthy specification and prover should fail on every mutant. In Ethereum’s “specification is law” architecture, an off-chain trusted deployer uses verifyCreation₍⊑₎(spec, code) and verifyUpgrade₍⊑₎(spec, code) to enforce that deployments and upgrades refine a Solidity specification stub with @notice invariant and @notice postcondition annotations. In ACSL synthesis for C, GPT-4 is augmented with PathCrawler traces and EVA alarms so that concrete I/O patterns and runtime-error conditions can be translated into requires, ensures, assigns, and loop invariants (Bugrara, 2019, Antonino et al., 2022, Granberry et al., 2024).

4. Domain-specific embodiments

In scientific computing, spec.md is a solver-independent problem specification. A minimal example for Poisson on the unit square includes symbolic equations, homogeneous Dirichlet boundary conditions, an observable defined as an $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$7 error against an exact solution, and a numeric threshold 1e-4. The Judge uses the resulting typed object to run dimensional checks and feasibility analysis before any solver is selected (Yang, 26 Mar 2026).

In computational imaging, spec.md becomes a design description for instruments rather than just a PDE statement. Published examples include clinical CT, CASSI, and accelerated MRI, each with explicit carrier type, measurement geometry, object model, primitive-chain forward model, noise model, target metric such as PSNR ≥ 30 dB or SSIM ≥ 0.90, and hardware plus calibration data in system_elements. The same schema is intended to cover 173 designable modalities drawn from five carrier families (Yang, 26 Mar 2026).

In AI-assisted software engineering, SPEC.md is not a single global file but a graph of files distributed across a repository. A recommended layout places ARCHITECTURE.md at the root, stores all node specifications under /specs/, and separates system-, container-, component-, and code-level files. A component example declares depends_on, children, public invariants such as “Checkout total must never go negative,” and private implementation constraints such as calling api.payment.charge before marking an order paid (Grabowski, 25 Jun 2026).

In smart-contract analysis, spec.md can be synthesized from behavior rather than authored first. SmCon mines transaction histories by trace slicing and predicate abstraction, infers an EFSM $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$8, and generates a ready-to-use Markdown specification skeleton containing API summaries, state-machine diagrams, and usage scenarios. The reported evaluation covers eleven well-studied Azure benchmark smart contracts and six popular real-world DApp smart contracts, with mined specifications used to enhance symbolic analysis and achieve up to 56% speedup (Liu et al., 2024).

In standards engineering, the same idea appears as single-source specification generation. Wasm SpecTec starts from a DSL, transforms it through EL, IL, and AL, and emits formal rules in math, Markdown pseudocode, reference interpreter code, unit tests, and a final spec.md. The intent is to generate all standardization artefacts required by the Wasm process from one checked source rather than maintaining handwritten versions separately (Breitner et al., 2023).

5. Single-source generation and interoperability

A major theme across the literature is that a structured specification should not terminate at documentation. In Wasm SpecTec, the same DSL definitions feed LaTeX, prose, OCaml or JavaScript extraction, test generation, and prover backends. Because all artefacts share the same EL/IL/AL pipeline, prose, tests, interpreter, and PDF are intended to remain in lock-step with the formal definition. This is an explicit single-source-of-truth architecture (Breitner et al., 2023).

The document-conversion setting operationalizes spec.md in a different direction: from structured Markdown to template-compliant typesetting. The Dual-Track Framework first extracts template constraints into a manifest $$(\mathcal{D}, \mathcal{E}, \mathcal{B}, \mathcal{I}, \mathcal{O}, \epsilon)$$9 containing packages, environments, sections, and macros; then, online, it parses spec.md, segments it into chunks, routes deterministic regions through rule-based mapping and reasoning-intensive regions through manifest-constrained LLM calls, assembles the output, and resolves citations. On 7 LaTeX templates and 56 published research papers, the reported compilation success rate is 0.946, compared with 0.821 for a Pandoc baseline and 0.625 for a monolithic LLM; compilation time drops from 208.5 s → 40.6 s, and token use is reduced by –24.1% input and –60.7% output tokens (Hei et al., 22 Jun 2026).

Interoperability also appears in more traditional specification formats. The reactive-synthesis extension of SMV adds ENV_AUTOMATON_SPEC and SYS_AUTOMATON_SPEC, marks controllable variables with --controllable, and converts the result to extended AIGER or standard SYNTCOMP via scripts such as spec_2_aag.py and justice_2_safety.py. H5MD, although not named spec.md, provides an analogous example of a structured, portable specification for molecular data built on HDF5 with a strict hierarchy, naming scheme, and module system. These adjacent systems show that spec.md belongs to a broader family of executable and transformable specification media rather than to prose documentation alone (Khalimov, 2016, Buyl et al., 2013).

6. Limitations, boundaries, and unresolved issues

The cited systems do not define a single universal spec.md standard. The six-section scientific-simulation schema, the eight-field imaging schema, the graph-structured repository SPEC.md, and manifest-oriented Markdown drafts are mutually non-isomorphic. This suggests that spec.md is best understood as a naming convention for structured, operational specifications rather than as one stable grammar across domains (Yang, 26 Mar 2026, Yang, 26 Mar 2026, Grabowski, 25 Jun 2026, Hei et al., 22 Jun 2026).

Several limitations are domain-specific and technically substantive. In scientific simulation, the residual 1.5% failure rate concentrates at bifurcation points where certifiability breaks down and Lipschitz constants diverge. In imaging, parameter mismatch $\epsilon_i \le C_i h_i^{q_i}$0 dominates for well-conditioned systems, while unmodeled physics $\epsilon_i \le C_i h_i^{q_i}$1 dominates in scattering-heavy settings; the reported theorem tightness ratio is $\tau \in [1.8,5.2]with median2.9`. In K-YAML verification, dynamic loops may require explicit invariants over EVM stack and memory cells or recompilation under an optimizer that eliminates the loop. In “specification is law,” the framework handles partial correctness only, with no termination proofs or liveness, and treats data-structure refinements and interface extensions as out of scope. Wasm SpecTec still faces adoption, feature-drift, and toolchain-maturity issues, while the extended SMV synthesis format assumes deterministic guarantees and safety-type assumptions (Yang, 26 Mar 2026, Yang, 26 Mar 2026, Bugrara, 2019, Antonino et al., 2022, Breitner et al., 2023, Khalimov, 2016).

Despite these differences, the literature converges on a common technical thesis: a specification becomes materially more useful when it is structured enough to be parsed, checked, transformed, audited, and kept synchronized with code or execution artefacts. Whether the target is solver-independent scientific computation, imaging-system design, architecture governance, smart-contract verification, or standards generation, spec.md functions as a compact boundary object between informal requirements and mechanically enforced behavior (Yang, 26 Mar 2026, Yang, 26 Mar 2026, Grabowski, 25 Jun 2026, Breitner et al., 2023).