プレイブックとバージョン

プレイブックは、手順や判断基準をまとめたものです。所有元のアカウント、共有設定（access）、共有に使う名前（エイリアス）、最新バージョン、アーカイブ状態を管理します。エイリアスは設定しないこともできます。

バージョンとして保存した内容は、後から変更されません。タイトルや手順を変えるときは新しいバージョンとして保存するため、過去の案件で使った内容も確認できます。

プレイブックと案件には所有元のユーザーまたはワークスペースのアカウント（ownerId）があり、請求先も兼ねます。個人所有者は全権限を持ち、ワークスペース所有の場合は現在のオーナー・管理者が所有権限を行使します。それ以外のメンバーには、ユーザー・チームへの明示的な共有、または公開コンテンツへの公開設定が必要です。所属だけでリソースへの権限は得られません。退会時には、そのワークスペースが所有するアイテムへの直接共有も、完了・アーカイブ済みを含めて解除されます。解除によって編集者がゼロになるアイテムがあれば、完了・アーカイブ済みも含め、先に別のユーザーまたはチームを編集者に追加してください。個人所有や別ワークスペースのアイテムへの共有は維持されます。チーム経由の権限と管理権限は現在の所属に従います。必須 SSO は所属メンバーに適用し、非メンバーへの直接共有は通常の Epismo 認証で利用できます。ワークスペース間のチーム共有では、参加元ワークスペースの SSO を確認します。一覧は明示的な共有と対応する公開設定で決まり、所有権限だけでは表示されません。

作成・コピー時の ownerId を省略すると、選択中のワークスペース、未選択なら個人アカウントを所有元にします。明示指定にも権限確認が適用されます。保存済みの接続先を含め、ワークスペースを選択している場合、作成時は private: true、空でない teamIds、access のいずれか1つを明示します。個人スペースでは共有指定を省略できます。選択したチームの編集権限で作成者も編集できるため、重複する直接共有は追加しません。明示した作成者への共有は保持します。管理者や担当者の指定は共有設定の代わりにはなりません。

プレイブックの内容

各バージョンには、形式のバージョン（schemaVersion）、タイトル、説明、カテゴリ、入力項目の定義、順番に並んだ手順が含まれます。カテゴリは一つ選びます。指定できる値は productivity、programming、design、sales、marketing、operations、learning です。

入力項目は、最上位がオブジェクトの JSON Schema Draft 2020-12 で定義します。案件の入力内容を検証するためのもので、プレイブックの手順を自動実行する仕組みではありません。

各手順には次の項目があります。

手順には、進捗状態、担当者、状態の遷移、再試行の設定、依存関係、完了日時はありません。エージェントは状況に合わせて手順を省略・統合・並べ替えたり、追加したりできます。

バージョンの保存と内容の識別

プレイブックを作成すると、最初のバージョンも同時に保存されます。次のバージョンを保存するときは、変更元の baseVersionId が必要です。先に別の人が新しいバージョンとして保存していた場合は、上書きを防ぐため競合エラーになります。

サーバーは内容を統一した形式の JSON に変換し、内容を識別する sha256: ハッシュ値とともに保存します。JSON や YAML の空白・キーの順序が違っても、内容が同じなら同じハッシュ値になります。プレイブックを使う案件には、参照するバージョンの ID とハッシュ値が保存され、開始時に使った手順を後から確認できます。

新しい手順の ID は省略すると、サーバーが割り当てます。同じ手順を編集するときは既存の ID を維持してください。削除済み ID は再利用されません。

バージョンのアーカイブ

所有権限を持つ人は、バージョンの詳細ページ、CLI、MCP、HTTP API から過去のバージョンをアーカイブできます。アーカイブしたバージョンは通常の一覧や直接参照で表示されず、新しい案件にも使えません。番号は再利用されません。たとえばバージョン1〜3のうち2をアーカイブすると、履歴には1と3が表示され、次に保存するバージョンは4になります。

最新バージョンは現在の手順を表し、下書きや次のバージョンの変更元にもなるため、アーカイブできません。既存の案件は参照するバージョンの ID を保持しますが、アーカイブしたバージョンの内容は通常の閲覧では表示されません。

下書き

プレイブックごとに下書きを1件保存できます。新しいバージョンを作らずに、何度でも編集・保存できます。保存時には最後に取得した更新番号（revision、初回は 0）を指定します。他の人による変更で番号が古くなっている場合は、バージョン保存時と同様に競合エラーになります。

