Core concepts

Epismo を使うときに最初に理解すべきことは、情報を 再利用するもの と 実行するもの に分けることです。再利用するものは pack、実行するものは track です。この分離があることで、AI agent は必要な context を探しやすくなり、人間は進行中の作業を task/goal として管理しやすくなります。

Pack と track の違い

「これは将来も参照される情報か？」と考えて yes なら pack です。「これは完了に向かって動く作業か？」と考えて yes なら track です。

Packs

Pack は再利用する artifact です。Epismo には 2 種類の pack があります。

Workflow pack は「どう進めるか」を表します。たとえば「release review をするときの確認手順」「bug triage の進め方」「新しい agent skill を作る流れ」などです。各 step には title, content, dueDate, dependsOn, parentId, assignee を持たせられます。Step assignee は human または agent ID です。Workspace user ID は workflow step の assignee には使いません。

Context pack は「何を知っておくべきか」を表します。たとえば「monorepo の構成」「API authentication の前提」「ユーザーインタビューの要約」などです。大きな context pack は、まず outline を取得し、必要な block だけを selective fetch すると agent context を節約できます。

Tracks

Track は現在進んでいる作業です。Track も 2 種類あります。

Task は具体的な作業単位です。担当者、期限、依存関係、親 task、紐づく goal を持てます。Goal は成果目標です。progress は 0 から 100 の整数です。

大量の task を一度に作る場合は bulk apply を使います。非 UUID の draft ID は新規作成として扱われ、同じ request 内で dependsOn, parentId, goalId から参照できます。Server が draft label を実際の UUID に解決します。

Alias

Alias は pack への読みやすい参照です。

Alias は pack だけを指します。Track は UUID または UUID を含む URL で参照します。Prompt、runbook、CI script では UUID より alias の方が読みやすく、長期的に扱いやすくなります。

Workspace, project, personal space

Epismo は workspace を組織境界として扱います。Workspace を使わない場合は personal space に保存されます。Workspace の中には project があり、project は private data の共有 container として使います。

CLI は次の順序で実行 context を決めます。

1. EPISMO_TOKEN に workspace が埋め込まれている場合はそれを使います。
2. それ以外では epismo workspace use <workspace-id> で保存した default workspace を使います。
3. Workspace が選ばれていなければ personal space を使います。

API では対応 endpoint に workspaceId query parameter を渡せます。MCP では bearer token から workspace context が決まります。

Scope and sharing

Private record は personal space または workspace project に属します。作成・更新では scope を使います。

{ "scope": { "type": "personal" } }

{ "scope": { "type": "projects", "ids": ["project-id"] } }

検索では複数の private location をまとめて探せるように scopes を使います。

{
	"scopes": [{ "type": "personal" }, { "type": "projects", "ids": ["project-id"] }]
}

sharedWith は、scope とは別に特定の user ID または email に見せたい場合に使います。Update で scope や sharedWith を省略すると、現在の access settings は維持されます。

Visibility and credits

Pack には visibility があります。private は scope と sharing settings に従って見える範囲を制御し、public は discovery の対象になります。category は空文字、または productivity, learning, programming, design, marketing, operations, life です。

Credits は、価値の高い agent context の取得や処理に使われる quota です。Agent usage、pack search、track search、pack read は credit を消費します。Detail が必要なときだけ full/selected pack content を取得し、まず search result や outline を確認すると後続の agent context を小さく保てます。Credit が不足すると、credit-gated operation は 402 Payment Required を返すことがあります。

よくある判断