Vibeflow

Vibeflow

AI コーディングエージェントのためのタスク管理 — 注釈と検証機能を内蔵しています。

Vibeflow は、順序付けられた、確保可能な作業をコーディングエージェントに提供します。階層構造のタスク、アトミックな --next による確保、検証結果を伴うレビューゲートを備え、リポジトリ内にとどまるローカルファーストのカンバンボードで管理できます。UI 要素をクリックして、正確なセレクター、URL、ソース内の位置を添えたチケットを作成する機能も組み込まれているため、視覚的なフィードバックが文章ではなく構造化されたタスクとして届きます。

🌐 ウェブサイト · 📖 チュートリアル

▶ 全編モーションデモを見る（MP4）

---

重要な理由

AI エージェントはコードをすばやく書きますが、何を変更すべきか理解するのには時間がかかります。UI の問題を文章で説明するとトークンを浪費し、誤った修正につながります。

Vibeflow は視覚的なフィードバックを構造化されたタスクに変換します。

• 任意の要素をクリック → CSS セレクター、URL、ソースファイル内の位置を含むタスクを即座に作成
• カンバンボードで管理 → すべてをひと目で把握し、列間でドラッグ
• エージェントがコンテキストを踏まえて実装 → 推測不要、要素の取り違えなし、無駄な反復なし

小規模な UI 修正、レイアウトの崩れ、間隔の問題など、説明するより指し示すほうが速い作業に最適です。

---

インストール

npx で一度実行するだけです。インストールは不要です。

npx @vibeflow-tools/cli kanban

または、2 日目以降も使えるようにグローバルにインストールできます。短縮エイリアス vf が追加されます。

npm install -g @vibeflow-tools/cli
vibeflow kanban                  # or: vf kanban

要件： Node.js >= 22。Apache-2.0 ライセンスです。アカウントもクラウドも不要です。すべてのタスクはリポジトリ内の JSON ファイルです。

---

クイックスタート

# 1. Start the local server and open the Kanban board
npx @vibeflow-tools/cli kanban

# 2. Annotate a running app: open http://localhost:3700/inject and drag the
#    bookmarklet onto your bookmarks bar (or use the script tag / console snippet)

# 3. Click elements in your app to create tasks — the CSS selector, URL and
#    source location are captured for you. You can also create tasks on the board.

# 4. Let your agent pick up the next task with full context
npx @vibeflow-tools/cli tasks --next

---

動作を見る

ボード上でタスクをドラッグ — Backlog → Todo → In Progress → Review → Done。カードをドラッグしてステータスを変更すると、ボードは新しい列と順序を保存するため、再読み込み後も維持されます。タグ、ユーザー、種類のフィルターは作業中も状態を維持し、変更はすべてタスクストアに直接書き込まれるため、CLI とエージェントからすぐに確認できます。

親子ツリーに分けて作業 — エピックを、それぞれ独自のステータス、優先度、履歴を持つ子タスクに分割できます。カード上でツリーをインライン展開するか、ターミナルから vibeflow tasks --add --title "..." --parent <id> を実行して子タスクを作成できます。同じ階層構造は vibeflow tasks --get <id> でも取得できるため、エージェントは親を見失わずに末端のタスクに取り組めます。

1 つのパネルでチケット全体を確認 — 任意のカードを開くと、ステータス、説明、タグ、優先度、作成者、関連情報（子タスクと関連タスク）、アクティビティフィード、添付ファイルを含むチケット全体を確認できます。変更は自動保存され、パネル内のどこかにスクリーンショットやファイルを貼り付けると、ダウンロードフォルダーではなくタスクに添付されます。

---

MCP サーバー

Vibeflow は MCP 経由でタスクツールを公開するため、エージェントはチケットを直接読み取り、更新できます。プロジェクトごとにサーバーを 1 つ設定してください。サーバーは起動時にプロジェクトのルートを一度解決し、すべてのツール呼び出しでそのルートを使用するため、誤ったプロジェクトに書き込むことはありません。

stdio（推奨 — ポート不要、起動したままにするものもありません）：

{
  "mcpServers": {
    "vibeflow": {
      "command": "npx",
      "args": ["-y", "@vibeflow-tools/cli", "mcp", "--project", "/path/to/project"]
    }
  }
}

