共有ファイル

Agent Boardが保存するすべてのファイルを、項目と例とともに示します。ファイルの使われ方はタスクと状態と保存と復旧にあります。

タスク

タスクはボード上の作業の単位です。タスクの状態はtask.jsonに、本文・受入条件・履歴はTASK.mdにあります。

項目	規則
`id`	正の整数。ボード内で一意で、フォルダ名と一致する。
`title`	前後の空白を除いて1〜100文字、1行。
`description`	frontmatterを含む`TASK.md`の全文。50,000文字の上限は本文だけを数える。CRLFはLFに正規化する。
`body`	`description`からfrontmatterを除いた本文。見出し構成は自由。GitHub Flavored Markdownに対応。
`acceptance`・`acceptanceError`	frontmatterの受入条件（不正なときは空）と、`acceptance`かYAML構文が不正かどうか。
`assignee`	`ai`か`human`。作成時に決め、以後は変えない。
`epicId`	同じプロジェクトのEPIC-ID、または`null`。
`taskStatus`	レーン。`todo`・`doing`・`done`。
`position`	正の整数。同じレーンの未アーカイブのタスク内で一意。
`agentStatus`	AIの稼働状態。`idle`・`running`・`pending`。
`isDraft`	既定は`false`。人が準備中のタスク（下書き）。
`pendingRequestId`・`pendingRequest`	Pendingの間の未回答の判断依頼。それ以外は`null`。
`requestAnswers`	再起動後も依頼IDで引けるよう保存する回答。
`archivedAt`	`null`、またはアーカイブ日時。
`attachments`	画像のID・名前・サイズ・MIME型・作成日時。
`simpleRequest`	過去の簡易依頼フォームが保存した任意のメタデータ`{requestId, payloadHash}`。新規タスクでは保存・利用しない。
`createdAt`・`updatedAt`	作成日時と、取得時に`task.json`と`TASK.md`の更新日時の新しい方。
`agentStatusChangedAt`・`taskStatusChangedAt`	稼働状態の最後の変更と、レーンの最後の実際の変更。本文の編集・進捗の記録・同じレーンへの操作では`taskStatusChangedAt`は変わらない。
`history`	`TASK.md`から読む。保存と応答は古い順。

文字数はUnicodeスカラー値で数えます。assignee（タスクの担当）はactor（操作した主体）とは別です。actorは権限を決め、履歴には保存しません。

ディスク上のファイル

データ領域は、どのOSでもホームディレクトリの.agent-board/、または空でないAGBOARD_HOMEです。ホームディレクトリを解決できなければ、作業フォルダで代用せずにコマンドが失敗します。

text

<data-root>/
  shared/
    workspace.json
    projects/
      <project-id>/
        project.json
        README.md
        docs/<任意のフォルダ>/<名前>.md
        epics/<EPIC-ID>/{epic.json, EPIC.md, assets/<attachment-id>.<ext>}
        tasks/<task-id>/{task.json, TASK.md, assets/<attachment-id>.<ext>}
        .internal/write.lock
        .internal/transactions/<transaction-id>.json
  bindings.json
  serve.json
  serve.log
  lifecycle.lock
  .internal/monitor-connection.json
  .internal/preferences.json

JSONはUTF-8・camelCase・2スペースのインデントで、末尾に改行を一つ付けます。未知の項目は拒否します。
workspace.jsonは{"format":"agboard-files","formatVersion":1}です。project.jsonとepic.jsonはformatVersion: 1、task.jsonもformatVersion: 1を持ちます。対応するバージョンは1だけです。それ以外はformat_unsupportedを報告し、変更せずに残します。移行もフォールバックもしません。
.で始まる名前は正本ではありません。README.mdはフォルダと編集の規則の案内で、製品が作成時に書きます。
画像は所有者のassets/に置きます。本文からはassets/<attachment-id>.<ext>（または旧形式のattachment:<id>）で画像を参照します。画像はPNG・JPEG・WebP・GIFで、1件10 MiBまで、所有者ごとに20件・合計50 MiBまでです。
bindings.jsonとserve.jsonはそのマシンだけで使うファイルです。serve.json（{"pid":41235,"port":7420,"started_at":"..."}）は、CLIに通知先を、waitに接続先を教えます。トークンは含みません。serve.logはserve -dで起動したサーバーの出力です（所有者のみ読み取り可、起動のたびに作り直し）。agboard stopはserve.jsonからサーバーを見つけます。

docs/には、プロジェクトのMarkdown文書を置きます。ドキュメントのダイアログが読み書きします（プロジェクトのドキュメントを参照）。

project.jsonはformatVersion・id・name・createdAt・nextTaskId・defaultEpicsSeededを持ちます。defaultEpicsSeededは、プロジェクトに既定のエピックBUGとENHANCEMENTを用意済みのときtrueになります。一度だけ書くので、削除された既定のエピックが作り直されることはありません。この項目がないファイルはfalseとして読みます。epic.jsonはformatVersion・id・name・color・isDraft・attachments・createdAt・updatedAtを持ちます。

