プレイブックと Version

プレイブックは、暗黙の owner、visibility、明示的な editor、0または1個の公式 Alias、latest Version、archive 状態を持つ論理 container です。実際の内容は immutable な Version に置かれるため、title や Step の変更は、過去の仕事で使った定義を書き換えず、新しい履歴として公開されます。

Definition

Version は、schemaVersion、title、description、単一 category、input schema、順序付き Step を含みます。category は productivity、programming、design、sales、marketing、operations、learning です。

input schema は object root の JSON Schema Draft 2020-12です。案件 input を検証しますが、Epismo にプレイブックを実行させるものではありません。

各 Step は次の field を持ちます。

Step は status、assignee、transition、retry policy、dependency、完了日時を持ちません。エージェントは Step を省略、統合、並べ替え、追加できます。

publish と identity

プレイブックの作成では container と Version 1をひとつの transaction で作ります。次の Version の publish には baseVersionId が必要です。latest が変わっていれば、同時変更を上書きせず conflict になります。

server は Definition を正規化し、canonical JSON と sha256: digest を保存します。JSON や YAML の空白・key 順が違っても同じ内容なら同じ identity です。Version に固定された案件は Version ID と digest を保持し、開始時の指針を後から検証できます。

新しい Step は ID を省略し、server が割り当てます。同じ論理 Step を編集するときだけ既存 ID を維持してください。削除済み ID は再利用されません。

Version のアーカイブ

owner manager は、Version 詳細ページ、CLI、MCP、HTTP API から過去の Version をアーカイブできます。アーカイブ済み Version は通常の一覧、直接参照、新しい案件の開始では表示・利用できません。番号は再利用されません。Version 1〜3のうち Version 2をアーカイブすると、表示される履歴は Version 1と3になり、次に publish されるのは Version 4です。

latest Version はプレイブックの現在の定義であり、下書きと次回 publish の base でもあるため、アーカイブできません。既存案件は固定済み Version の参照を保持して動作を継続しますが、アーカイブ済み Version の内容は通常の read では公開されません。

下書き

プレイブックが持てる下書きは最大1件です。mutable で未公開の内容を、Version を作らずに何度でも保存できます。保存には最後に読んだ revision（初回は 0）を指定し、古い revision を指定すると拒否されます。base version の conflict と同じ扱いです。

下書きはプレイブックの edit access に従います。editor と owner manager は read と edit を行えますが、公開の reader と share link は下書きにアクセスできません。下書きを publish すると、その内容から新しい Version が作られ、同時に下書きは破棄されます。方向性が違えば直接破棄すれば、公開済みの Version には影響しません。

発見と参照

読めるプレイブックを text・category で検索するほか、Web のカタログで resource kind と正規化された resource reference から探すこともできます。カタログでは同じ GitHub または npm resource を指す URL 形式と provider 固有の形式をまとめ、resource kind は分けて表示します。よく使うプレイブックは star し、active namespace 内で Alias を付けられます。個人または管理可能な Workspace namespace ごとに、読めるプレイブックへ1個の Alias を設定できます。表示形式は、local 解決の pb:alias と namespace を含む pb:handle/alias です。プレイブック owner の Alias は公式として表示・検索されます。第三者 Alias は設定した namespace の owner 本人にだけ「あなたの Alias」として表示され、検索対象にはなりません。Alias はアクセス権を付与せず、Version ではなく論理プレイブックを指します。

share token は恒久 access を変えずに token-based な read access を提供します。公開プレイブックは instructions と resource hint も公開するため、visibility を public にする前に secret、signed URL、社内限定参照、個人情報を除いてください。