maias

MAIAS — モバイルアプリ情報アーキテクチャスキーマ

アプリの情報アーキテクチャ（画面、ナビゲーション、フロー、UI 要素、状態、データ依存関係）を、人間が読みやすく、エージェントが操作できる単一の YAML（または JSON）ドキュメントで記述するオープンスタンダードです。

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

目的： アプリ開発における人間とエージェントの協働のための共通言語です。エージェントはドキュメントから記述されたアプリを構築し（実装ガイド）、安全な機械操作（CLI、MCP）としてドキュメントを作成・編集できます。また、人間も同じファイルを読んでレビューできます。

初めてですか？ MAIAS とは何か、なぜ作られたのか、プラグインの実際の動作を紹介する短い動画をご覧ください：TechPdM/maias-showcase。

このリポジトリの内容

仕様	docs/spec/ — 11 章 · llms.txt（1 コンテキストウィンドウに収まるエージェント向けリファレンス） · schema/maias.schema.json
@maias/core	packages/core — 解析 → 型付きモデル → 往復時の忠実性を保ってシリアライズ（コメントは編集後も保持）、グラフユーティリティ、安全な編集（連鎖的な名前変更、要素の一括処理）、正規フォーマッター、Hermes 対応の検証
maias CLI	packages/cli — maias validate（スキーマと意味的なリント、--json）、maias fmt、maias rename
MCP サーバー	packages/mcp — MCP 対応エージェント向けの validate / query / edit / edit_elements ツール
MAIAS Browser	MAIAS_browser — 実行時に任意の MAIAS ドキュメントを開いて描画する Expo アプリ：動的なタブバー、プラグイン可能なデザインシステムアダプター（ワイヤーフレーム · shadcn スタイル · ブループリント）、アプリ内の検証エラー
サンプル	examples/ — calculator · todo_list · social_network · ecommerce — すべてを合わせると、コア要素と画面タイプをすべて網羅しています
Claude スキル	.claude/skills/ — maias-create、maias-edit、maias-review、maias-wireframe · maias plugin としてどこにでもインストールできます

クイックスタート

Node.js 20.19.4+ / 22.13+ / 24.3+ が必要です（CI は 22 で実行）。クローンもインストールも不要です。パッケージは 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

maias コマンドだけを使いたい場合は、npm i -g @maias/cli を実行してください。

Claude Code では、 1 回のインストールで 4 つのスキルと MCP サーバーを導入できます：

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

任意の MCP クライアントでは、 claude mcp add maias -- npx -y @maias/mcp でサーバーを追加してください（または JSON 形式で設定します。packages/mcp を参照）。公式 MCP レジストリにも io.github.MAIAS-project/maias として登録されています。

MAIAS Browser（任意のドキュメントを動作するアプリとして描画。Web/iOS/Android 対応）は、クローンから起動できます：

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

クローンから作業する場合、npm run link-tools を実行すると、ワークスペースの CLI（および maias-mcp サーバー）が PATH にシンボリックリンクされ、ローカルのビルドが反映されます。元に戻すには npm rm -g @maias/cli @maias/mcp を実行してください。

ドキュメントを作成するには、docs/spec/llms.txt から始めてください。これだけで十分です。または Claude Code で「レシピアプリの IA を作成して」と頼むだけで構いません（あとは maias-create スキルが進めます）。

プロジェクトのドキュメント

プロジェクトのアーキテクチャ：docs/ARCHITECTURE.md · ブラウザーの実装：MAIAS_browser/ARCHITECTURE.md · ローカルエージェントのセットアップ（MCP、オフライン検証）：docs/ARCHITECTURE_LOCAL_SETUP.md · ドキュメントからアプリを構築する方法：docs/implementation-guide.md · デザインシステムアダプター：docs/adapters.md。

ステータス