EPIC.mdには、エピックの詳細をMarkdownで保存します。frontmatterを含み、frontmatterには作業順のpriority（タスクIDのリスト）を置けます。APIとepic show --jsonは、全文をdocument、frontmatterを除いた本文をbody、解析した作業順をpriorityとして返します。以前のバージョンでは、このファイルをPLAN.mdと呼んでいました。プロジェクトを初めて読み込むと、EPIC.mdへ名前が変わります（データとバックアップを参照）。

task.jsonは次のような形です。

json

{
  "formatVersion": 1,
  "id": 1,
  "title": "Implement the answer UI",
  "assignee": "ai",
  "epicId": null,
  "taskStatus": "todo",
  "agentStatus": "idle",
  "position": 1,
  "isDraft": false,
  "archivedAt": null,
  "pendingRequestId": null,
  "pendingRequest": null,
  "requestAnswers": [],
  "createdAt": "2026-10-10T00:00:00Z",
  "updatedAt": "2026-10-10T00:00:00Z",
  "agentStatusChangedAt": "2026-10-10T00:00:00Z",
  "taskStatusChangedAt": "2026-10-10T00:00:00Z",
  "attachments": []
}

pendingRequestは{question, choices}で、choicesは[{"id":"proceed","label":"Proceed"}]のような形です。
requestAnswersの各項目は{requestId, actor, choiceId, choiceLabel, text, at}です。choiceIdとchoiceLabelは両方nullか両方設定、textはnullか有効な回答で、選択と文の少なくとも一方があります。requestIdは一意で、現在のpendingRequestIdとは異なります。
過去の簡易依頼タスクにはsimpleRequestメタデータが残っている場合があります。互換性のため読み込みますが、新規タスクでは保存せず、再送の判定にも使いません。

TASK.mdではhistoryが必須です（history: []も有効）。新規タスクの入力では省略するか空のリストにでき、作成の入力に空でない履歴があれば拒否します。本文と受入条件の編集は最新の履歴を保ち、edit --desc-fileは履歴を追加しません。直接編集で履歴を追記する場合は、既存の内容を保ち、at/reasonの項目だけを追加します。ただし、日時の付与と原子的な追記を行うCLIの利用を推奨します。

yaml

---
acceptance: []
history:
  - at: "2026-10-15T01:30:00Z"
    reason: "Verified the setup guide links and recorded the result in the task body."
---

プロジェクトはshared/projects/<project-id>/を複製してバックアップし、serveを止めてフォルダを戻して復元します。エクスポートやインポートのコマンドはありません。データのガイドを参照してください。

モニター接続の設定

ngrokのモバイル接続は、秘密ではない設定を<データ領域>/.internal/monitor-connection.jsonに保存します。このファイルはアプリのもので、PCの設定画面とserveだけが書き、手で編集するものではありません。共有領域には含まれないため、プロジェクトのバックアップには入りません。所有者だけが読み書きできる権限（OSにある場合は0600）でatomicに置き換えます。

json

{
  "formatVersion": 1,
  "revision": 3,
  "enabled": true
}

フィールド	規則
`formatVersion`	常に`1`。ほかの値、未知のフィールド、壊れたファイルは、設定を読めない（`config_unreadable`）扱いになる。PCの入口は動き続け、新しい設定を保存するとファイルが置き換わる。
`revision`	保存のたびに増える。設定APIが、別の画面での変更を検出するために使う。
`enabled`	次の`serve`で接続を再び始めるか。停止すると`false`で保存する。

ファイルには、ngrokのトークン、スマホの合言葉、session、CSRFトークンを入れません。利用者が保存を選んだトークンは、代わりにこのPCの安全な保管場所（OSの資格情報ストア。service agent-board、account ngrok-authtoken）に置きます。monitor/config.jsonはありません。

表示設定

保存した言語とカラーテーマは、<データ領域>/.internal/preferences.jsonにあります。このファイルはアプリのもので、PCのPUT /api/preferencesとモニターの保存の経路だけが書き、手で書くことはありません。shared/にはないため、プロジェクトのバックアップには含まれません。所有者だけが読み書きできる権限（OSにある場合は0600）で、原子的に置き換えます。書き込みに失敗した場合は、以前のファイルをそのまま残します。

json

{
  "formatVersion": 1,
  "revision": 4,
  "locale": "ja",
  "theme": {
    "mode": "dark",
    "accent": "teal"
  }
}

項目	規則
`formatVersion`	常に`1`。ほかの値、未知の項目、壊れたファイルは既定値として読み、次の保存でファイルを置き換える。
`revision`	何も保存していなければ`0`。保存するたびに1増える。
`locale`	`en`か`ja`。既定は`en`。
`theme.mode`	`light`か`dark`。既定は`light`。
`theme.accent`	12色のいずれか: `blue`・`sky`・`cyan`・`teal`・`green`・`lime`・`yellow`・`orange`・`red`・`pink`・`purple`・`gray`。既定は`blue`。

