MSFM Explained: How Annotated Markdown Compiles Into Apps

What Is MSFM?

MSFM (MindStudio-Flavored Markdown) is the format Remy uses to turn natural language specs into production applications. It’s a strict superset of Markdown that adds three primitives: block annotations, inline annotations, and pointers. These let you attach precision to prose so an AI compiler produces consistent results.

A spec written in MSFM is readable in any Markdown viewer. Annotations render as code blocks and bracketed text. Nothing breaks. But when Remy reads the spec, those annotations resolve ambiguities that would otherwise produce inconsistent code.

At a Glance

• Strict superset of Markdown — valid Markdown is valid MSFM, renders normally in GitHub/VS Code
• Three annotation primitives — block annotations (~~~), inline annotations ([text]{content}), pointers ({#id})
• Structured blocks — typography and color definitions with language tags (```typography, ```colors)
• Additive precision — a bare spec with no annotations is valid; each annotation makes compilation more deterministic
• One file — no sidecars, no imports, email it or paste it into a chat
• Readable by AI and humans — designed for LLM consumption and human review

Why Does MSFM Exist?

Natural language is ambiguous. “Three areas of review” might mean three sequential stages or three parallel tracks. “Amount” might mean integer cents or decimal dollars. “Status” might be any string or a fixed enum.

Code is unambiguous but verbose. A TypeScript interface with explicit types, constraints, and edge-case handling is precise but takes 50 lines to say what prose says in two sentences.

MSFM splits the difference. Write the domain in prose. Annotate the parts where ambiguity matters. The compiler gets both: the big picture from the prose, the precision from the annotations.

This is the structural difference between Remy and coding agents like Claude. Coding agents edit existing code. Remy compiles a spec. The spec is the source of truth. The code is compiled output.

What Are Block Annotations?

A block annotation is a fenced block using tildes (~~~) that attaches to the content immediately above it:

When requesting a new vendor, there are three areas of review:
governance, legal, and accounting, with approvals flowing in that order.

~~~
The spec says "three areas" but lists four names. From the process flowchart, it is three sequential stages:

  1. Governance, Risk & Compliance (GRC), one combined stage
  2. Legal
  3. Accounts Payable (AP)

These are sequential. Each stage must complete before the next is notified. If any stage rejects, the entire request is rejected.
~~~

The annotation clarifies an ambiguity in the prose. “Three areas” names four things. Without the annotation, the agent might generate four separate stages. With it, the agent knows it’s three.

Rules for Block Annotations

• Starts and ends with ~~~ on its own line
• Attaches to the nearest preceding block element (paragraph, heading, table, list)
• Multiple annotations can follow the same element (read in order)
• Can contain any Markdown content (use backtick code fences inside; they coexist with tilde fences)
• Renders as a code block in standard Markdown viewers

When Should You Use Block Annotations?

Block annotations resolve ambiguity at the paragraph or section level. Use them for:

• Edge cases — “What happens when a reviewer rejects?”
• Data representations — “Amounts are in USD cents (integer), not decimal dollars”
• Business rules — “Sequential stages, not parallel tracks”
• Clarifying scope — “The AP team in this context refers to the internal accounts payable department, not a vendor’s AP”

What Are Inline Annotations?

Inline annotations attach to a specific word or phrase:

All invoices can be sent to the [Accounts Payable]{The AP team in
this context refers to the internal accounts payable department, not
a vendor's AP. Only users with the "ap" or "admin" role can process
invoices.} team for processing against the PO.

The [text] is the visible, highlighted span. The {content} is the annotation, hidden by default in a rich editor and visible as literal text in plain Markdown.

When Should You Use Inline Annotations?

Good for definitions, units, and clarifications:

The PO [amount]{Total across all line items, in USD cents (integer).
Does not include tax, shipping, or fees.} must not exceed the approved
budget for the [cost center]{The organizational budget code that this
purchase is charged to.}.

Inline annotations keep the prose readable while pinning down the specifics the compiler needs.

What Are Pointers?

When an annotation is too large for inline placement (lists, code, tables), use a pointer:

The AP team pays the vendor according to the [contract payment terms]{#payment-terms}.

~~~#payment-terms
We do not model payment terms (net 30, net 60, etc.) on the PO or vendor. The dueDate on the invoice is the sole payment trigger.

A production implementation would:
- Store terms on the vendor record (net_30, net_60, due_on_receipt)
- Auto-calculate dueDate from invoiceDate + terms
- Support early payment discounts (2/10 net 30)

Default behavior when no terms are specified: due on receipt.
~~~

The {#payment-terms} inline reference points to the ~~~#payment-terms block. Keep the block co-located, right after the paragraph containing the pointer.

A single block annotation can be referenced by multiple pointers. Useful for concepts like “amounts are in USD cents” that apply in several places.

How Do Typography Blocks Work?

Spec files can contain fenced code blocks with special language tags that define structured data. These are standard markdown code fences, not MSFM-specific syntax. The MindStudio editor renders them as rich interactive UI; in a plain markdown viewer they appear as readable YAML.

```typography blocks declare fonts with source URLs and named type styles:

```typography
fonts:
  - name: Inter
    source: https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700
  - name: JetBrains Mono
    source: https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500

styles:
  - name: Heading 1
    font: Inter
    size: 32px
    weight: 700
    letterSpacing: -0.02em
    lineHeight: 1.2
    description: Page titles and primary headings

  - name: Body
    font: Inter
    size: 16px
    weight: 400
    lineHeight: 1.5
    description: Default body text

  - name: Code
    font: JetBrains Mono
    size: 14px
    weight: 400
    lineHeight: 1.6
    description: Inline code and code blocks
```

How Do Color Blocks Work?

```colors blocks declare named colors with hex values and descriptions:

```colors
- name: Primary
  value: "#2563eb"
  description: Primary brand color for CTAs and links

- name: Background
  value: "#ffffff"
  description: Default page background

- name: Text Primary
  value: "#1f2937"
  description: Body text and headings

- name: Border
  value: "#e5e7eb"
  description: Dividers and input borders
```

These typically live in src/interfaces/@brand/visual.md and define the app’s design system. The agent uses them when generating frontend code; the user edits them through the editor’s visual UI.

How Does Remy Use MSFM?

When Remy reads a spec:

1. Understands the domain. The prose gives it the big picture: what the app does, who uses it, how it works.
2. Reads annotations for precision. Annotations resolve the ambiguities that would otherwise produce inconsistent code.
3. Generates the contract. Methods, tables, and roles in dist/ that implement the spec.
4. Maintains consistency. When modifying code, the agent checks against the spec to ensure changes are semantically correct, not just syntactically valid.

The spec is also what makes the project onboardable. A new developer (or a different AI agent) can read src/app.md and understand the entire application without reading any code.

What Are the Authoring Conventions?

Annotate Ambiguity, Not the Obvious

If a statement has only one reasonable interpretation, leave it alone. Annotations resolve genuine ambiguity, places where two engineers might implement different things.

Pin Down Edge Cases

The most valuable annotations answer “what happens when…”:

• What happens when a reviewer rejects?
• What happens when the amount is exactly on the threshold?
• What happens when no user has the required role?
• What happens when this is called twice?

Specify Data When It Matters

When “amount” could mean integer cents or decimal dollars, annotate the representation. When “status” could be any string, list the valid values.

Let the Spec Breathe

Not every paragraph needs annotations. A spec with more annotation than prose is over-specified. Annotate the hard parts. Trust the compiler on the straightforward parts.

Is MSFM Compatible With Standard Markdown?

Yes. MSFM is a strict superset of Markdown. Every valid Markdown document is valid MSFM.

MSFM feature	Renders as in standard Markdown
Block annotation (~~~...~~~)	Fenced code block
Inline annotation ([text]{content})	Literal text with brackets
Pointer ([text]{#id})	Literal text
Tagged block (~~~#id)	Fenced code block with #id visible
Typography block (```typography)	YAML code block
Colors block (```colors)	YAML code block
Everything else	Standard Markdown

Specs are fully readable in GitHub, VS Code, or any Markdown previewer. The annotations are visible as literal text. Nothing breaks.

How Does MSFM Compare to Other Spec Formats?

Most spec formats are either too loose (plain text, no structure) or too rigid (JSON schemas, YAML configs). MSFM sits in the middle:

• Plain text — readable but ambiguous. Two engineers reading the same spec might build different things.
• JSON/YAML schemas — unambiguous but verbose. A 50-line schema says what prose says in two sentences.
• MSFM — readable prose with annotations where ambiguity matters. The compiler gets both the big picture and the precision.

This is the same pattern Claude Code’s agentic workflow patterns use for structuring complex tasks. The difference is that Claude Code workflows operate on existing code. Remy compiles a spec into new code. Understanding the WAT framework (workflows, agents, and tools) helps clarify when to use spec-driven compilation versus code-editing agents.

What About Version Control?

MSFM specs are plain text files. They diff cleanly in git. A one-line change to a paragraph shows up as a one-line diff. Annotations are part of the text, so they diff too.

This is different from visual no-code tools where the “source of truth” is a database or proprietary format. With MSFM, the spec is a .md file. You can email it, paste it into a chat, or version it in git like any other source file.

Example: A Complete MSFM Spec

Here’s a minimal but complete spec for a vendor approval workflow:

---
name: Vendor Approval Workflow
version: 1
---

# Vendor Approval Workflow

A simple workflow for requesting and approving new vendors.

~~~
Roles:
- requester: can submit vendor requests
- approver: can approve or reject requests
- admin: full access

Data model:
- vendors table with name, contactEmail, status, taxId
- status is one of: pending, approved, rejected
~~~

## Submitting a Request

A requester submits a vendor request with the vendor's name, contact email, and tax ID. The request starts in [pending]{Status is set to "pending" on creation. Only approvers and admins can change it.} status.

~~~
Validation:
- name: required, non-empty string
- contactEmail: required, valid email format
- taxId: required, matches pattern XX-XXXXXXX (US EIN format)
~~~

## Approval Flow

An approver reviews the request and either approves or rejects it. If approved, the status changes to [approved]{Once approved, the vendor can be used for purchase orders. Approved vendors cannot be rejected later — they can only be archived (future feature).}. If rejected, the status changes to rejected and the requester is notified.

~~~
Edge cases:
- If a request is already approved or rejected, attempting to approve/reject again throws an error: "This vendor has already been reviewed."
- Only users with the "approver" or "admin" role can approve or reject.
- The requester cannot approve their own request.
~~~

This spec compiles into:

• A vendors table with typed columns
• A submitVendorRequest method with validation
• An approveVendor method with role checks
• A rejectVendor method
• Role definitions for requester, approver, and admin

The prose describes the workflow. The annotations pin down the data types, validation rules, and edge cases.

What Is Remy?

Remy is a product agent that compiles annotated markdown into a full-stack app — backend, database, frontend, auth, tests, and deployment — in a single step. See goremy.ai.

FAQ

Can I write MSFM by hand or do I need Remy?

You can write MSFM by hand. It’s just Markdown with annotations. But Remy users don’t write MSFM manually — they describe what they want in plain language (voice, text, or pasted documents), and the agent generates the MSFM spec on their behalf. The spec is the compiled output of the conversation, not something you author directly.

If you’re building on the MindStudio platform directly (not through Remy), you can write MSFM specs by hand and the platform will compile them.

Does MSFM work with other AI models?

MSFM is a format, not a product. Any AI model that can read Markdown can read MSFM. The annotations are just more context. Whether the model produces consistent code from the spec depends on the model’s capabilities and the quality of the annotations.

Remy uses MSFM because it’s the format that produces the most consistent results across multiple compile passes. Other tools might use different formats.

What if I want to edit the compiled code directly?

You can. The compiled code in dist/ is real TypeScript. You can edit it by hand, add npm packages, refactor methods, whatever you want. But the spec in src/ is the reset point. If you regenerate from the spec, your hand edits are overwritten.

The right workflow is: update the spec to capture the change, then recompile. That way the spec stays in sync with the code.

How does MSFM handle breaking changes to the spec?

When you change the spec, Remy diffs the new version against the old version and generates a migration. New tables get CREATE TABLE. New columns get ALTER TABLE ADD COLUMN. Dropped columns get ALTER TABLE DROP COLUMN. Type changes and renames are not supported in the automatic migration path — those require manual intervention.

The spec is versioned in git like any other source file. A breaking change shows up as a diff in the spec file.

Can I use MSFM for non-Remy projects?

Yes. MSFM is a format, not a product. You can use it to document any project where you want to attach precision to prose. It’s just Markdown with annotations. Any tool that reads Markdown can read MSFM.

The structured blocks (typography, colors) are specific to the MindStudio platform’s design system, but the core annotation primitives (block, inline, pointers) are general-purpose.

What’s the learning curve for MSFM?

If you know Markdown, you know 90% of MSFM. The three annotation primitives (block, inline, pointers) take 5 minutes to learn. The hard part isn’t the syntax — it’s knowing where to annotate. That comes with practice.

The authoring convention “annotate ambiguity, not the obvious” is the key heuristic. If a statement has only one reasonable interpretation, leave it alone. If two engineers might implement it differently, annotate.

How does MSFM relate to other annotation formats like JSDoc or Python docstrings?

JSDoc and Python docstrings annotate code. MSFM annotates prose. The difference is the direction of compilation. JSDoc adds metadata to existing code so tools can extract types and generate docs. MSFM adds metadata to prose so tools can generate code.

Both are annotation systems, but they operate at different layers of abstraction.

Can I see a real MSFM spec?

The Remy documentation includes several example specs in the developer guide. The 02_spec-and-msfm.md file has the full syntax reference with examples.

The Debut gallery shows real apps built with Remy. Each app has a spec (not all are public, but the ones that are show production MSFM).

Start Building With Remy

MSFM is the format Remy uses to turn natural language into production applications. The syntax is simple: Markdown with three annotation primitives. The hard part is knowing where to annotate. That comes with practice.

If you want to see MSFM in action, the fastest way is to try Remy. Describe an app in plain language and watch the agent generate the MSFM spec, then compile it into a full-stack application.

Start building with Remy →