MAIAS — Mobile App Information Architecture Schema

Name: maias
Author: maias-project

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.

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 three 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).