保存では、送った項目だけを変えます。ほかの項目は保存済みの値を保ちます。後から保存した内容が優先され、競合の確認はありません。このファイルには秘密の値を含みません。トークン、合言葉、sessionは入りません。

タスクのJSONとスナップショット

CLI・Web API・Hookは、camelCaseの同じタスクの表現を使います。task.jsonのメタデータに、history・description・body・acceptance・acceptanceError、解決したpendingReasonとpendingChoices、表示用のupdatedAt、epic（{id, name, color}またはnull）を加えたものです。pendingRequestとrequestAnswersが履歴に現れることはありません。待機するstate ... --request-jsonは、解決した回答を別のanswerで返します。

スナップショットは、project・version・cursor・epics・tasks（それぞれ全履歴を持つ）・problemsを一度の読み込みから返します。CLIのスナップショットはnextTaskIdも含み、CLIのスナップショット・Hook・waitはfetchedAtを含みます。
プロジェクト一覧はprojects（id・name・createdAt）とcatalogVersionを返し、タスクは含みません。
ls --all-projects --jsonは、catalogVersionと、プロジェクトごとのスナップショットを名前順に返します。cursorはそれぞれのプロジェクトのものです。

problemsは形式の不備を報告します。[{ "file": "projects/<id>/tasks/12/TASK.md", "field": "acceptance[1].text", "reason": "The text must not be empty." }]の形で、fieldはfrontmatter・acceptance[<index>].<key>・history・history[<index>].<key>のいずれか、fileはshared/からの相対パス、reasonは英語です。不備が読み書きにどう影響するかは保存と復旧にあります。

初回の案内

shared/.internal/onboarding.json: 案内の状態、リースの持ち主、実行中の run、直近のコマンド ID。保存と回復を参照してください。
tasks/<id>/task.json の onboardingSample: { "runId": "<32 桁の小文字 hex>", "ordinal": 1 | 2 }。案内のサンプルカードにだけ付きます。

フォルダの紐付け

フォルダの紐付けは、実フォルダとProjectIdを対応づけ、Hookとagboard progressが作業フォルダが属するプロジェクトを識別できるようにします。端末ローカルのデータ領域にだけ保存し、共有領域や追跡ファイルには保存しません。ProjectIdを保存するので、名前変更に追従し、同じ名前で作り直したプロジェクトへは移りません。最も近い紐付け済みの祖先フォルダを使います。存在しないフォルダ・壊れた紐付け・削除済みのProjectIdは、説明つきのエラーにします。

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

shared/projects/<project-id>/docs/は、プロジェクトの文書のフォルダです。ボードではなく利用者のものです。ファイルには形式もformatVersionも項目もなく、Agent Boardは検証しません。

プロジェクトと一緒に作る。 project createと、プロジェクトを作るときのinitは、新しいプロジェクトの一時フォルダの中にdocs/とREADME.mdを作り、それからフォルダを正式な名前に変えます。READMEは英語か日本語で、.internal/preferences.jsonのアプリの言語に合わせます（jaなら日本語、それ以外は英語）。文面はsrc/docs/templates/にあります。
起動時に補う。 serveは、docs/がないプロジェクトにdocs/とREADMEを作ります。すでにあるフォルダには触れないので、利用者が消したREADMEは消えたままです。ここでの失敗は無視します。フォルダがなければ空のツリーとして読むためです。
プロジェクトと一緒に消える。 project rmはプロジェクトのフォルダを丸ごと削除し、docs/も消えます。退避はしません。既存のプロジェクトに対するinitはtasks/とepics/だけを初期化するので、docs/は残ります。
ボードのデータではない。 監視はdocs/の下をすべて無視し、ファイルはプロジェクトのversionに含まれません（変更の通知を参照）。編集してもchangedは送られません。
ドキュメントのルートからだけ読み書きする。 ツリーはフォルダとファイルを一覧にし、ファイルのルートは2 MiB以下のUTF-8の.mdと.mdxファイルを読み、保存します。画像のルートは10 MiB以下のPNG・JPEG・WebP・GIF・AVIF・SVGを返します。Web APIを参照してください。
送られたとおりに保存する。 保存は受け取ったバイト列をそのまま書きます。改行コード、BOM、末尾の改行、フロントマターは変えません。保存で指定するrevisionは、sha256:とそのバイト列のSHA-256（16進数）です。

共有ファイル ​

タスク ​

ディスク上のファイル ​

モニター接続の設定 ​

表示設定 ​

タスクのJSONとスナップショット ​

初回の案内 ​

フォルダの紐付け ​

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

共有ファイル

タスク

ディスク上のファイル

モニター接続の設定

表示設定

タスクのJSONとスナップショット

初回の案内

フォルダの紐付け

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