MSFM: The Markdown Syntax That Compiles Into Full-Stack Apps

What Is MSFM?

MSFM — MindStudio-Flavored Markdown — is the annotation language that turns a readable spec document into a compilable application. It’s the syntax layer that lets you write “the button should be green” in prose and have the compiler understand that as a precise color value, a CSS class, and a design token.

Think of it as markdown with three new primitives: block annotations, inline annotations, and pointer annotations. Regular markdown gives you headings, lists, and links. MSFM adds the ability to attach structured data — schemas, types, rules, code hints — directly to the prose. The result is a document that reads like English but compiles like code.

Remy uses MSFM as the source language for specs. When you describe an app to Remy, the agent writes MSFM. When you edit the spec, you’re editing MSFM. When the compiler runs, it reads MSFM and generates TypeScript, SQL schemas, React components, auth flows, the whole stack.

At a Glance

• Format: Markdown superset with three annotation primitives (block, inline, pointer)
• Renders anywhere: GitHub, VS Code, ChatGPT, any markdown viewer
• Compiles to: TypeScript backends, SQL schemas, React frontends, deployment manifests
• Portability: Plain text, version-controllable, LLM-readable
• Used by: Remy (the product agent), MindStudio platform developers, any LLM that can read structured markdown
• Open spec: Documented at github.com/mindstudio-ai/remy/tree/main/docs

How Does MSFM Work?

MSFM extends markdown with three annotation primitives. Each one attaches structured data to a piece of prose without breaking readability.

Block annotations

Block annotations use triple-tilde fences with a type declaration. They look like code blocks but carry structured metadata instead of code.

~~~typography
font: "Inter"
headings: "Sora"
scale: 1.25
~~~

This block tells the compiler which fonts to load, what the type scale is, and how headings should render. A human reading the spec sees “the typography uses Inter and Sora.” The compiler sees a typed object it can validate and transform into CSS imports and design tokens.

Other common block types:

• ~~~colors — palette definitions with hex values and semantic names
• ~~~table — database schema with column types and constraints
• ~~~method — backend route signature with parameters and return type
• ~~~role — auth role with permissions

Inline annotations

Inline annotations use square-bracket syntax: [readable text]{structured data}. The text is what a human reads. The braces hold what the compiler needs.

Example:

The primary button should be [green]{color: "#10b981"}.

A human reads “green.” The compiler reads #10b981 and knows exactly which shade. This pattern shows up everywhere in MSFM specs:

• [the user's email]{field: "email", type: "string"} — prose + typed field reference
• [approved]{status: "approved"} — readable state + enum value
• [next Tuesday]{date: "+7d"} — natural language + parseable offset

The inline annotation keeps the spec readable while giving the compiler the precision it needs to generate correct code.

Pointer annotations

Pointer annotations reference a block by ID: [text]{#blockId}. They let you define something once in a block and reference it everywhere else without repeating the full definition.

Example:

~~~colors {#palette}
primary: "#3b82f6"
success: "#10b981"
danger: "#ef4444"
~~~

The submit button uses [the primary color]{#palette.primary}.

The {#palette.primary} pointer tells the compiler to pull the value from the colors block with ID palette. Change the palette block once, and every pointer updates automatically. This is how MSFM specs stay DRY (don’t repeat yourself) without sacrificing readability.

What Does a Real MSFM Spec Look Like?

Here’s a simplified example of an MSFM spec for a task-management app. This isn’t the full spec — just enough to show how the three annotation types work together.

# Task Manager

A simple task tracker with projects, tasks, and assignments.

~~~colors {#palette}
primary: "#3b82f6"
success: "#10b981"
warning: "#f59e0b"
~~~

~~~typography {#type}
font: "Inter"
headings: "Sora"
scale: 1.2
~~~

## Data Model

~~~table {#tasks}
name: tasks
columns:
  - id: integer, primary key
  - title: text, required
  - status: text, enum ["todo", "in_progress", "done"]
  - project_id: integer, foreign key -> projects.id
  - assigned_to: integer, foreign key -> users.id
~~~

~~~table {#projects}
name: projects
columns:
  - id: integer, primary key
  - name: text, required
  - color: text
~~~

## Methods

~~~method {#createTask}
name: createTask
parameters:
  - title: string
  - projectId: number
  - assignedTo?: number
returns: Task
description: Creates a new task in the specified project
~~~

When a user creates a task, call [createTask]{#createTask} with the [task title]{field: "title", type: "string"} and [project ID]{field: "projectId", type: "number"}. The task starts in [todo status]{status: "todo"} and appears in the project's task list.

## UI

The task list shows each task as a card. Completed tasks have a [green checkmark]{#palette.success}. In-progress tasks show a [warning-colored spinner]{#palette.warning}.

Notice:

• The colors and typography blocks define design tokens once
• The table blocks define the database schema with typed columns
• The method block defines the backend route signature
• Inline annotations like {field: "title", type: "string"} attach types to prose
• Pointer annotations like {#palette.success} reference the color palette

A human can read this spec and understand what the app does. The compiler can parse it and generate a working TypeScript backend, a SQL schema, and a React frontend.

Why Use MSFM Instead of Just Writing Code?

MSFM solves a specific problem: how do you write a spec that both humans and AI can read, edit, and reason about?

Code is precise but hard to skim. Prose is readable but ambiguous. MSFM sits in between. The prose layer gives you the narrative — what the app does, why it works this way, what the user experience should feel like. The annotation layer gives you the precision — types, constraints, references, the stuff the compiler needs.

This two-layer structure is what makes spec-driven development work. You can hand an MSFM spec to another developer and they’ll understand the app. You can hand it to an LLM and it’ll generate correct code. You can hand it to Remy and it’ll compile the whole stack.

And because MSFM is plain markdown, it renders everywhere. Open it in GitHub and you see a readable document. Open it in VS Code and you see the same thing. Paste it into ChatGPT and the model can read the annotations. The format is portable by default.

How Does MSFM Compare to Other Annotation Formats?

MSFM isn’t the first attempt at annotated prose. Literate programming (Knuth), Jupyter notebooks, and MDX all tried to blend narrative and code. MSFM differs in a few ways:

• Renders as plain markdown. MSFM doesn’t require a custom viewer. Any markdown renderer works. The annotations are just markdown syntax (fenced blocks, bracketed text). This makes MSFM specs readable in more places than MDX or Jupyter.
• Designed for LLMs. MSFM’s structure is optimized for language models to read and write. Block annotations are YAML-like (easy to parse). Inline annotations are JSON-like (easy to extract). Pointer annotations are explicit references (easy to resolve). An LLM can generate valid MSFM without a custom parser.
• Compiles to a full stack. MSFM isn’t just documentation. It’s the source language for a compiler that generates backends, databases, frontends, and deployment configs. The annotations aren’t hints — they’re the contract.

Is MSFM Vendor Lock-In?

No. MSFM is plain text. If Remy disappeared tomorrow, you’d still have a readable spec document you could hand to another LLM or another developer. The annotations are structured enough that any competent code-generation model could parse them and produce working code.

The compiled output (TypeScript, SQL, React) is also yours. You can edit it, deploy it, run it anywhere. The runtime (MindStudio’s execution sandbox, database layer, auth system) is the only piece tied to the platform. But the spec and the code are portable.

This is graduated portability — the spec is fully portable, the code is mostly portable, the runtime is not. That’s by design. The runtime is where the platform adds value (managed databases, auth, deployment, monitoring). The spec and code are where you keep control. For more on how memory and state layers work in AI-powered tools, see Claude Code’s three-layer memory architecture.

How Do You Write MSFM?

Most Remy users don’t write MSFM by hand. They describe what they want in natural language and Remy generates the MSFM spec. The agent handles the syntax, the structure, the annotations. You review it, edit it if needed, and approve it.

But if you want to write MSFM directly — or if you’re building on the MindStudio platform outside of Remy — the syntax is straightforward:

1. Start with prose. Write the spec as a readable document. Describe what the app does, how it works, what the user sees.
2. Add block annotations where you need structure. Database tables, method signatures, design tokens, roles — anything that needs a schema gets a block.
3. Add inline annotations where you need precision. Field references, enum values, type hints — anywhere the prose is ambiguous, add an inline annotation.
4. Add pointer annotations to avoid repetition. Define things once in a block, reference them everywhere else with pointers.

The full MSFM reference is in the Remy developer guide. If you’re curious about the mechanics, start there.

What Can You Build With MSFM?

Anything you can describe in a spec, you can build with MSFM. The format is general-purpose. It’s not limited to a specific app shape or domain.

Examples of what Remy has compiled from MSFM specs:

• Internal tools: Approval workflows, vendor management, content moderation queues
• Vertical SaaS: CRMs, project trackers, client portals
• AI-powered apps: Content generators, image editors, autonomous task agents
• Multi-interface apps: Web frontends + REST APIs + conversational agents + cron jobs, all from one spec

The constraint is the platform’s capabilities (TypeScript backends, SQL databases, web frontends, no native mobile). Within that, MSFM is flexible enough to describe most full-stack web apps.

How Does MSFM Relate to Other Remy Concepts?

MSFM is the syntax layer. It’s one piece of a larger system:

• The spec is the source of truth — the markdown document that describes the app
• MSFM is the annotation language used inside the spec
• The manifest (mindstudio.json) is the compiled contract — the structured representation of what the spec declares
• The methods are the backend routes the compiler generates from the spec
• The interfaces (web, API, Discord, Telegram, cron) are the surfaces that invoke those methods

MSFM is how you write the spec. The manifest is what the compiler reads. The methods are what the app runs. They’re connected but distinct layers.

For more on how these pieces fit together, see the WAT framework explanation — it covers the three-layer model (spec → contract → interfaces) that MSFM plugs into.

Can Other Tools Use MSFM?

Yes. MSFM is an open format. Any LLM that can read structured markdown can parse MSFM. Any code-generation tool that wants a readable, annotated spec format can adopt it.

Remy uses MSFM because it’s optimized for the product-agent workflow (describe → align → compile). But the format itself isn’t Remy-specific. If another tool wanted to compile MSFM specs into code, the syntax is documented and the examples are public.

The MindStudio platform also uses MSFM for developers building apps directly (without Remy). The developer guide documents the full MSFM reference for that audience. Same syntax, different entry point. For developers interested in building personal knowledge systems with structured specs, Andrej Karpathy’s LLM Wiki approach shows how annotated markdown can serve as a foundation for AI-assisted development.

FAQ

Is MSFM just markdown with YAML blocks?

Mostly, yes. Block annotations are YAML-like. Inline annotations are JSON-like. Pointer annotations are custom but simple ({#id.field}). The syntax is intentionally familiar so it’s easy to read and write.

Do I need to learn MSFM to use Remy?

No. Remy generates the MSFM for you. You describe what you want in natural language and the agent writes the spec. You can edit the MSFM if you want, but most users just review it and approve it.

Can I use MSFM outside of Remy?

Yes. MSFM is the annotation format for the MindStudio platform. If you’re building apps on the platform directly (without Remy), you write MSFM specs by hand. The developer guide has the full reference.

What happens if I edit the MSFM spec after Remy generates it?

Remy stays in sync. If you edit the spec, Remy can recompile the code to match. If you edit the code, Remy can update the spec to reflect the changes. The spec is the source of truth, but the system is bidirectional.

Is MSFM versioned?

Not formally yet. The syntax is stable enough for production use but may evolve as the platform adds features. Breaking changes would be announced and migrated. For now, treat it as a living spec.

Can I see real MSFM examples?

Yes. The Remy repo has example specs in the docs. The Debut gallery shows real apps built with Remy — some of those have public specs you can browse.

How does MSFM handle edge cases and validation rules?

Inline annotations and block annotations can carry validation logic. For example, a table column can have constraints (required, unique, min, max). A method parameter can have validation rules (email format, length > 5). The compiler reads these and generates the corresponding backend validation code.

What’s the difference between MSFM and the manifest?

MSFM is the human-readable spec format. The manifest (mindstudio.json) is the machine-readable contract the compiler generates from the spec. MSFM is what you edit. The manifest is what the platform reads at runtime. They stay in sync via the compile step.

How does Remy stay useful as AI models improve?

The spec is the source of truth. As models improve, Remy can recompile the same spec with better code generation, newer frameworks, or optimized patterns. The app upgrades without rewriting the spec. The annotation layer ensures the contract stays stable even as the implementation evolves.

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. MSFM is the annotation language Remy uses to write specs. See goremy.ai.

---

MSFM is the syntax layer that makes spec-driven development work. It’s readable enough for humans, structured enough for compilers, and portable enough to outlive any single tool. If you’re building with Remy, you’re writing MSFM whether you know it or not. If you’re building on the MindStudio platform, MSFM is the source language. Either way, it’s worth understanding how the annotations work and why the format is designed this way.

The next time you see a Remy spec, look for the block annotations, the inline annotations, and the pointer annotations. That’s MSFM doing its job — turning prose into precision without sacrificing readability.

Start building with Remy →