--project は必須です。起動されたクライアントの作業ディレクトリ（多くの場合、ホームディレクトリ）は決して信頼されず、何かを作成する前にルートが検証されます。この設定はプロジェクトと一緒に置いてください。リポジトリのルートにある .mcp.json、または ${workspaceFolder} を使ったエディターのワークスペース設定に記述します。

HTTP（起動したままにするサーバー）：

vibeflow serve --project ./my-project    # MCP endpoint at /api/mcp

トークンを設定するまでは、ループバック経由のみでアクセスできます。どちらのトランスポートも同一のツールセットをマウントし、異なるのはトランスポートだけです。

呼び出しごとにプロジェクト引数を指定するグローバルサーバーを 1 つだけ実行することはしないでください。これは意図的にサポートされていません。1 つのプロセスが提供するルートは 1 つで、起動時に解決されます。

type:"Research" のタスクは、.md レポートが添付されるまで RESEARCH_REPORT_REQUIRED によってレビューを拒否されます。MCP 経由でレポートを添付するには、.md ファイル名を指定して attach_file を使います。ゲートはタスクのファイルの中に .md があるかを確認するため、重要なのはファイル名です。このインターフェースには --report-file に相当するものはありません。CLI 呼び出し元向けに、拒否時の suggestion に CLI フラグ名が記載されています。Research タスクには検証結果を設定できません（RESEARCH_VERIFY_NOT_ALLOWED）。検証対象となる注釈付き UI がないためです。

MCP の結果

ツールの結果は、ペイロードを content[0].text 内の 1 つの JSON ドキュメントとして返します。これは、ツールレベルでの成功と拒否のすべてに当てはまります。JSON ではない形式は、プロトコルレベルの失敗が 2 つの場合だけです。ツール自体のスキーマで拒否された引数、または存在しないツール名の場合、result.isError === true と content[0].text = MCP error -32602: … が返され、解析するためのエンベロープはありません。そのため、まず isError を確認し、それがない場合に限りテキストを JSON として解析してください。

この 2 つのプロトコルレベルの失敗は、コードではなく、メッセージに何が記されているかで区別します。SDK は不明なツールを同じ入力検証経路で報告するため、JSON-RPC では「method not found」に -32601 が予約されているにもかかわらず、どちらも -32602 になります。

送信したもの	メッセージに記される内容	対処方法
ツールのスキーマで拒否された引数	問題のあるフィールド（… at title）	そのフィールドを、スキーマが求める型で送信します
存在しないツール名	ツール	tools/list を確認してください。送信した名前は、このサーバーが公開しているツールのものではありません

スキーマエラーのクラス（-32602）— 設計上、vibeflow のコードはありません

title のない create_task、contentB64 のない attach_file、limit:-1 を指定した list_tasks のように、ツール自体のスキーマで拒否される入力は、vibeflow のハンドラーが実行される前に、MCP SDK の入力検証によって拒否されます。そのため、vibeflow がこの呼び出しを受け取ることはなく、code や suggestion を付与できません。返される内容は次のとおりです。

result.isError === true
content[0].text = "MCP error -32602: Input validation error: Invalid arguments for tool
                   create_task: Invalid input: expected string, received undefined at title"

次の 3 つの特性は、すべて意図的なものであり、いずれも重要です。

• 以下のコード表には含まれず、今後も含まれません。 その表にあるコードはすべて、ハンドラーが意図的に生成する vibeflow のドメインコードです。-32602 は JSON-RPC の invalid params コードであり、vibeflow の用語には含まれません。-32602 がその表に掲載されることはありません。
• 問題のあるフィールドが示されます（… at title、… at contentB64）。メッセージの最後の単語が、誤っていたフィールドです。
• コード文字列はクライアントによって異なるため、これを判定条件にしないでください。 クライアントによっては、このクラスのエラーを独自の文字列に正規化します（たとえば、Pi MCP adapter は call_failed と報告します）。そのラベルはクライアントのものであり、vibeflow のものではありません。同じ拒否でも、通常の JSON-RPC クライアントでは MCP error -32602 になります。あるクライアントのラベルを別のクライアントの出力から検索すると、実際には異ならない挙動を異なると判断してしまいます。 コード文字列ではなく、形状でクラスを見分けてください。 isError === true で、フィールド名を示す入力検証メッセージをテキストに含む結果が該当します。対処法は常に同じです。名前が示されたフィールドを、スキーマが求める型で送信してください。不明なツールはこのクラスに含まれません。フィールド名を示さないため、上記のルールには当てはまらず、対処法も異なります（上の表を参照）。コードだけを基準にすると、この2つを同じ分類にまとめてしまい、実際の間違いはツール名なのに、読者に入力フィールドを探させることになります。

