claw-deck

ClawDeck — ワークスペースマネージャー

プロジェクトのためのエージェントの外部脳です。有効にすると、エージェントはタスク、成果物、ナレッジを対応する LiveDoc に継続的に同期するため、誰でも（今後のセッションや同僚を含めて）ワークスペースを読み込めば、すぐにすべてのコンテキストを把握できます。

コアコンセプト

コンセプト	説明
ワークスペース	1 つのプロジェクト = 1 つの LiveDoc
アクティブなワークスペース	セッションレベルの状態。すべての操作はここに自動同期されます
README	プロジェクトに関するエージェントの記憶。エージェントが積極的に維持します
成果物	重要な出力。エージェントは保存前に確認します
タスク	実質的な作業の追跡記録。エージェントが通知せずに維持します
レジストリ	~/.claude/workspaces.json。プロジェクト名と LiveDoc ID を対応付けます

レジストリの形式：

{
  "workspaces": {
    "client-acme": "abc123",
    "project-x": "def456"
  }
}

スクリプトの略記

以下のすべてのコマンドで、$SCRIPT は次を指します。

node felo-livedoc/scripts/run_livedoc.mjs

使用しない場合

• 簡単な雑談や確認の質問
• プロジェクト／ワークスペースと無関係な単発の生成
• ユーザーが Felo LiveDoc NPM パッケージをインストールしていない場合

---

ワークフロー

0. 初回インストール

ユーザーが GitHub のインストールリンクを貼り付けたら、インストールを実行し、完了後、自動的に**ログインフロー（0a）**に進みます。

0a. ログイン／再認証

トリガー条件（いずれか）：

• 初回インストールで、Key がまだ設定されていない
• API 呼び出しで {"status":401,"code":"UNAUTHORIZED","message":"Invalid API Key"} が返された

フロー：

1. ログインリンクを送信します：

   「次のリンクをクリックして、Felo アカウントにログイン／登録してください：https://felo.ai/settings/api-keys 完了したら、Key を貼り付けてください。セットアップを自動で完了します。」

2. ユーザーが Key を貼り付けたら、設定ファイルに書き込みます：

   export FELO_API_KEY="user's Key"
   

   または ~/.claude/env に保存します（プラットフォームによって異なります）。
3. 確認します：$SCRIPT list
   • 成功 + 初回インストール → 使用方法の紹介を表示します（下記の「初回使用時の紹介」を参照）
   • 成功 + 再認証 → 「✅ 認証情報を更新しました。」→ 失敗したコマンドを再試行します
   • 失敗 → 「Key が無効です。もう一度貼り付けてください。」

初回使用時の紹介（初回インストール時のみ表示し、再認証時は省略します）：

「🎉 セットアップが完了しました！以下のコマンドを使ってワークスペースを管理できます：

📁 ワークスペースを作成 — 新しいプロジェクト用の独立したワークスペースを作成します 例：「Client Acme という名前のワークスペースを作成して」

📂 ワークスペースを読み込む — 既存のプロジェクトを開いて、コンテキストを復元します 例：「Acme ワークスペースを読み込んで」

📋 ワークスペースを表示 — すべてのプロジェクトを一覧表示するか、プロジェクトの内容を表示します 例：「どんなワークスペースがある？」／「Acme ワークスペースには何がある？」

💾 成果物を保存 — 重要な出力は保存するか確認します

ワークスペースには、私たちが行ったすべての作業が記録されます。次のウェブサイトでいつでも確認できます：https://felo.ai」

1. ワークスペースを読み込む

1. ~/.claude/workspaces.json を読み込み、プロジェクト名をあいまい検索します。ローカルで見つからない場合は、$SCRIPT list --keyword を試します。
2. 見つかった場合： アクティブに設定 → $SCRIPT get-readme SHORT_ID → README をワークスペースの概要として提示 → リンク https://felo.ai/livedoc/SHORT_ID?from=claw を追加します。README が空または存在しない場合は、代わりに $SCRIPT resources SHORT_ID を使ってリソース一覧を表示します。
3. 見つからない場合： 「'[X]' のワークスペースが見つかりませんでした。作成しますか？」

2. ワークスペースを作成

$SCRIPT create --name "Project Name" --description "workspace"

