Maias

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

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.