プレリリース。 MAIAS は 1.0 より前の段階にあり、フォーマットとツールは 0.x バージョン間で互換性を損なう形で変更される可能性があります。仕様 v0.3（0.2 に、capabilities/deep_links の名称変更と elements-first のリンクルールを追加）；6 つすべてのプロジェクト成果物を実装済み（仕様とスキーマ、バリデーター／リンター、ブラウザー、サンプル、スキル、エージェント相互運用ツールキット）。テスト：npx vitest run（コアのラウンドトリップ／lint／fmt、CLI、MCP）。プロジェクトのこれまでの経緯については、以下のバージョンに関する注記をご覧ください。

バージョンに関する注記

各パッケージは個別にバージョン管理されています（1.0 より前の段階では、マイナーバージョンの更新は破壊的変更を示し、パッチバージョンの更新は機能追加と修正に対応します）。そのため、以下の履歴はマイルストーンごとに新しい順で整理しています。フォーマット自体については、仕様の変更履歴が正式な記録です。

• 2026-10-12 — サンプルのレビュー、ローダーの堅牢化、ビデオツアー。 4 つのサンプルドキュメントに、レビューを経て、より詳しいユーザーの流れ、状態、データ連携、ナビゲーションラベルが追加されました。@maias/core は、コンパイル時に組み込まれたスキーマが不正な場合、読み込み時にエラーを明示するようになり、リグレッションテストも追加されました。リリース用ヘルパースクリプトは scripts/ で管理されるようになり、短いビデオツアーは TechPdM/maias-showcase で公開されています。(ソースのみ — 新しいパッケージリリースなし：core/mcp 0.5.1 · cli 0.4.0 · plugin 0.5.1)
• 2026-07-25 — 決定論的なワイヤーフレームレンダラー。 maias wireframe は CLI と MCP サーバーの両方から、ドキュメントを決定論的に単体で動作する HTML ワイヤーフレームへレンダリングします。maias-wireframe スキルは手作業で描画するのではなく、レンダラーを制御します。(core/mcp 0.5.1 · cli 0.4.0 · plugin 0.5.1)
• 2026-07-24 — 仕様 v0.3。 画面の actions: を capabilities: に、app.links を app.deep_links に変更し、elements-first のリンクルール、名称変更されたキーに対するバージョン別リンティング、コメントを保持する maias migrate コマンドを追加しました。(core 0.4.0 · cli 0.3.0 · mcp 0.4.0)
• 2026-07-23 — プレリリースに伴うバージョン番号の変更。 意味上の変更はなく、プロジェクトが 1.0 より前の段階であることを番号に反映するため、仕様バージョンを 1.0 → 0.1、1.1 → 0.2 に変更しました。
• 2026-07-19 — 初回リリース。 @maias/core、@maias/cli、@maias/mcp を npm に公開しました。Claude Code プラグイン（スキル + MCP サーバー）と、公式 MCP レジストリーへの登録（io.github.MAIAS-project/maias）も公開されました。
• 2026-07-18 — 堅牢化。 新規クローンからの初めての完全なインストール／テストを実施しました。ビルド順序とワークスペースのリンクを修正し、フォーマッターを仕様の正規形式に準拠させ、リンターでバージョンに応じた機能の有効化を実装し、Node の最低バージョンを 20.19.4+ に引き上げました。
• 2026-07-07 — MAIAS の一般公開。 ドキュメントのヘッダーキー、スキーマ、診断コード、パッケージ名、CLI バイナリを含め、プロジェクト名を MAIAS に変更しました（仕様の変更履歴を参照）。Apache-2.0 ライセンスと CI を追加し、リポジトリーを公開しました。
• 2026-07-05/06 — 初期仕様とツールキット。 動作するプロトタイプを基に一般化し、仕様 v0.1（12 種類の画面、29 種類の要素、フロー、2 階層のナビゲーション、状態、データ依存関係、正規形式）と v0.2（宣言型の戻るナビゲーション）を策定しました。コアライブラリー、CLI、MCP サーバー、MAIAS Browser、サンプルドキュメント、Claude スキルも同時に用意しました。