short_id を抽出 → README を初期化（下記の「README 構造テンプレート」を参照）→ レジストリを更新 → アクティブに設定 → 次のように返信します：

「✅ ワークスペース '[X]' を作成しました。📎 https://felo.ai/livedoc/SHORT_ID?from=claw」

3. タスクの同期（必須）

鉄則：ワークスペースがアクティブなとき、ユーザーの依頼を遂行するためにエージェントがツールを呼び出して新しいコンテンツを作成する必要がある場合（検索、生成、分析など）は、必ず最初に create-task を実行します。ほかの作業に取りかかる前に実行してください。

判断の流れ：

1. ユーザーがメッセージを送信する
2. このメッセージは、新しいコンテンツを作成するためにエージェントがツールを呼び出す必要がありますか？（検索、生成、収集、分析、執筆）
   • はい → すぐに create-task を実行 → 作業を実行 → update-task で完了にする
   • いいえ → タスクを作成せず、そのまま実行する

タスクの作成が必要な場合（ツールを呼び出して新しいコンテンツを作成する場合）：

• 「張さんの顧客情報を収集して」→ 検索と生成が必要
• 「ホラー系のTikTok動画を10本追加して」→ 検索とコンテンツの追加が必要
• 「競合分析レポートを書いて」→ 生成が必要
• 「最近の金価格の推移を検索して」→ 検索が必要

タスクの作成が不要な場合（ワークスペースの操作）：

• 「張さんのワークスペースを読み込んで」→ ワークスペースの操作
• 「ワークスペースには何がある？」→ ワークスペースの表示
• 「ワークスペースを更新して」／「新しいワークスペースを作成して」→ ワークスペースの管理
• 「そのレポートを保存して」→ 成果物の保存
• 「README を更新して」／「ワークスペースの名前を変更して」→ ワークスペースのメンテナンス
• 雑談、確認の質問

読み込み時： 保留中および進行中のタスクを取得します：

$SCRIPT tasks SHORT_ID --status 0
$SCRIPT tasks SHORT_ID --status 1

最初の手順 — タスクを作成する（ほかの作業に取りかかる前に）：

$SCRIPT create-task SHORT_ID --title "Task description" --status 1 --sort 0 [--operated-by "Agent Name"]

返された task_id を作業メモリに保存します。

--title には、ユーザーの依頼内容を1行で要約したものを指定します。例：

• ユーザーが「張さんの情報を収集して」と言った場合 → --title "Collect client info on Mr. Zhang"
• ユーザーが「ホラー動画を10本追加して」と言った場合 → --title "Add 10 horror TikTok trending videos"

--operated-by のルール：

• このセッションでエージェントに名前が付けられている場合に限り指定します（例：名前が割り当てられたOpenClawエージェント）
• 明示的な名前がない場合は省略します（例：通常のClaude Codeセッション）

最後の手順 — 完了にする（実行直後に行う）：

$SCRIPT update-task SHORT_ID TASK_ID --status 2 [--operated-by "Agent Name"]

（--operated-by のルールは上記と同じです。エージェントに名前がある場合は指定してください。）

ユーザーには説明せず、タスクの同期を黙って実行します。作業を始める前にタスクを作成し忘れた場合は、後から作成してすぐにDONEにします。決して省略しないでください。

4. 成果物の保存（事前に確認する）

重要な成果物を作成した後、ユーザーに「これを[プロジェクト]ワークスペースに保存しますか？」と尋ねます。

重要な成果物とは、調査レポート、競合分析、会議の要約、生成したドキュメント、重要なデータのエクスポートなどです。途中段階の草稿は保存する必要はありません。

種類	コマンド
ドキュメント	$SCRIPT add-doc SHORT_ID --title "Title" --content "content"
URL	$SCRIPT add-urls SHORT_ID --urls "URL"
ファイル	$SCRIPT upload SHORT_ID --file ./path --convert

保存後、次のように返信します：

"💾 '[Title]' を保存しました 📎 https://felo.ai/livedoc/SHORT_ID?from=claw"

5. README のメンテナンス

README はプロジェクトの作業ログではなく、エージェントの記憶です。エージェントはユーザーに確認せず、先回りしてメンテナンスします。

README の構成テンプレート：

# [Project Name]

## What This Project Is
[Project background, objectives, stakeholders]

