MAIAS — Mobile App Information Architecture Schema

An open standard for describing an app's information architecture — screens, navigation, flows, UI elements, states, and data dependencies — in one YAML (or JSON) document that is equally readable by humans and operable by agents.

maias: "0.3"
app:
  name: Todo List
  navigation:
    primary:
      screens: [home, settings]     # ← the tab bar, derived, not drawn
  flows:
    - name: main
      entry_screen: home
      screens: [home, task_detail, task_new]
screens:
  - id: home
    title: My Tasks
    type: list
    path: /tasks
    description: All tasks, newest first.
    elements:
      - label: Buy milk
        type: list_item
        target: task_detail          # ← references are validated, renames cascade

Why: a common language for human–agent collaboration on app development. An agent can build the described app from the document (implementation guide), create and edit documents as safe machine operations (CLI, MCP), and a human can read and review the same file.

New here? Watch the short video tour — what MAIAS is, why it exists, and the plugin in action: TechPdM/maias-showcase.

What's in this repo

The spec	docs/spec/ — 11 chapters · llms.txt (one-context-window agent reference) · schema/maias.schema.json
@maias/core	packages/core — parse → typed model → serialise with round-trip fidelity (comments survive edits), graph utilities, safe edits (cascading renames, element batches), canonical formatter, Hermes-safe validation
maias CLI	packages/cli — maias validate (schema + semantic lint, --json), maias fmt, maias rename
MCP server	packages/mcp — validate / query / edit / edit_elements tools for any MCP-capable agent
MAIAS Browser	MAIAS_browser — Expo app that opens any MAIAS document at runtime and renders it: dynamic tab bar, pluggable design-system adapters (wireframe · shadcn-style · blueprint), in-app validation errors
Examples	examples/ — calculator · todo_list · social_network · ecommerce — collectively covering every core element and screen type
Claude skills	.claude/skills/ — maias-create, maias-edit, maias-review, maias-wireframe · installable anywhere as the maias plugin

Quick start

Requires Node.js 20.19.4+ / 22.13+ / 24.3+ (CI runs 22). No clone or install needed — the packages are on npm:

# validate a document — schema + semantic lint (dangling targets, orphans,
# path collisions), with line numbers; add --json for machine-readable output
npx -y @maias/cli validate my-app.maias.yaml

# canonical formatting (idempotent; agent edits diff cleanly)
npx -y @maias/cli fmt my-app.maias.yaml --write

# rename a screen — cascades to flows, navigation, every target
npx -y @maias/cli rename my-app.maias.yaml old_screen new_screen

Prefer a plain maias command? npm i -g @maias/cli.

In Claude Code, one install delivers the four skills plus the MCP server:

/plugin marketplace add MAIAS-project/maias-plugin
/plugin install maias@maias

In any MCP client, add the server with claude mcp add maias -- npx -y @maias/mcp (or the JSON equivalent — see packages/mcp); it is also listed in the official MCP registry as io.github.MAIAS-project/maias.

The MAIAS Browser (render any document as a working app, web/iOS/Android) runs from a clone:

git clone https://github.com/MAIAS-project/maias.git && cd maias
npm install && npm run build
npx maias validate examples/todo_list/maias.yaml
npm run web --workspace maias-browser

Working from a clone, npm run link-tools symlinks the workspace CLI (and the maias-mcp server) onto your PATH, tracking your local build; undo with npm rm -g @maias/cli @maias/mcp.

To author a document, start from docs/spec/llms.txt — it is sufficient on its own — or, in Claude Code, just ask: "create an IA for a recipe app" (the maias-create skill takes it from there).

Project documentation

Project architecture: docs/ARCHITECTURE.md · the browser as built: MAIAS_browser/ARCHITECTURE.md · local agent setup (MCP, offline validation): docs/ARCHITECTURE_LOCAL_SETUP.md · building an app from a document: docs/implementation-guide.md · design-system adapters: docs/adapters.md.

Status

Pre-release. MAIAS is pre-1.0: the format and tooling may change in breaking ways between 0.x versions. Spec v0.3 (0.2 + the capabilities/deep_links renames and the elements-first link rule); all six project deliverables implemented (spec + schema, validator/linter, browser, examples, skills, agent-interop toolkit). Tests: npx vitest run (core round-trip/lint/fmt, CLI, MCP). See version notes below for how the project got here.

Version notes

The packages version independently (pre-1.0: a minor bump signals a breaking change, a patch bump covers features and fixes), so the history below is organised by milestone, newest first. For the format itself, the authoritative record is the spec changelog.

• 2026-10-12 — Examples review pass, loader hardening, video tour. The four example documents gain fuller journeys, states, data wiring, and navigation labels from a review pass; @maias/core now fails loudly at load if its compiled-in schema is malformed, with regression tests; the release helper scripts are tracked in scripts/; and a short video tour lives at TechPdM/maias-showcase. (source only — no new package releases: core/mcp 0.5.1 · cli 0.4.0 · plugin 0.5.1)
• 2026-07-25 — Deterministic wireframe renderer. maias wireframe renders a document to standalone HTML wireframes, deterministically, from both the CLI and the MCP server; the maias-wireframe skill orchestrates the renderer rather than drawing by hand. (core/mcp 0.5.1 · cli 0.4.0 · plugin 0.5.1)
• 2026-07-24 — Spec v0.3. Screen actions: → capabilities:, app.links → app.deep_links, the elements-first link rule, version-gated lints for renamed keys, and a comment-preserving maias migrate command. (core 0.4.0 · cli 0.3.0 · mcp 0.4.0)
• 2026-07-23 — Pre-release renumbering. Spec versions renumbered 1.0 → 0.1 and 1.1 → 0.2 with no semantic change, so the numbering reflects the project's pre-1.0 status.
• 2026-07-19 — First release. @maias/core, @maias/cli, and @maias/mcp published to npm; the Claude Code plugin (skills + MCP server) and the official MCP registry listing (io.github.MAIAS-project/maias) go live.
• 2026-07-18 — Hardening. First full install/test pass from a fresh clone: build-order and workspace-linking fixes, formatter conformance with the spec's canonical form, version–feature gating in the linter, Node floor raised to 20.19.4+.
• 2026-07-07 — MAIAS goes public. Project renamed to MAIAS (see the spec changelog) across the document header key, schema, diagnostic codes, package names, and CLI binary; Apache-2.0 licence and CI added; repository published.
• 2026-07-05/06 — Initial spec and toolkit. Spec v0.1 (12 screen types, 29 element types, flows, two-level navigation, states, data dependencies, canonical form) and v0.2 (declared back navigation), generalised from a working prototype — alongside the core library, CLI, MCP server, MAIAS Browser, example documents, and Claude skills.