tools/list は、クライアントが失敗する前に契約を確認できる唯一の場所であるため、入力の形状では、エージェントが間違えやすい各フィールドに description を公開しています。各タスクツールの id（多くの場合、完全な ID または一意のプレフィックスが必要です）、setVerify／verifyReason の組み合わせ、limit、contentB64、コメント本文、filename（受け入れ可否は拡張子で決まります）などです。ここで確認してください。やり直す機会はありません。

JSON の場合には、CLI 独自の規約に沿った3つのルールがあります。

• 拒否は CLI のエンベロープ形式です。 {ok:false, error:{code, message, retryable, suggestion?}} — tasks --json が標準エラーに書き出すものと同じ形なので、どちらの出力先も同じパーサーで処理できます。ツールレベルの拒否では isError は設定されません。JSON が {ok:false, …} である通常の結果です。

• すべての拒否には suggestion があり、その意味は「何を変更するか」です。 コードはどのルールに該当したかを示し、suggestion はルールを満たす入力を示します。error.suggestion は、一般的な catch ラッパー（LIST_TASKS_ERROR、GET_TASK_ERROR、CREATE_TASK_ERROR、UPDATE_TASK_ERROR、ADD_COMMENT_ERROR、ATTACH_FILE_ERROR、VERIFY_TASK_ERROR、PUSH_TASKS_ERROR、CLAIM_TASK_ERROR）を含むすべてのツールレベルの拒否で、空でない文字列になります。また、同じ制約に該当する両方のインターフェース、つまり MCP の入力またはツールと CLI フラグの両方を示します。共通の制約に対する suggestion は、CLI と MCP の update_task の両方で参照されるため、CLI 専用の suggestion では MCP クライアントは対処できません。（verify_task は、CLI の検証エンジン独自のコード（E_NOT_FOUND、E_NO_BASELINE、E_NO_SELECTOR など）を返す唯一のツールです。これらのコードは変更されません。エンジンが独自のテキストを付けない場合、ツールは何も対処できないコードを返す代わりに、汎用的な復旧案内を返します。）suggestion がない唯一のクラスは、ハンドラーに到達しない上記のスキーマエラーです。

• 「要求できるものがない」は成功です。 空のボードでの claim_next_task、または有効なフィルターに一致するタスクがない場合は、エラーではなく、ペイロードが null の ok になります。claim のペイロードは Task 自体なので、オブジェクトならタスクが要求され、null なら要求できるものがなかったことを意味します。これは vibeflow tasks --next --json が task:null と終了コード 0 で返す答えと同じです。dryRun プレビューも同じように応答するため、プレビューと実際の呼び出しで食い違うことはありません。NO_TASKS_AVAILABLE コードはありません。

• 把握しておくべき非失敗は notices に含まれます。 これは {code, message} オブジェクトの配列で、CLI が --json の成功ペイロードに付けるものと同じキーです。notice は非致命的なシグナルであり、部分的な成功の同義語ではありません。配列が存在するかどうかではなく、code に基づいて分岐してください。

  コード	意味
  DRY_RUN	プレビューです。何も書き込まれていません
  GIT_COMMIT_FAILED	タスクは書き込まれましたが、コミットは行われていません
  GIT_COMMITTED	情報提供です。コミットは成功しました。message は sha です
  dryRun:true のプレビューには notices:[{code:"DRY_RUN", message:"Task would be updated"}]（または対応する文言 — Task would be created / claimed、Comment would be added、
  File would be attached、Verification would run）が含まれます。レビューの状態遷移には、自動コミットが成功した場合は sha とともに GIT_COMMITTED
  が含まれ、失敗した場合は {code:"GIT_COMMIT_FAILED", message:"…"} が含まれます。このサーフェスに steps キーはもうなく、notices に文字列だけが含まれることもありません。（warning 文字列は別のフィールドで、ここには決して現れません。）