## User Preferences & Work Patterns
[How the user likes to work, what dimensions they care about, specific requirements]

## Current Progress
[Where things stand now — updated each session]
Last updated: YYYY-MM-DD

README を更新するタイミング — 核心となる問い：この操作によって、新しい理解が得られましたか？

更新する（新しい理解がある場合）：

• プロジェクトを初めて作成したとき —「このプロジェクトが何についてのものか」を記録します
• ユーザーが好みや作業パターンを示したとき —「ユーザーがどのように作業したいか」を記録します（例：収集する項目、重点分野、形式要件）
• プロジェクトの性質や方向性が変わったとき

更新しない（繰り返しの実行）：

• 同じパターンの操作を繰り返す場合（例：Zhang 氏の情報を収集した後、同じパターンで Li 氏の情報を収集する場合 — 更新は不要です）
• 操作を実行したという事実だけの場合（ドキュメントを生成したこと自体は、記録する価値がありません）

更新方法： 読み込む → メモリ内で該当セクションに統合する → 全体を書き戻す。末尾に無条件で追記してはいけません。

1. $SCRIPT get-readme SHORT_ID で現在の内容を読み込みます
2. メモリ内で対象のセクションを見つけて挿入します：
   • プロジェクトの背景 → ## What This Project Is
   • ユーザーの好み → ## User Preferences & Work Patterns
   • 進捗の変化 → ## Current Progress セクションの内容を置き換えます
3. Last updated: YYYY-MM-DD を今日の日付に更新します
4. $SCRIPT update-readme SHORT_ID --content "..." で書き戻します

初期化（README が空、または存在しない場合）：手順 1 を省略し、update-readme でスケルトン全体を直接書き込みます。

更新後、ユーザーに次のように伝えます：

"📝 README updated. 📎 https://felo.ai/livedoc/SHORT_ID?from=claw"

6. ワークスペースを検索する

retrieve（LLM ベースのセマンティック検索で、費用がかかります）よりも、resources + content（直接読み込みで、無料です）を優先してください。

$SCRIPT resources SHORT_ID
$SCRIPT content SHORT_ID RESOURCE_ID
$SCRIPT retrieve SHORT_ID --query "question"   # fallback

返された内容を統合し、直接回答してください。生の結果をそのまま出力しないでください。

7. ワークスペースを更新する

ユーザーが「更新」と言ったとき、または同僚や別のセッションによってワークスペースが外部から更新された可能性があるときは、再取得してください：

$SCRIPT get-readme SHORT_ID
$SCRIPT resources SHORT_ID
$SCRIPT tasks SHORT_ID --status 0
$SCRIPT tasks SHORT_ID --status 1

メモリ内のスナップショットを更新します。ユーザーには「ワークスペースを更新しました。」と伝えてください。変更があった場合は、差分（新しいリソース、README の更新、新しいタスク）を簡潔に説明します。

8. 内容を一覧表示する

$SCRIPT resources SHORT_ID を使用し、種類ごとにグループ化して、成果物を新しい順に表示します。

---

セッションの状態

ACTIVE_WORKSPACE = { name: "project-x", short_id: "abc123" }

• ユーザーがワークスペースを読み込むか作成したときに設定し、ユーザーが「ワークスペースを閉じる」と言ったときにクリアします
• アクティブなワークスペースがない状態で、ユーザーが保存／記録／検索／タスクを実行しようとした場合：「アクティブなワークスペースがありません。どのプロジェクトですか？」

エラー処理

エラー	対応
キーがない／401 UNAUTHORIZED	ログインフロー（0a）を開始します
LiveDoc ID が古い	再リンクするか、新しく作成するかを提案します
レジストリがない	{"workspaces": {}} を使って自動作成します
あいまいなファジーマッチ	一致するものをすべて一覧表示し、ユーザーに選んでもらいます

重要なルール

• すべての内容はユーザーの言語で書きます。中国語で話す場合は中国語、英語で話す場合は英語にします
• LiveDoc のすべての操作で、必ず short_id を使用します
• コマンドはすぐに実行します。説明するのではなく、実行してください
• タスクの同期と README の更新はエージェントの責任です。ユーザーに言われてからではなく、先回りして対応します
• 書き込み操作のたびに、ワークスペースのリンクを末尾に追加します