MimiSpec embeds a progressive workflow — from uncertainty to structured to fully locked — directly into the syntax. Every phase of design is a syntactically valid .mms file.
// Phase 1: Raw intent, fully delegated to AI
module?? Shop:
type?? Order:
desc?? "Order data, including buyer, product, amount, and status"
func?? Pay:
steps:
desc?? "Check balance"
desc?? "Deduct payment"
// Phase 5: Fully locked architecture
module$ Shop:
type$ OrderStatus: New | Pending | Paid | Shipped | Cancelled
rule$ "Payment must be idempotent"
func$ Pay(order, amount):
requires$: order.status == Pending
ensures$: order.status == Paid
steps:
check$ balance
charge$ payment
order.status$ = Paid >>> done
| Feature | Description |
|---|---|
| 🧩 Fragment Architecture | Any syntax subtree is a valid top-level Fragment — module, type, flow, func, ui, steps, expressions, UI nodes |
| 📈 Progressive Precision | desc → requires/ensures → math: blocks, step by step |
| 🔒 Commitment System | $/$$ for confirmed, ?/?? for uncertainty — 9 combinations |
| ⛓️ Constraint Chains | rule front-attachment from file-level to function-level |
| ➗ Structured Math | math: blocks with tensor ops, linear algebra, calculus |
| 🎯 State Machine | flow definitions with >>> transition operator |
| 🖼️ UI Views | stack/parallel layouts, on event bindings, Saga compensation |
| 🛡️ Error Recovery | Multi-level synchronization, never loses the AST |
| 🦀 Pure Rust | Zero runtime dependencies, single binary CLI |
# From crates.io (CLI tool)
cargo install mimispec
# Or as a library
cargo add mimispec
# Or build from source
git clone https://github.com/ontonous/mimispec.git
cd mimispec
cargo build --releasemimispec path/to/file.mms --ast # dump AST
mimispec path/to/file.mms --json # JSON output (for IDE)
mimispec path/to/file.mms --render # render back to source
mimispec path/to/file.mms --latex # render math to LaTeX
echo "func Hello: steps:\n say hi" | mimispec - --ast # stdin
mimispec *.mms --json # multiple files[dependencies]
mimispec = "0.1"use mimispec::parse;
let source = r#"
type Status: Active | Inactive
func Toggle(user):
requires: user.status in [Active, Inactive]
steps:
user.status = Inactive >>> done
"#;
let result = parse(source);
if result.errors.is_empty() {
println!("{} fragments", result.file.fragments.len());
} else {
for err in &result.errors {
eprintln!("{}", mimispec::format::format_diagnostic(err, source));
}
}| Structure | Example |
|---|---|
| Enum | type Status: New | Pending | Paid |
| Record | type Order:\n id: u64\n status: Status |
| Function | func Pay(order):\n requires: order.status == Pending\n steps:\n charge payment >>> done |
| State Machine | flow Lifecycle:\n New >>> Pending:\n Pending >>> Paid:\n Paid >>> Done: |
| UI View | ui Panel binds Model:\n stack:\n "Title" on tap: DoSomething() |
| Parallel | parasteps "Load Data":\n load users\n load orders |
| Math | math:\n scores = Q @ K.T / sqrt(d_k) |
Full syntax: docs/specification.md
mimispec/
├── src/
│ ├── main.rs # CLI entry
│ └── lib/
│ ├── mod.rs # Public API (parse, tokenize)
│ ├── ast.rs # AST types
│ ├── error.rs # Error system
│ ├── lexer.rs # Lexer (indent/dedent)
│ ├── parser/
│ │ ├── mod.rs # Parser core
│ │ ├── expr.rs # Pratt expression parser
│ │ ├── fragment.rs # Fragment dispatch
│ │ ├── func.rs # FuncDef parser
│ │ ├── module.rs # Module parser
│ │ ├── flow.rs # FlowDef parser
│ │ ├── step.rs # Step parser
│ │ ├── type.rs # TypeDef parser
│ │ ├── ui.rs # UiDef parser
│ │ └── rule.rs # RuleDef parser
│ ├── render.rs # AST → source renderer
│ ├── render_util.rs # Expression precedence utils
│ ├── format.rs # Diagnostic formatter
│ └── latex.rs # LaTeX math renderer
├── docs/
│ ├── specification.md # Syntax specification
│ ├── advanced-usage.md # Advanced usage
│ ├── version-management.md # Version management
│ └── stdlib-api.md # Stdlib API reference
├── mimispec-parser-mms/ # Reference parser in MimiSpec
├── editors/
│ ├── vscode/ # VS Code extension
│ └── monaco/ # Monaco reference integration
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
└── AGENTS.md # AI agent guide
| Document | Description |
|---|---|
| Syntax Specification | Full language reference (1329 lines) |
| Advanced Usage | Modular design, contracts, Saga, ML specs |
| Version Management | SemVer, branching model, CI/CD |
| Stdlib API | Mimi runtime 16-module reference |
| Contribution Guide | Dev environment & PR workflow |
| Code of Conduct | Community guidelines |
| Security Policy | Vulnerability reporting |
Full extension with .mms syntax highlighting and CLI-driven live diagnostics:
cd editors/vscode
npm install && npm run compile
code --install-extension mimispec-vscode-*.vsixReference implementation with Monarch tokenizer and completion provider:
import { registerMimiSpecLanguage } from './mimispecLanguage';
registerMimiSpecLanguage(monaco);See editors/monaco/ for details.
From Scratch to Full — Fragments are the starting point, aggregation is the process, completeness is the result.
| Principle |
|---|
Write desc "..." when uncertain, AI fills the details |
Add ? for ambiguity, $ when locked |
Every fragment is a valid .mms file |
| The parser never rejects for incompleteness |
Q: How is MimiSpec different from TypeSpec / Smithy / OpenAPI?
A: MimiSpec targets human-AI collaboration, not just API contracts. Its progressive precision model (desc → structured → locked) and Fragment architecture are designed for iterative design workflows with AI partners.
Q: Can I use MimiSpec without AI?
A: Yes. MimiSpec is a fully self-contained specification language. AI tooling is an optional layer.
Q: What is the difference between .mms and .mimi?
A: .mms (MimiSpec) is the intent design layer — progressive, human-readable, fragment-friendly. .mimi (Mimi) is the production compile target — contract-verified, LLVM-compiled, with structured concurrency and linear capabilities.
Q: Is this ready for production?
A: The parser (v0.1) is fully functional — published on crates.io with 77 unit tests passing, error recovery, and complete AST rendering. CLI binary installable via cargo install mimispec. Production tooling (cross-file linking, LSP, Mimi compilation) is on the roadmap.
Q: How do I contribute?
A: See CONTRIBUTING.md. All contributions — code, docs, issues — are welcome.
Please report security vulnerabilities to ontonous@gmail.com.
See SECURITY.md for details.
Apache 2.0 © 2026 ontonous. See LICENSE.