AIコーディングアシスタントはステートレスです。新しいセッションは毎回ゼロから始まります。モデルは昨日何を構築したか、何が壊れているか、どのような決定が下されたか、次に何に取り組むべきかを知りません。開発者はCLAUDE.mdファイルや散らばったメモで補おうとしますが、標準的な構造も、セッションの継続性も、ツールもありません。
本当のコストはセットアップに無駄にする時間ではありません。繰り返されるミス、蒸し返される設計判断、幻覚的なコンテキスト、そして複利的ではなく直線的な作業の積み重ねです。
Related MCP server: AI Conversation Logger
すべてのプロジェクトに、JSONとマークダウンファイルからなる.story/ディレクトリを置きます。チケット、イシュー、ロードマップのフェーズ、セッションハンドオーバー、学んだ教訓がすべてそこに置かれ、gitで追跡され、あらゆるAIが読めるようになります。
CLI: storybloq - ターミナルから.story/を参照・変更します。
MCPサーバー: Claude CodeとCodexが直接呼び出せる構造化ツール。ローカルBusを有効にするとさらに5つのツールが追加されます。サブプロセスの生成はありません。
スキル: Claude Codeの/storyまたはCodexの$storyで、各セッションの開始時にプロジェクトの状態を読み込みます。
Macアプリ: .story/を監視し、AIクライアントが作業している間ライブで更新されるネイティブサイドバー（別製品、App Storeで無料）。
npm install -g @storybloq/storybloq@latest
storybloq setup --client allNode.js 20以上と、少なくとも1つのAIクライアント（Claude CodeまたはCodex CLI 0.130.0以上）が必要です。パッケージはnpmの@storybloq/storybloqにあります。リリースはこのリポジトリのgithub.com/Storybloq/storybloq/releasesにタグ付けされています。
setup --client allは、ClaudeとCodex用のStorybloqスキルをインストールし、このパッケージをMCPサーバーとして登録し、利用可能なクライアントフックを設定します。再実行しても安全です。Codexはインストールされたフックを信頼度unknownとして報告します。Codexで/hooksを開いて確認し、信頼してください。setup-skillはClaudeのみのセットアップ用の互換エイリアスとして残っています。
npm install -g @storybloq/storybloq@latest
storybloq setup --client all新規インストールと同じ2つのコマンドです。@latestで最新バージョンを取得し、setupの再実行でStorybloqスキルファイルを更新し、MCPサーバーを再登録し、以前のインストールで残った古いフックエントリを掃除します。
npmに新しいバージョンがある場合、次回のstorybloq呼び出し時に1行のバナーが表示されるのが通常です。
storybloq v1.2.0 is available (you have v1.1.6).
Update: npm install -g @storybloq/storybloq@latestCLIはアップグレード後の初回実行時に、スキルディレクトリを静かに更新し、レガシーフックエントリ（たとえば、改名前の@anthropologies/claudestoryパッケージ由来のもの）を移行します。手動でのクリーンアップは不要です。
Claude Codeプラグインシステムによる代替インストール方法: Storybloq/plugin-archiveを参照してください（レガシーパス。storybloq setup --client allが推奨インストール方法です）。
cd your-project
storybloq init --name "your-project"マルチリポジトリプロジェクトについては、下記のフェデレーションを参照してください。
これにより以下がスキャフォールドされます:
.story/
├── config.json project config + recipe overrides
├── roadmap.json phase ordering + metadata
├── tickets/ T-001.json, T-002.json, ...
├── issues/ ISS-001.json, ISS-002.json, ...
├── notes/ N-001.json, N-002.json, ...
├── lessons/ L-001.json, ...
├── handovers/ YYYY-MM-DD-<slug>.md
└── snapshots/ state snapshots (gitignored).story/snapshots/以外はすべてコミットしてください。
Claude CodeまたはCodex内で:
Claude Codeの/storyまたはCodexの$story - プロジェクトのステータスを読み込み、最新のハンドオーバーを読み、オープン中のチケットとイシューを表示し、ブロック中の作業をリストアップし、最近の変更を要約します。クライアントがバックグラウンドエージェントを実行でき、実行可能なバックログが多い場合、オーケストレート作業スタイルもプロアクティブに提示します（推奨であり、明示的なオプトインによって制御されます）。
/story auto T-001 T-002 ISS-013 / $story auto T-001 T-002 ISS-013 - 指定された項目にスコープされた自律モード。チケットをプラン → プランレビュー → 実装 → テスト → コードレビュー → コミットへと進め、各チェックポイントでハンドオーバーを行います。
/story review T-001 / $story review T-001 - チケットのdiffに対してマルチレンズレビューを実行します（Storybloq/lensesを参照）。
/story orchestrate / $story orchestrate - クライアントが正確な呼び出し可能なワークフロー/サブエージェントツールを公開している場合、マルチリポジトリ（または大規模な単一リポジトリ）のバックログを駆動します。Codexはmulti_agent_v1.spawn_agent、その正規化された識別子multi_agent_v1__spawn_agent、または正確なspawn_agentツールを使用します。Claude Agent Viewベースのstorybloq dispatchコマンドは同梱されています。プロダクト管理されたCodexディスパッチバックエンドは含まれていません。
/story triage / $story triage - オープン中のイシューバックログの読み取り専用トリアージ: 各フィンディングを固定された現在のHEADに対して検証し、すでに修正済みのイシューと重複イシューにフラグを立て、1つの検証済み根本原因を共有するイシューをグループ化し、優先順位付けされたチケットプランを推奨します。イシューもチケットも変更しません。
/story bus / $story bus - タスクにバインドされたローカルBusエンドポイントをポーリングし、実装者と独立したレビュー担当者がコピー＆ペーストなしでアドバイザリーフィンディングを交換できるようにします。
/story handover / $story handover - 決定事項、ブロッカー、次のステップを記録したセッションハンドオーバーを書き込みます。
両クライアントとも、コンテキスト読み込み、自律モード、MCP、およびコンパクション/ステータスフックをサポートしています。Codex Desktopは自律セッションの所有タスクを開き、正確なオーナー応答をそこに中継できます。Codex CLIは手動のタスク切り替えに安全にフォールバックします。自律コードレビューはデフォルトで12ラウンドの着地上限（チケットのリスクに応じて上方にクランプ）があります。未解決のクリティカルフィンディングとリジェクトは引き続きブロックし、非ブロッキングフィンディングは上限到達時にフォローアップイシューになります。recipeOverrides.stages.CODE_REVIEW.maxReviewRoundsを0に設定すると、上限を明示的に無効化できます。
recipeOverrides.compactThresholdはmedium、high（デフォルト）、またはcriticalを受け入れます。この値は圧力制限とローテーションのトリガーの両方を選択します。mediumはより低い制限を使用し、中程度の圧力でローテーションします。criticalはより高い制限を使用し、クリティカルな圧力を待ちます。クリーンなCOMPLETE境界では、Storybloqはクライアントのコンパクションコマンドを呼び出せないため、しきい値圧力はHANDOVERを通じて境界付きセッションを終了します。クライアント自身がコンパクションを行う場合、PreCompactフックとSessionStartフックが同じセッションを維持します。圧力はSessionStartがsource: compactを確認した後にのみリセットされます。
AIクライアントの外でも、同じ状態はstorybloqの1回の呼び出しで確認できます。
Claude Codeセッションは使用制限（「使用制限に達しました」）で停止し、夜間の自律作業はそれとともに静かに終了します。StorybloqはClaude CodeのStopFailureフックを通じて停止を検出し、セッショントランスクリプトからリセット時刻を解析し、グローバル台帳（~/.claude/storybloq/limit-ledger.json）に停止を記録し、制限がリセットされたときにセッションを再開します。フックがインストールされるとデフォルトでオンになります。
自律セッションはコンパクションと同じリカバリーレーンに待機し、完全なステートマシンを通じてヘッドレスで起こされます。所有権の再バインド、git-HEAD検証、リカバリーマッピングがすべて適用されるため、ワークスペースが変更された後のウェイクは盲目的に再生されるのではなく検証されます。FINALIZE途中で停止したセッションは自動再開されません（コミットのリプレイは安全であると証明されていません）。代わりに手動リカバリー手順を含む通知が届きます。
通常のセッションはリセット時に、正確なclaude --resumeコマンドを含むデスクトップ通知を受け取ります。プロジェクトごとのオプトイン（limitResume.plainMode: "headless"）により、代わりにヘッドレスで起こされます。
権限の姿勢がエスカレートされることはありません。 --dangerously-skip-permissionsで実行されたセッションは、プロジェクトが明示的にオプトインした場合（limitResume.inheritBypass: true）にのみそのフラグ付きで起こされます。それ以外の場合は通知のみです。
ウェイクはデーモンではなく、一時的なデタッチドウェイカープロセスによって駆動されます。30秒ごとに台帳をポーリングし、期限が来たものを再開し（試行回数上限付き、間隔をずらし、同時実行数を制限）、保留がなくなると終了します。ラップトップのスリープは生き延びますが、再起動やログアウトは生き延びません。再起動後は、任意のプロジェクトでの次のstorybloq呼び出しまたはフック発火がそれを再生成するため、週単位の待機も次のアクティビティで回復します。これが「デーモンなし」の代償です。
storybloq limit-statusでキューを検査・管理します（--cancel <key>で保留中の自動再開を破棄、--requeue <key>で待機中のレコードを再試行）。~/.claude/storybloq/config.jsonの{"limitResume": {"enabled": false}}でグローバルに無効化するか、.story/config.jsonのlimitResumeでプロジェクトごとに無効化できます（maxAttempts、staggerMs、maxConcurrent、notifyなども設定可能）。
先行技術: 検出と再解析のアプローチはunsnooze（MIT）をモデルにしています。unsnoozeはtmuxホストセッション向けのトランスクリプトベースの制限検出とリセット時刻解析を先駆けて実装しました。Storybloq版はtmuxレイヤーを廃止し、文書化されたフックサーフェスを使用し、キーストロークではなく独自のステートマシンを通じて自律セッションを再開します。
Storybloq Busは、1つの実装者タスクと1つのレビュー担当タスクのためのオプションのローカル調整プロトコルです。ランタイム状態はgitignoreされた.story/bus/の下に置かれます。確認されたフィンディングは、イシュー通知として送信される前に、永続的なソースの来歴を持つ正規のStorybloqイシューになります。
storybloq bus init
storybloq bus join implementer --client codex
storybloq bus join reviewer --client claude
storybloq bus hooks enable --client codex
storybloq bus hooks enable --client claudeBusランタイムはローカルかつgitignoreされているため、参加する各チェックアウトでstorybloq bus initを一度実行してください。statusとdoctorは、新しいチェックアウトを「有効だが初期化されていない」と報告します。この健全な非アクティブ状態は、コミットや自律FINALIZEをブロックしません。他のBusコマンドやMCPツールはランタイムを暗黙的に初期化しません。初期化は、シンボリックリンクされたignoreファイルと否定パターンを拒否します。それ以外の場合、Gitが完全なランタイムを確実に除外することを安全に証明できないためです。
フォアグラウンドプロトコルには、送信、ポーリング、確認応答、スレッド状態、ステータス、ドクター、エクスポート、シップチェックが含まれます。メッセージはハッシュチェーン化され、冪等で、境界があり、タスクにバインドされ、シークレットスクリーニングされ、クラッシュリカバリ可能な受信者メールボックスを通じて配信されます。クリティカルメッセージは、デフォルトで一致する未解決のクリティカルイシューを必要とします。Busテキストは常にピアエージェントのアドバイスです。オーナーの承認を付与したり、マージ、プッシュ、署名、デプロイ、認証情報、支出、破壊的アクションを許可したりすることは決してありません。
V1には、Bus配信経路としてデーモン、プロセス生成、ヘッドレス再開、自動オフラインウェイクは含まれません。自然なSessionStart/Stopフックと明示的なポーリングが配信経路です。Codex Desktopはウェイク不可のままです。（上記の使用制限の自動再開は、Busの外の限定された例外です。その一時的なウェイカーは制限で停止したセッションを回復するものであり、メッセージ配信経路ではありません。）
フェデレーションは、複数のリポジトリにまたがるAIエージェントの作業を調整します。1つのプロジェクトがオーケストレーターになります。オーケストレーターは、システムの一部となるリポジトリ（ノード）、それらの依存関係、および実行時の通信方法を宣言します。各ノードは、独自のチケット、イシュー、ハンドオーバーを含む独自の .story/ を保持します。オーケストレーターはそれらすべてを横断して読み取ります。
# Create an orchestrator
storybloq init --type orchestrator --name "my-platform"
# Register nodes
storybloq node add api --path ../api --stack typescript --role "REST backend"
storybloq node add web --path ../web --stack nextjs --depends-on api
storybloq node add sdk --path ../sdk --stack typescriptノードを接続する3つの関係タイプ:
dependsOn ノード設定上: ビルド順のエッジ。WebアプリはAPIに依存します。
links ノード設定上: 実行時統合。WebアプリはHTTPでAPIを呼び出します。
crossNodeBlockedBy チケット上: あるリポジトリのチケットは、別のリポジトリのチケットが完了するまでブロックされます。例: "crossNodeBlockedBy": ["api:T-012"]。
オーケストレーターディレクトリから:
storybloq status # aggregated view across all nodes
storybloq recommend # federation-aware suggestions (bottlenecks, stale nodes, blockers)
storybloq ticket list --node api # list tickets in the api node without cd-ingレコメンデーションエンジンは、フェデレーション固有の提案を生成します: 下流の作業をブロックしているノード、他の多くのノードから依存されるボトルネックノード、2週間ハンドオーバーがないノードなどです。crossNodeBlockedBy 参照を持つチケットは、ブロック中のチケットが完了するまでレコメンデーションに表示されません。
すべてのコマンドは --format json|md（デフォルトは md）を受け付けます。スクリプト処理ではJSONを jq にパイプし、Markdown版を直接読むこともできます。
コマンド | 説明 |
|
|
| フェーズステータス、カウント、リスクを含むプロジェクト概要 |
| 参照、スキーマ、ソースの来歴、およびローダーに依存しないJSONチェック |
| Storybloqスキルをインストールし、MCPを登録し、クライアントフックを設定します |
|
|
| コンテキストを考慮した作業提案 |
コマンド | 説明 |
| 派生ステータスを持つすべてのフェーズ（ステータスはチケットから計算され、保存されることはありません） |
| 最初の未完了フェーズ |
| フェーズのリーフチケット |
| フェーズを作成 |
| フェーズメタデータを更新 |
| 並べ替え |
| 削除（含まれるチケットを再割り当て） |
コマンド | 説明 |
| リーフチケットを一覧表示（アンブレラは除外） |
| チケットの完全な詳細 |
| 最優先のブロック解除済みチケット |
| 現在ブロックされているすべてのチケット |
| 作成（オーケストレーターから |
| 更新 |
| カスタムパススルーメタデータを管理 |
| 削除 |
コマンド | 説明 |
| イシューを一覧表示 |
| イシューの詳細 |
| 作成（オプションで永続的なレビュー証跡と再試行IDを指定） |
| 更新 |
| カスタムパススルーメタデータを管理 |
| 削除 |
コマンド | 説明 |
| ブレインストーミングとアイデアの記録 |
| 再利用可能なパターンとアンチパターン |
| スキル注入用の全アクティブレッスンの簡潔なサマリー |
コマンド | 説明 |
| セッション継続ドキュメント |
| 新しいハンドオーバーを書く |
| 進行をブロックする外部依存関係 |
| 状態をキャプチャし、最後のスナップショットとの差分を表示 |
| 自己完結型のプロジェクトドキュメント |
| 保留中の使用制限の自動再開（プロジェクト横断でグローバル） |
コマンド | 説明 |
| ローカルBusを有効にし、gitignoreされたランタイム状態を作成 |
| 現在のクライアントタスクを1つの排他的ロールにバインド |
| スレッドを作成するか、必須の冪等性キーを使用して返信を送信 |
| タスクバインドされたエンドポイントの未承認メッセージを読み取る |
| 受理、拒否、または延期された配信状態を記録 |
| 参加者スレッドを検査または遷移 |
| このプロジェクトのガード付きライブ配信を制御 |
| 状態を検査し、整合性を検証 |
| 重要なBus作業がリリースをブロックしている場合に失敗 |
| 1つのランタイムトランスクリプトを明示的にエクスポート |
コマンド | 説明 |
| ノードマップを持つオーケストレーターの |
| ノードリポジトリを登録する |
| ノードの登録を解除する（依存関係を先にチェックする） |
| ノードのメタデータを更新する |
| 設定済みの全ノードのテーブル |
| オーケストレーターがノードリポジトリに書き込むことを許可する |
これらのコマンドが操作するマージモデルについては、チームモードを参照してください。
コマンド | 説明 |
| このプロジェクトでチームモードを有効にする |
| このクローンにgitマージドライバーをインストールする（各チームメイトがチェックアウトごとに1回） |
| チームのヘルスチェック。 |
| チーム設定を確認または変更する |
| リモート参照を介して表示IDを予約する（git-refsアロケーターのみ） |
| 重複した表示IDを検出して番号を付け直す |
| 未解決のマージ競合を確認する |
| 競合を解決する（ |
| 保持期間を過ぎた削除済みアイテムのトゥームストーンを削除する。 |
Claude CodeまたはCodexに登録する（セットアップで自動的に行われます）：
claude mcp add storybloq -s user -- storybloq --mcp
codex mcp add storybloq --env STORYBLOQ_CLIENT=codex -- storybloq --mcpサーバーはCLIと同じTypeScriptモジュールを直接インポートするため、サブプロセスのオーバーヘッドはありません。作業ディレクトリから最も近い .story/ 親ディレクトリまで上に移動して、プロジェクトルートを自動検出します。
基本ツールは責任ごとにグループ化されています。バス対応プロジェクトでは、MCPプロセス起動時に追加の5つのツールが登録されます。storybloq bus init の後に接続中のクライアントを再起動してください。
storybloq_status · storybloq_phase_list · storybloq_phase_current · storybloq_phase_tickets · storybloq_ticket_list · storybloq_ticket_get · storybloq_ticket_meta_get · storybloq_ticket_next · storybloq_ticket_blocked · storybloq_issue_list · storybloq_issue_get · storybloq_issue_meta_get · storybloq_note_list · storybloq_note_get · storybloq_lesson_list · storybloq_lesson_get · storybloq_lesson_digest · storybloq_handover_list · storybloq_handover_latest · storybloq_handover_get · storybloq_blocker_list · storybloq_validate · storybloq_recap · storybloq_recommend · storybloq_export · storybloq_selftest
.story/ を変更）storybloq_snapshot · storybloq_handover_create · storybloq_ticket_create · storybloq_ticket_update · storybloq_ticket_meta_set · storybloq_ticket_meta_unset · storybloq_issue_create · storybloq_issue_update · storybloq_issue_meta_set · storybloq_issue_meta_unset · storybloq_note_create · storybloq_note_update · storybloq_lesson_create · storybloq_lesson_update · storybloq_lesson_reinforce · storybloq_phase_create
storybloq_autonomous_guide は自律状態機械（PICK_TICKET -> PLAN -> PLAN_REVIEW -> WRITE_TESTS -> IMPLEMENT -> TEST -> CODE_REVIEW -> FINALIZE -> COMPLETE）を駆動します。
storybloq_review_lenses_prepare・storybloq_review_lenses_judge・storybloq_review_lenses_synthesize はマルチレンズレビューループを調整します（@storybloq/lenses が必要です）。
storybloq_session_report・storybloq_register_subprocess・storybloq_unregister_subprocess はセッションの健全性をMacアプリに表示します。
storybloq_bus_send · storybloq_bus_poll · storybloq_bus_ack · storybloq_bus_thread_get · storybloq_bus_thread_update
すべての呼び出しには、安定したエンドポイントIDと現在検証済みのクライアントタスクIDが必要です。ポーリングとスレッドの出力は、ピアコンテンツを助言権限としてマークします。storybloq_bus_poll と storybloq_bus_thread_get は、正規の追跡対象プロジェクト状態に関して読み取り専用です。ポーリングはgitignoreされた .story/bus/ ランタイムメタデータを調整する場合があります。残りの3つは通常のMCP書き込み承認を保持します。
storybloq_node_init は、オーケストレーターコンテキストからノードリポジトリ内の .story/ をブートストラップします。
storybloq_node_add・storybloq_node_list・storybloq_node_update はオーケストレーターのノードレジストリを管理します。
コンテキストのコンパクションの前に storybloq session compact-prepare を実行して、クライアントがPreCompactフックをサポートしている場合にスナップショットと再開ブレッドクラムが最新の状態を保つようにします。Codexセットアップは manual|auto マッチャー付きの storybloq session compact-prepare --client codex を使用するため、CodexフックがClaude所有のセッションをコンパクト化することはできません。Claude Codeセットアップはマッチャーを空のままにします。
{
"hooks": {
"PreCompact": [{
"matcher": "manual|auto",
"hooks": [{ "type": "command", "command": "storybloq session compact-prepare" }]
}]
}
}storybloq setup --client all --skip-hooks でスキップします。
コンパクト対応の再開プロンプトを注入します。Codexセットアップは --codex-hook-json とマッチャー startup|resume|clear|compact を指定して同じコマンドを使用します。そのフックJSONには現在のタスクIDも含まれるため、同じタスクのCOMPACTリカバリはコピー＆ペーストしたResumeトークンなしで続行できます。フックの信頼性はセットアップで検証できないため、インストール後にCodexの /hooks を確認してください。
{
"hooks": {
"SessionStart": [{
"matcher": "compact",
"hooks": [{ "type": "command", "command": "storybloq session resume-prompt" }]
}]
}
}storybloq bus hooks enable は別のプロジェクトのオプトインです。SessionStartにエンドポイントメタデータと保留中のカウントを追加し、同期Stopフックが新しいメールボックスカーソルごとに一度だけブロックすることを許可します。ピアペイロードのバイトがフック出力に表示されることはありません。Claudeの共有フック構造は一度アップグレードされ、プロジェクトローカルポリシーによって保護されたままになります。Codexは storybloq hook-status --client codex を使用します。
毎ターンの終わりに storybloq hook-status を実行し、MacアプリとiOSコンパニオンがライブセッション状態を読み取るgitignoreされた .story/status.json を更新します。
書き込みはコンテンツゲートされています。ペイロードがファイルの既存の内容と同一の場合（観測タイムスタンプと書き込み元を無視）、何も書き込まれず、ファイルのタイムスタンプとinodeは変更されません。したがって、アイドルターンは作業ツリーを完全に変更しません。実際の変更（ワークフロー遷移、新しいMCP呼び出し、ヘルスまたはリースの変更）は即座に書き込まれます。
実行中の書き込みを失敗と見なすテストハーネスを持つプロジェクトは、ターン終了時のライターを完全にオフにできます：
{ "statusWriter": { "stopHook": false } }.story/config.json 内で。フックはその後、ステータス作業を一切行いません：セッションスキャンなし、ペイロード構築なし、gitignore自己修復なし、書き込みなし。自律セッションは独自のMCP遷移でステータスを更新し続けるため、セッション実行中はMacアプリがライブ状態を表示し続けますが、通常の対話型作業のターン間では更新が停止するだけです。フラグはデフォルトでオンであり、読み取り不能または不正な設定でもオンのままになります。
Claude Codeセッションがレート制限で停止したときに storybloq session limit-stop を実行し、自動再開のために停止を記録します（上記の使用量制限の自動再開を参照）。セットアップはまた、同じ session resume-prompt コマンドを持つ2番目のSessionStartマッチャーグループ（"resume"）を追加するため、制限で停止したセッションを手動で再度開くと、制限を認識したガイダンスが得られます。両方のエントリはClaude専用で、アップグレードのたびに調整され、グローバルキルスイッチが設定されると自動的に削除されます。
{
"hooks": {
"StopFailure": [{
"matcher": "rate_limit",
"hooks": [{ "type": "command", "command": "storybloq session limit-stop" }]
}]
}
}import { loadProject } from "@storybloq/storybloq";
const { state, warnings } = await loadProject("/path/to/project");
console.log(state.tickets.length); // all tickets
console.log(state.phaseTickets("p1")); // leaf tickets in phase p1
console.log(state.umbrellaChildren("T-014")); // children of an umbrella完全な型定義はパッケージに同梱されています（exports.types）。
チケット（.story/tickets/T-001.json）：
{
"id": "T-001",
"title": "Add search to sidebar",
"type": "task",
"status": "inprogress",
"phase": "p2",
"order": 10,
"description": "Fuzzy match over ticket title + description.",
"createdDate": "2026-04-12",
"completedDate": null,
"blockedBy": [],
"parentTicket": null,
"crossNodeBlockedBy": []
}イシュー（.story/issues/ISS-001.json）：
{
"id": "ISS-001",
"title": "Drag handle hit target too small on trackpad",
"status": "open",
"severity": "medium",
"components": ["mac-app"],
"impact": "Dragging tickets on trackpad requires multiple tries.",
"location": ["macos/Views/KanbanCard.swift:42"],
"sourceRefs": [{
"path": "macos/Views/KanbanCard.swift",
"startLine": 42,
"revision": "5ac37f94f7023b18f72d8e3fcf43dd64f54c11d7",
"contentHash": "f5b1b1b65dca3d9d86adf7c5d49082aa4dc09e7903ab46ce50e8cc6b4812e4cf",
"reviewId": "review-2026-04-15"
}],
"dedupeKey": "review-2026-04-15:finding-3",
"createdBy": "external-reviewer",
"discoveredDate": "2026-04-15",
"resolvedDate": null,
"relatedTickets": []
}各レコードは独自のファイルです。IDはタイプ内で連番です（T-001、T-002、...）。関係は単一の正規オーナーです：チケットの blockedBy フィールドはブロッカーチケットを指し、逆（誰が自分をブロックしているか）はスキャンによって導出されます。
作成操作は並行して実行しても安全です。ID割り当てと作成書き込みはプロジェクトロックの下で一緒に行われるため、同時作成者は直列化され、それぞれが異なる連番IDを受け取ります。作成が既存のレコードを静かに上書きすることは決してありません。激しい同時競合の下では、作成者は衝突する代わりにエラーで明示的に失敗します。
イシューの sourceRefs は、変更可能な path:line 表示文字列とは独立してレビュー証拠を保持します。Storybloqは正規化された参照行範囲のみをハッシュし、ソースの抜粋を保存することはありません。指定されたリビジョンはGitコミットに解決されます。それ以外の場合、Storybloqは作業ツリーの範囲をキャプチャし、それらのバイトが一致する場合にのみHEADを記録します。storybloq validate は、元の証拠を解決できない場合はエラーを報告し、有効な履歴証拠がHEADで移動または変更された場合は警告を報告し、まだ一致する場合は何も報告しません。
破損した config.json または roadmap.json が通常の読み込みを妨げる場合は、storybloq validate --integrity-only を使用してください。この読み取り専用の事前チェックは、すべての .story/**/*.json ファイルを1回のパスでスキャンし、利用可能な場合はパーサーの位置を報告し、重大なシングルトン障害とスキップ可能なアイテムおよび補助ファイルの障害を分離します。破損したファイルを書き換えることはありません。
確認された手動または外部レビューの所見は、オープンイシューとして直接登録する必要があります。まず検索し、createdBy にレビュー担当者の属性を渡し、sourceRefs を介してレビューIDとリビジョンを添付し、<review-id>:<finding-id> のような安定した dedupeKey を使用して、再試行が冪等になるようにします。不確かな設計上の質問は、メモまたはオーナーの質問として保持します。実装エージェントがイシューのステータスと解決を所有します。
チケットとイシューのレコードは、未知のJSONフィールドを保持します。storybloq ticket meta と storybloq issue meta を使用して、Storybloqのコアフィールドに触れることなく、これらのカスタムパススルーフィールドを読み取りまたは変更します。値はJSONであり、ドットパスはネストされたオブジェクトを指定します。例：storybloq ticket meta set T-001 integration.linear '"ABC-123"'。
自動プランレビューの深さは、チケットごとにreviewRiskメタデータ（low、medium、high）をシードとして設定できます。たとえば、storybloq ticket meta set T-001 reviewRisk '"high"'を実行すると、少なくとも3回のプランレビューラウンドが必要になります。従来のriskメタデータも認識されますが、正規のキーはreviewRiskです。この設定はレビューの深さだけを変更するもので、レビューステージをスキップすることはありません。
# Initialize
storybloq init --name "my-app"
# Add the first phase
storybloq phase create --id bootstrap --name "Bootstrap" --label "PHASE 1" \
--description "Get the app running end-to-end"
# Add a ticket
storybloq ticket create --title "Scaffold Next.js" --type task --phase bootstrap
# Start Claude Code and type /story, or invoke $story in Codex, then work on it
# (or go autonomous: /story auto T-001 / $story auto T-001)
# At the end of a session, commit your changes including .story/
git add .
git commit -m "T-001: scaffold Next.js"
# Session ends. Next session starts with /story or $story and picks up with full context..story/はgitで追跡されるプレーンなJSONです。したがって、これを共有するチームは、共有状態が抱えるのと同じ2つの問題に直面します。同じレコードへの同時編集と、新しいレコードの同時作成です。チームモードはその両方に対応します。
storybloq team init # once per project; commit the result
storybloq team setup # once per clone, by every teammateteam initは、プロジェクトをチーム作業用に設定します（スキーマバージョン、クレームのスターレ感、IDアロケーター、必要なクライアント機能）。また、自分のクローン用のセットアップも実行します。team setupは、storybloq-jsonのGitマージドライバーをクローンのローカルGit設定にインストールし、.story/のJSONファイルがそのドライバーを通るように.story/に.story/.gitattributesを書き込みます。Git設定はクローンごとのため、各チームメイトはチェックアウトあたり1度だけsetupを実行します。storybloq team doctorは、設定のすべて（重複表示ID、未解決のコンフリクト、失効したクレーム、マージドライバーの導入）を確認し、--ciが指定されるとエラー時に非ゼロで終了します。マージゲートのワークフローについては、後述のTeam CIを参照してください。
Gitが、同じ.story/レコードの両方に触れた2つのブランチをマージするとき、マージドライバーは、行ベースのテキストマージではなく、レコードごとの構造化三位マージでマージを実行します。フィールドは独立してマージされます。チームのメンバーがチケットのstatusを変更し、別のメンバーはdescriptionを編集した場合、両方の編修が反映されます。同じフィールドが両側で分岐した場合、ドライバーはどちらも選択しません。その分岐をレコード内の構造的な_conflictsブロックとして記録するので、ファイルは競合マーカーのない有効なJSONのままです。それでもGitはそのパスを「conflicted」として報告しますので、ファイルをgit addしてコミットすればマージ完了です。あとは記録されたコンフリクトを自分のペースで解決できます（コンフリクトは解決されるまで後のマージに引き継がれます）。未解決の_conflictsがあるプロジェクトは、すべての競合が解決されるまで書き込みがブロックされます：
storybloq conflicts list # every item with unresolved conflicts
storybloq conflicts show T-042 # field-level detail: base, ours, theirs
storybloq resolve T-042 --field status --use theirs
storybloq resolve T-042 --field title --value '"Merged title"'
storybloq resolve config # config.json merges the same way
storybloq resolve roadmap # so does roadmap.json並列ブランチで2人のメンバーがアイテムを同時作成するのは、別の障害の出方です。新レコードはランダムな正のIDファイル名で保存されるため（例えばt-8f2kq0v3n1xw9d4e.json）、独立に作成されたアイテムがファイルレベルで出会うことはありません。パス衝突がまだ起こり得るのは、古い連番ファイル名だけです（正規IDより前のプロジェクトに由来するISS-041.json）。衝突しうるのは人間向けの表示IDのほうです。両方のブランチがローカルに「次の空き番号」を計算し、両方ともT-042を発行します。これはマージ競合ではなく「重複」です。専用のツールがあります：
storybloq reconcile # renumber duplicates; the copy already on the protected ref, else the earlier one, keeps the number
storybloq reconcile --ci # detect only: exit non-zero if duplicates exist, mutate nothing番号を振り直されたアイテムは、旧表示IDをpreviousDisplayIdsに保持するため、以前の番号への既存の参照は引き続き解決できます。
team init --id-allocator local|git-refsは、args allocatorが表示するIDの割り当て方法を選択します。トレードオフの関係は次の表のとおりです：
|
| |
割り当て | ローカルチェックアウトから計算した次の空き番号 | 使用前に共有Gitリモート上にrefsとして予約されたID |
衝突 | 分岐したブランチが重複した表示IDをペンアウトできる | 発生元で防止される |
復旧 | マージ後に | IDには不要 |
要件 | なし；オフラインでも動作する | 到達可能な共有Gitリモートとref-push権限 |
古いクライアント | どんなクライアントでもアイテムを作成ことができる | 割り当て族を宣言していないタイクライアントがコンタイプ（フェイルクローズ；後述を参照） |
git-refsでは、team initはteam.requiredFeaturesにremote-ref-reservationsも追加します。これにより、そのクライアントは、その機能を宣言しないクライアントがアイテムを作ることを拒否し、git-refsチームでローカルに割り当てをして衝突することを避けます。注意点が一つ：現在のMacアプリの設リースは「予約機能」を宣言しているものの、予約は後になってから表れます。Macサイドの更新が配布されるまで、git-refsチームではMacアプリからアイテムを作ることは避けてください。storybloq team reserve tickets --count 5とすると、IDのバッチを事前に一括予約します。
team initは.story/config.jsonにschema version: 3を刻印します。CLI1.5.0より前のリリースはもっと、schemaVersion-3 のプロジェクトの読み込み・書き込みの両方ときに、アップグレードを促すメッセージ付きできっぱり拒否します（Config schemaVersion 3 exceeds max supported 2. Run: npm update -g @storybloq/storybloq）。この喧によるエラーは意図的なものです。それらのクライアントはチームモードのデータを理解できないエラー、バージョン混在チームでの以前の彼らは、エラーではなく無音で一部を読み取っていました。
フェンスより前に作られたチームのリポジトリにはschemaVersion: 2刻まれています。既存のチームリライトリをアップグレードにするには：全員が1.5.0+CLIを実行するまで待ち、その後schemaVersionを手動で3に設定するか、storybloq team initを再実行して同じアップグレードを行ってください。古いMacアプリのツールは、スキーマバージョン3のプロジェクトを「読み取り専用」として表示し、更新があるまでそのままです。データは失われません。
.story/.gitignore以前のリポジトリをアップグレードするteam initとteam setupは、マシンローカらのファイル（config/.storygores、snapshots/、status.json、federation-cache.json、channel-inbox/）を対象にした.story/.gitignoreを書きます。.gitignoreは、既に追跡済みのファイルを追跡対象から外しません。そのため、gitignoreが存在するより前にstorybloqを採用したプロジェクトは、一時ファイルをGitの履歴内に残している可能性があります。一度確認して、それらの追跡を解除します：
git ls-files .story/ | grep -E 'sessions/|snapshots/|status\.json|federation-cache\.json|channel-inbox/'
git rm -r --cached --ignore-unmatch .story/sessions .story/snapshots .story/status.json .story/federation-cache.json .story/channel-inboxその“追跡（トラッキング）”をコミットして削除します。セッションの状態は、絶対パス（ユーザー名を含む）を記録するので、先ほどの初回の共有プシューの前にやっておくと良いでしょう。
チームモードでチケット、issue、ノート、レッスンを削除しても、共有リポジトリからは消されません。ファイルは残り、すべての元内容に加えて、ライフサイクルマーカー（ lifecycle: "deleted"的なマーカー、deletedAtタイムスタンプ、削除者のGit user.email が入る deletedBy）を含みます。削除と編集の競合を解決するときも、解決者のメールがdeletedByとして合成トゥームストーンに刻マークできます。トゥームストーンは、storybloq gc --applyが実行されるまでリポジトリ内に残ります（既定の保持は30日）。
つまり、削除したアイテムは通常のビューから隠されますが、コンテンツも自分の刻印も、迷惑者のクローンからは確実にexternal nothingしません。最初にstorybloq gcを実行して、パージ対象（適切なトゥーストーン）をプレビューし、それから保持期間が過ぎた分をstorybloq gc --applyでパージしてください。
リポジトリはチームモードで状態を共有しているため、.story/へコミットされたすべては、リポジトリにアクセスできる全員に見えます。
チケット、issue、ノート、レッスン、フリーテキストフィールドも含めて。
ハンドオーバー：事実をしかも理由まで含んだセッション文書。何が起こったかを最も詳しく書くことが多い。
進行中アイテムのクレームブロック：主張しているチームメイトのGit識別情報（user.email）、ブランチ名、クレームタイムスタンプ、および自律セッションがそのアイテムに取り組む間のclaimedBySessionId UUID。
未解決のマージ衝突：マージを発散した後、この影響を受けたレコードの、_conflictsブロック中で、両サイドの値（base、ours、彼の theirs）が解決までそのまま残る。後で仲裁によって失われたチームメートのテキストも、解決までファイル上に残って見えます。
gitignoreを置いてあれば、マシンローカルファイルのrepositories.goはリポジトリの外です：sessions/（自律セッションの状態、各セッションのevents.logも）、snapshots/、status.json、federation-cache.json、channel-inbox/。コミットした.story/の内容は、コミットメッセージやコードコメントと同じ注意深さで扱ってください。それらはリポジトリと一緒に伝わっていくのです。
チームモードのプロジェクトでは、マージの処理前に、重複displayIdと古い参照をキャッチするCIを追加してください。GitHub Actionsフローとしてすぐ使えるものは TEAM_CI.mdにあります。
@storybloq/lenses - マルチレンズのコードレビューMCPサーバー兼ライブラリ。9の特化レビュアーが並で動いて、構造的な判定を返します。storybloq の自律レンズバックエンドがそれを直接使います。
Storybloq for Mac - .story/を監視し、AIクライアントが動いている間、そのライブで更新されるmacOS（ネイティブ）アプリ。Mac App Store で無料です。
セットアップのトラブル、質問、フィーチャー要望、あるいは今を作っているものを教えるためなら、何でも shayegh@me.comへメールをください。バグ報告は、GitHub issues としても歓迎します。
Issue と PR を待っています。単純でない変更については、まず Issue を開いて方向性をすり合わせましょう。
開発環境のセットアップ：
git clone https://github.com/Storybloq/storybloq.git
cd storybloq
npm install
npm test
npm run buildPolyForm Shield 1.0.0 - ソースを基に利用可能で、非ライセンス（OSIオープンソースではない）ライセンス。
以下のような包括目的に、Storybloqを使用することができます：
個人または趣味のプロジェクト
オープンソースのプロジェクト
社内の利用
開発している商業ソフトウェア
ただし、無のライセンスのまま、storybloqを競合製品を作るために使用することはできません：再パッケージ、再販売、マネージドサービスとしての提供、あるいはホワイトラベルの形で。その場合は、shayegh@me.comにご連絡ください。
This server cannot be deployed
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Shared project memory that keeps teammates and AI agents aligned across sessions.