---

関連パッケージ

• @vibeflow-tools/prototyping — URL の永続化に対応した、React 向けアプリ内バリアント切り替え機能です。npm install @vibeflow-tools/prototyping
• ライブ Kanban デモ — ブラウザーで vibeflow ボードをお試しください。

---

コマンド

コマンド	説明
vibeflow kanban [dir]	サーバーを起動し、ブラウザーでライブ Kanban ボードを開きます
vibeflow serve [target]	HTML ファイルをライブ注釈オーバーレイ付きで配信するか、既存のアプリ向けに API 専用のタスクサーバーを実行します
vibeflow tasks	タスクの一覧表示、絞り込み、作成、編集、コメント追加を行います
vibeflow mcp [--project <dir>]	stdio 経由で MCP サーバーを実行します（MCP クライアントが起動します）
vibeflow telemetry	CLI の使用状況テレメトリーを管理します（いつでもオプトアウトできます）

vibeflow kanban [dir]

vibeflow kanban                   # open Kanban board for current directory
vibeflow kanban ./my-project      # open Kanban for a specific project

Kanban ボードでは、ドラッグ＆ドロップで列を移動できるビジュアルタスクトラッカー、親子タスクのツリー、エージェントのステータス表示、ファイル添付機能を利用できます。ボード上でタスクを直接作成するか、注釈付きプロトタイプからインポートできます。

vibeflow serve [target]

vibeflow serve .                  # serve all HTML files in current directory
vibeflow serve dashboard.html     # serve a single file
vibeflow serve -p 4000 .          # custom port
vibeflow serve --no-open .        # don't open browser automatically
vibeflow serve                    # API-only mode — connects to an existing hosted app

注釈オーバーレイ付きで HTML プロトタイプを配信します。任意の要素をクリックすると、その CSS セレクター、URL、ソース位置を含むタスクを作成できます。

vibeflow tasks

コマンドラインからタスクを完全に管理できます。エージェントが使いやすいように設計されています。

# Pick the next task (auto-claims a todo task)
vibeflow tasks --next                             # picks highest-priority todo task
vibeflow tasks --next --type Bug                  # next bug task only

# List tasks
vibeflow tasks                                    # tasks (default: 5 most recent)
vibeflow tasks --limit 0                          # show all tasks (no limit)
vibeflow tasks --json                             # machine-readable JSON output

# Filter
vibeflow tasks --status todo                      # by status
vibeflow tasks --type Bug                         # by type (Task, Bug, Feature, Enhancement, Research)
vibeflow tasks --user [email protected]             # by author email
vibeflow tasks --tag frontend --tag urgent        # by tags (AND matching)

# Get full details of a single task
vibeflow tasks --get <id>                         # supports partial ID prefix

# Create a task, or a child of an existing one
vibeflow tasks --add --title "Fix header" --description "Button overflows on mobile"
vibeflow tasks --add --title "Adjust the tour copy" --parent <id>

# Edit a task
vibeflow tasks --edit <id> --set-status in-progress
vibeflow tasks --edit <id> --title "Updated title" --description "More detail"

# Verification verdict (agent attestation — pass/fail/cannot, one only)
vibeflow tasks --edit <id> --set-verify pass                   # task IS implemented correctly (green badge)
vibeflow tasks --edit <id> --set-verify fail                   # task is NOT correct (amber badge; blocks review)
vibeflow tasks --edit <id> --set-verify cannot --verify-reason "<why>"  # unverifiable here (no badge; reason recorded)
# Research tasks must NOT carry a verdict — they have no annotated UI to verify, and the CLI REJECTS it (RESEARCH_VERIFY_NOT_ALLOWED)

# Mark as review (requires implementation report; annotated URL+selector tasks also need a verdict)
vibeflow tasks --edit <id> --set-status review --set-verify pass \
  --commit-message "fix: header layout" \
  --comment "Fixed the alignment issue by adjusting flex-wrap"