下書きの閲覧・編集にはプレイブックの編集権限が必要です。編集者に指定されたユーザーやチームのメンバー、所有者、所有元ワークスペースのオーナー・管理者が利用できます。公開範囲だけで閲覧する人や共有リンクには、下書きへのアクセス権はありません。下書きをバージョンとして保存すると、その内容から新しいバージョンが作られ、下書きは同時に破棄されます。下書きだけを破棄しても、保存済みのバージョンには影響しません。

発見と参照

閲覧できるプレイブックをキーワードやカテゴリで検索できます。Web 版のカタログでは、使用するツールや資料の種類・参照先からも探せます。同じ GitHub リポジトリや npm パッケージを指す参照は、URL などの表記が異なっていてもまとめて扱い、種類ごとに表示します。プレイブックの所有者（ワークスペース所有なら管理者）は、公開ハンドルの設定後に現在のエイリアスを1つ設定できます。共有するときは pb:handle/alias を使います。エイリアスはアクセス権を付与せず、特定のバージョンではなくプレイブック自体を指します。既存の pb:alias は本人のローカル参照として引き続き使えますが、共有には適しません。従来の第三者エイリアスは引き続き解決できますが、新規作成はできません。

所有権を移しても、旧所有者のエイリアスは旧所有者の名前の範囲で同じ名前を別のプレイブックに再利用するか削除するまで引き続き解決されます。移転先に公開ハンドルがあり、同名のエイリアスが空いていれば、自動的に新所有者の現在のエイリアスになります。移転先の既存エイリアスは上書きしません。現在の参照として表示するのは新所有者のエイリアスだけです。公開ハンドルを変更・削除すると旧ハンドルを含む参照は元のプレイブックを指さなくなります。別の人が旧ハンドルを取得すると、その参照が別のプレイブックを指す可能性があります。エイリアス自体は残り、新しいハンドルの下で再び共有できます。

共有 URL はプレイブックのページへリダイレクトします。閲覧時には現在のアクセス権が適用され、URL を知っているだけでは閲覧権限は得られません。共有設定を一般公開（public）にすると手順や参照先を誰でも読めるため、visibility を public にする前に、秘密情報、署名付き URL、社内限定の参照先、個人情報を取り除いてください。

読める保存済みバージョンをコピーして、独立した内容として調整できます。コピーは独自の内容とバージョンを持ち、共有設定、下書き、案件、提案、エイリアス、スター、履歴を引き継ぎません。編集は同期されません。共有設定を明示してください。ownerId を省略すると選択中のワークスペース、未選択なら個人アカウントを所有元にします。copiedFrom は直近の元プレイブックと固定バージョンを保持し、sourceAccessible は元を現在も読めるかを示します。コピー一覧には読めるものだけを返します。料金は通常のプレイブック作成と同じです。

所有・責任・ライフサイクル

編集者と所有者はプレイブックをアーカイブ・復元できます。検索語を指定せず archived=true（playbook list --archived または epismo_playbook_search）で一覧を取得し、playbook restore または epismo_playbook_restore で復元します。バージョン・共有設定・管理者は維持します。所有者は playbook assign --assigned-to または epismo_playbook_assign で責任者を変更できますが、権限は付与しません。過去バージョンのアーカイブは所有権限が必要で、最新版はアーカイブできません。

Web の「アーカイブ済みプレイブック」では、所有者がアーカイブ済みプレイブックを完全削除できます。ただし、完了・アーカイブ済みを含む案件からの参照や、このプレイブックをコピー元とする別のプレイブックがない場合に限ります。元には戻せません。CLI・MCP のアーカイブ・復元操作では完全削除しません。

提案は現在の親プレイブックに紐づき、独立した所有者や共有範囲のスナップショットを持ちません。authorId は作成者、baseVersionId は改善を検討するための不変の内容参照です。閲覧には親への現在のアクセス権が必要で、親がアーカイブされると復元まで提案も読めません。作成者は親へのアクセス権を保持している間、未解決の自分の提案を編集でき、現在のプレイブック編集者が採用・却下を行えます。移管後も既存の提案は親の現在の共有設定に従います。採用済みにする前に結果のバージョンを保存してください。

プレイブックの担当変更も案件と同じ assignedTo を使い、応答でも assignedTo として返します。epismo_playbook_assign、playbook assign <playbook-id> --assigned-to <user-id>、または PATCH /v1/playbooks/{playbookId}/assignee を使います。変更には所有権限、選ぶ相手には既存の編集権限が必要です。