JSON 出力（--json）： エンベロープは 1 つで、識別子は ok のみです。成功時は {ok:true, …payload} を stdout に出力します。tasks の場合は {ok:true, tasks:[…], hiddenChildren}、--get の場合は {ok:true, task:{…}}、--add／--edit／--next の場合は {ok:true, task:{…}, next_actions:[…]} です。失敗時は {ok:false, error:{code, message, retryable, suggestion}} を stderr に出力し、0 以外で終了します。すべての 0 以外の終了時にこのエンベロープを出力します。説明文だけを出力する拒否応答では、機械処理を行うクライアントに stdout が空でコードもない状態を残してしまうためです。--json では、例外なく、どの経路でも stdout は 空か、JSON ドキュメントがちょうど 1 つ になります。

「作業対象がない」場合も成功です。 ボードが空の場合、または有効なフィルター（--type Bug、--tag）に一致する todo タスクがない場合、--next は {ok:true, task:null, next_actions:[]} を stdout に出力し、終了コード 0 で終了します。キーの組み合わせは正常に claim された場合と同じで、task === null が分岐条件です。claim されたタスクは必ずオブジェクトになります。一致するものがないフィルターの状況はボードが空の場合と 同じ であり、特別扱いではありません。--json なしの場合は、No todo tasks found. Nothing to work on. という文と終了コード 0 に変更はありません。MCP ツール claim_next_task も同じ状況に対して同じように応答します — 以下を参照してください。（これは、--json の場合に文を出力していた以前の裁定を覆すものです。NO_TASKS_AVAILABLE はもう存在しません。）

--user は例外で、以前から常にそうです。tasks --next --user … は空のボードを報告するのではなく、E_USAGE（終了コード 2）で拒否されます。これは --next が作成しない候補作成者リストに対してフィルターを検証するためです。この拒否動作は以前から存在しており、上記の空ボード時の成功による変更はありません。

意味ごとにコードは 1 つです。

code	意味	再試行可能
E_USAGE	不正なフラグ値、または指定できないフラグの組み合わせ（例：--set-status review を指定せずに --report-file を指定する、編集対象がない状態で ID を指定せずに --edit を指定する、オンラインボードで --parent を指定する）	いいえ
TASK_NOT_FOUND	タスクまたは親タスクが存在しません（MCP ツールと同じコードです）	いいえ
E_NOT_FOUND	--report-file のパスなど、その他の項目が見つかりません	いいえ
E_BACKEND_UNAVAILABLE	オンラインバックエンドへの呼び出しに失敗しました — retryable: true となるのはホストに到達できなかった場合のみです	到達できない場合のみ
E_NOT_AUTHENTICATED	トークンがない、またはセッションが拒否されました（HTTP 401/403）	いいえ
E_COMMENT_SAVE	タスクは書き込まれましたが、要求されたテキスト（--comment、または cannot 判定の --verify-reason）は保存されませんでした	いいえ
GIT_COMMIT_FAILED	error.code の場合は何もコミットされていません。notices[].code の場合はタスクは書き込まれ、コミットだけが行われませんでした	いいえ
REINDEX_WRITE_FAILED	--reindex-sort-keys で sortKey の書き込みを計画しましたが、1 件も書き込まれませんでした — タスクファイルは変更されていません	いいえ
REVIEW_COMMENT_REQUIRED、COMMIT_MESSAGE_REQUIRED、BRANCH_REQUIRED、VERIFY_REQUIRED、VERIFY_FAILED_ATTESTED、VERIFY_REASON_REQUIRED、RESEARCH_REPORT_REQUIRED、RESEARCH_VERIFY_NOT_ALLOWED	レビューゲートによる拒否（vibeflow tasks --edit --set-status review を参照）	いいえ

コードはグローバルではなく、コマンドごとに適用されます。tasks の TASK_NOT_FOUND は「そのタスクがない」ことを意味し、tasks の E_NOT_FOUND は「そのファイルがない」ことを意味します（例：--report-file）。この 2 つのサーフェスにはそれぞれ異なるコード体系があります。呼び出したコマンドのコードを確認してください。

この表はドメインコードの語彙です。各行は vibeflow のハンドラーが意図的に返した拒否を示し、どのコードにも修正方法を示す suggestion が付いています。スキーマエラーのクラスは意図的に含めていません。ツール独自のスキーマで拒否された入力は、ハンドラーが実行される前に MCP SDK によって拒否されるため、vibeflow のコードも suggestion もありません。見分け方については、上記の スキーマエラーのクラス（-32602） を参照してください。

notices は、呼び出し元が把握しておくべき致命的ではないシグナルを、code で識別して格納する CLI の構造化フィールドです。「一部成功」の同義語ではなく、この配列があるだけで何か問題が起きたという意味にはなりません。成功ペイロードでは、{code, message} の任意の配列であり、問題なく実行された場合は含まれません。

code	意味
GIT_COMMIT_FAILED	タスクは書き込まれましたが、レビュー後の自動コミットだけが行われませんでした
REINDEX_INCOMPLETE	sortKey の再キー付けは完了しましたが、その後のアサーションに失敗しました
SET_STATUS_DONE	ポリシー上の注記：エージェントは作業を review に設定し、タスクを done にするのは人間だけです
RESEARCH_NO_IMPLEMENT	Research タスクには引き継ぐ実装がありません
ALREADY_IN_PROGRESS	タスクはすでに進行中で、変更はありませんでした

配列は常に配列です（単独のオブジェクトになることも、notices と warnings に分割されることもありません）。ローカルの --edit パスはこれらをすべて出力します。オンラインの --edit パスで出力できるのは SET_STATUS_DONE のみです（残りはローカルのタスクファイルを対象に判定されますが、オンラインボードにはそれに相当するものがありません）。そのため、notices は「存在する場合もない場合もある配列」として扱い、コードが常に一定だとは考えないでください。MCP サーフェスでも同じ名前を同じ概念に使い、さらに独自の DRY_RUN と GIT_COMMITTED も使用します。CLI はコミットが成功しても何も出力しません。詳しくは MCP の結果 を参照してください。

warning は別のフィールドで、サーフェスごとに異なります。どちらのサーフェスでも単独の文字列ですが、次の 2 つのサーフェスでそれぞれ異なる意味を持ちます。

• オンラインボードのオンライン --edit ペイロードに含まれる、サーバーからそのまま渡された文字列。
• verify サーフェスの、ページ全体に対する vibeflow verify <id> <tool> --json の結果に含まれる、キャプチャ切り詰めに関する注記（truncated:true の結果には、部分的な表示であることを説明する warning が含まれます）。 つまり、warningはオブジェクトになることはなく、「部分的な成功」を意味することもありません。notices[].codeに基づいて分岐するコンシューマーが、これによって予期せず動作することはありません。

tasks --commit --jsonには、**autoPush: {attempted, ok, error?}**も含まれます。自動プッシュはどちらのモードでも実行されます。--jsonが抑制するのは進行状況の行だけで、プッシュ自体は抑制しません。そのため、これは結果を文章ではなく機械処理可能な形でコンシューマーに渡す方法です。attempted: falseは、新たにプッシュするものがなかったことを意味します。既存のコミットに紐付けられているか、設定でautoPushがオフになっています。プッシュに失敗しても、コミット自体は作成されているため、ok:trueかつ終了コードは0のままです。失敗したプッシュは別途再試行できます。

**0.18.0での破壊的変更：**以前はtasks --jsonが配列をそのまま返し、--get --jsonはフラットなオブジェクトを返していました。また、成功ペイロードにはok:trueではなくsuccess:trueが含まれ、タスクが書き込まれていたにもかかわらず、自動コミットの失敗時には終了コードが1になっていました。ローカル通知フィールドはwarningではなく、配列のnoticesです。

vibeflow verify <id>が収集するのはページの健全性に関する証拠だけです（要素が解決され、新しいコンソールエラーがないこと）。判定は設定しません。タスクをレビューに移すとき、エージェントが正しさを判断し、--set-verifyで証明します。選択肢はpass（正しく実装されている）、fail（正しくないため、レビューへの移行をブロック）、または--verify-reasonを指定したcannot（ここでは検証できず、タスクのアクティビティに記録される）です。

タスクの種類： Task · Bug · Feature · Enhancement · Research
タスクのステータス： backlog → todo → in-progress → review → done
優先度： Critical · High · Medium · Low

同期ストアの安全性： .vibeflowストアはGitで追跡され、マシン間で同期されるため、未解決のマージがある状態でgit add -Aを実行しないでください。競合マーカー（<<<<<<< / ======= / >>>>>>>）が残っているタスクファイルは解析できません。そのため、CLIが隔離し、そのタスクはすべての一覧からひっそりと消えます。ルールは、マージを解決し、プルして、検証してから追加することです。pre-commitフックはpnpm check:storeを実行します（すべての.vibeflow/tasks JSONファイルが解析可能で、競合マーカーを含まないことを確認し、問題のあるパスを表示して失敗します）。また、tasks --normalizeは解析不能なレコードや隔離されたレコードを破棄せず、明確に報告します。隔離されたレコードが通知されずに済むこともありません。pull、list、pushはそれぞれ、実行ごとに件数と最初の理由を含む警告を1つ出力します（stderr、および--jsonの場合はエンベロープ内のnotices）。これは警告であり、失敗ではないため、終了コードは0のままです。

vibeflow telemetry

vibeflow telemetry              # show current status
vibeflow telemetry --disable    # opt out of usage tracking
vibeflow telemetry --enable     # opt back in

PIIが収集されることはありません。ユーザーの識別情報はハッシュ化されます。

収集される情報。 各呼び出しにつき、少数の大まかなプロパティを含むcommand_runイベントを1つ収集します。

• command — 最上位のコマンド（tasks、serve、kanbanなど）
• subcommand — サブコマンドを持つコマンド内のモード：tasksではlist / get / add / edit / next / reindex、serveではapi（API専用のタスクサーバー）またはprototype（HTMLターゲットが指定されている場合）を出力します
• from_status / to_status — tasks --editの場合のみ：編集前後のタスクのステータス。backlog | todo | in-progress | review | doneから選択され、ステータスの遷移をファネルとしてクエリできます

収集されることのない情報：タスクID、タイトル、説明、ファイルパス、セレクター、URL、その他のタスク内容。

---

ブラウザーオーバーレイ

オーバーレイは、HTMLプロトタイプや稼働中のアプリなど、任意のページに挿入されるShadow DOMパネルです。

• クリックして注釈を追加 — 任意の要素をクリックするとタスクフォームが開き、CSSセレクター、URL、ソースの場所があらかじめ入力されます
• タスクサイドバー — 開いているタスクをステータスバッジ付きで一覧表示します。クリックすると、注釈を付けた要素に移動します
• タスクインジケーター — 注釈を付けた要素に番号付きマーカーを表示します
• リアルタイム同期 — WebSocketとファイルのライブ監視を使用します
• スクリーンショットのキャプチャ — オーバーレイからスクリーンショットをタスクに添付できます
• ダークテーマ — 設定不要の洗練されたダークUIです
• キーボードショートカット — Alt+Aで注釈モードを切り替えます
• CSPに安全な挿入 — ブックマークレットはscript-srcの制限を回避します

注入方法

オーバーレイは、次の3つの方法で任意のページに注入できます。

方法	最適な用途	CSPへの対応
ブックマークレット（推奨）	本番アプリを含む任意のページ	対応
スクリプトタグ	HTMLを管理できるページ	非対応
DevToolsコンソール	すぐに行う単発のセッション	対応

実行中のサーバーで /inject にアクセスすると、すぐに使えるブックマークレットとスニペットを確認できます。

---

動作の仕組み

You browse your app  →  click to annotate  →  task created with context
          ↑                                         ↓
    browser reloads  ←  agent implements  ←  vibeflow tasks --next

1. オーバーレイ — ブックマークレットまたはスクリプトをアプリに埋め込み、任意の要素をクリックして注釈を付けます
2. カンバン — ボードを開いてすべてのタスクを一覧で確認し、新しいタスクを直接作成します
3. タスク — vibeflow tasks --next で、エージェント向けの完全なコンテキストとともに、最も優先度の高いタスクを選択します
4. 反復 — エージェントが実装し、ブラウザーが再読み込みされたら、再び注釈を付けます

---

エージェント連携

Vibeflow のタスクは、完全なコンテキストを含む形式で AI エージェントに提供されます。

• CSS セレクター — 推測の余地がない、正確な要素の指定
• ソースの位置 — 要素が定義されているファイル、行、列
• スクリーンショット — タスクに添付された視覚的なコンテキスト
• コメント — 各タスクに関するスレッド形式のディスカッション
• ファイル添付 — 調査レポート、仕様書、参考資料
• Git コミット — コミットメッセージ内の [proto:task-id] を通じて、変更をタスクに関連付けます

カンバンボードから POST /api/agent/run を実行して、完全なタスクコンテキストとともに opencode を起動することもできます。

---

API

連携とブラウザーオーバーレイ向けに、http://localhost:3700 で REST API と tRPC ルーターを利用できます。主なエンドポイントは次のとおりです。

• /kanban — ライブカンバンボード
• GET/POST /api/tasks — タスクの一覧表示と作成
• GET/PATCH/DELETE /api/tasks/:id — 個々のタスクの管理
• GET/POST /api/tasks/:id/comments — タスクのコメント
• GET/POST/DELETE /api/tasks/:id/files — ファイル添付
• POST /api/agent/run — タスク用の AI エージェントを起動
• /inject — オーバーレイ注入のヘルパーページ

API の全容は src/server/server.ts を参照してください。

---

貢献

pnpm install          # install dependencies
pnpm build            # build CLI
pnpm test             # unit tests
pnpm test:integration # integration tests (verify flow across a temp project)
pnpm test:e2e         # end-to-end tests
pnpm test:browser     # Playwright browser tests (kanban board, overlay)
pnpm test:coverage    # unit coverage only
pnpm test:coverage:e2e  # unit + e2e coverage MERGED (see below)

test:browser の実行には、一度だけブラウザーが必要です。npx playwright install chromium を実行してください。

変更時に必須のチェック

各テストスイートはそれぞれ専用のスクリプトからのみ実行でき、どのスクリプトもほかのテストスイートを実行しません。そのため、pnpm test が成功しても、e2e、統合テスト、ブラウザテストについては何もわかりません。変更をコミットする前に、すべて実行してください。

コマンド	対象
pnpm run lint:symbols	packages/*/src/** に対する ESLint
pnpm --filter @vibeflow-tools/cli run lint	tsc --noEmit
pnpm run test	単体テスト
pnpm run test:integration	統合テスト（検証フロー）
pnpm run test:e2e	エンドツーエンド（CLI を子プロセスとして起動）
pnpm run test:browser	ブラウザ（Playwright）— UI を変更する場合は必須
pnpm run build	リリース用 CLI の tsup バンドル

最初の3つと build は、コミット前フックで実行されます。統合テスト、e2e、ブラウザテストはフックに含まれないため、これらが省略されていないことを確認できるのは、この一覧だけです。

test:coverage は、プロセス内の単体テストで実行されるコードを報告します。ただし、このパッケージの全体像はわかりません。src/index.ts はほぼすべてがコマンドのディスパッチ処理であり、各コマンドは e2e テストで検証されます。e2e テストは CLI を子プロセスとして起動し、v8 のカバレッジ計測ではその実行を追跡できません。そのため、数百件の e2e アサーションが src/index.ts を実行していても、行カバレッジは約16％にとどまっていました。test:coverage:e2e では、この計測を修正します。ソースマップ付きで、最小化していない CLI を .coverage-cli/ にビルドし（リリース用バンドルは最小化され、ソースマップも削除されるため、src/** に対応付けられません）、NODE_V8_COVERAGE を設定してその CLI に対して e2e テストを実行します。その後、子プロセスのカウンターを変換してソースに対応付け、ソース位置に基づいて単体テストのカウンターとマージし、coverage/merged/ に出力します（text、json、lcov）。src/index.ts の単体テストのみ、e2e のみ、マージ後の数値を標準出力に表示します。マージツールチェーンは @vitest/coverage-v8 の間接依存関係としてすでに含まれているため、package.json への追加はありません。

---

ライセンス

Apache-2.0 — 第三者のクレジットについては NOTICE を参照してください。