withvibe-roadmap

WithVibe ロードマッププラグイン

WithVibe向けの環境ごとの実装ロードマップボードです。Postgres を基盤とし、AI オーケストレーターが直接操作する MCP サーバーを備えています。

複数のフェーズにまたがる機能は、進行中に方向がずれていきます。計画は途中で変わります。数回のセッションを経ると、何がリリース済みで、何が保留中で、今どのステップにいるのかを把握できなくなります。このプラグインは、AI が状態を構造化して記録する場所を提供し、ユーザーがその状態をリアルタイムで確認できるようにします。

Feature: Auth rewrite                          ▓▓▓▓░░░░░░ 4/11 tasks
you are here →  API layer  ›  Wire DTO validation

[x] Phase 1: Schema (done)
[~] Phase 2: API layer (in progress)
    [x] Endpoint scaffolding
    [x] Auth guard
    [~] Wire DTO validation     ← active
    [ ] Error envelope
[ ] Phase 3: Web
[ ] Phase 4: QA

— Plan changes —
2026-05-28  AI added Phase 4 (QA) — reason: integration tests not in original scope
2026-05-29  user removed "Add caching" — reason: deferred to follow-up

内容

• 階層型ロードマップ — 機能 → フェーズ → タスクで構成され、pending / in_progress / done / blocked / deferred / canceled のステータスを設定できます。
• 「現在地」マーカー — 一度にアクティブにできるタスクは1つだけです。コンテキストを切り替えて戻ったとき、バナーが作業再開の手がかりになります。
• 計画変更ログ — 追加・削除・名前変更・ステータス変更のたびに、実行者（ai または user）と任意の理由を記録します。この履歴から、計画のずれを確認できます。
• AI オーケストレーターがプロンプトなしで使用する MCP ツール：propose_plan、set_active_task、complete_task、add_note、update_task、log_change、…
• ライブ UI — htmx ベースで、軽量なバージョンエンドポイントをポーリングします。スクロール位置を飛ばすことなく、AI による変更から約4秒以内に iframe が更新されます。
• 永続化 — WithVibe の shared-postgres プラグインストレージを使用するため、コンテナーを再起動しても状態が維持されます。

アーキテクチャ

manifest.yaml ──→ WithVibe spawns one container per env
       ↓
   server.js (express)
   ├── /health         platform health probe
   ├── /mcp            AI orchestrator's MCP endpoint  ─→ mcp.js
   ├── /ui             dark-themed htmx UI             ─→ ui.js
   └── /ui/version     cheap freshness check (drives live updates)
                ↓
              db.js (pg)
                ↓
          shared-postgres
          per-env schema
          plan / phase / task / plan_event

• スコープ：env — 環境とプラグインの組み合わせごとに1つのコンテナーが起動します。各環境には、独自のロードマップ、Postgres スキーマ、ポートが割り当てられます。
• ストレージ：shared-postgres — プラットフォームが withvibe_plugins データベースに専用のロールとスキーマを用意し、起動時に DATABASE_URL と PGSCHEMA を注入します。プラグインのロールからメインの withvibe DB にアクセスすることはできません。
• 状態の保存先：db.js 内の4つのテーブルです。plan（シングルトン）、phase、task、plan_event（変更ログ）で構成されます。

MCP ツール

すべてのツールは、最新の状態が古くならないよう、更新後の計画全体を末尾のテキストで返します。

ツール	用途
get_plan	ロードマップ全体、アクティブマーカー、直近20件のイベントを読み取ります。
propose_plan	ロードマップ全体を置き換えます（初期計画または大幅な計画変更）。
add_phase / add_task	作業の進行中に作業項目を追加します。reason が記録されます。
set_active_task	作業開始前に「現在地」の目印を設定します。
complete_task	1行の成果を添えて完了にします。すべてのタスクが完了すると、フェーズも自動的に完了します。
update_task / update_phase	理由を添えてタイトル・説明・ステータス（blocked、deferred、canceled）を編集します。
add_note	決定事項、試したこと、参照情報などをマークダウン形式のメモとして追加します。
log_change	データを変更せず、計画レベルの決定を記録します。

完全なスキーマについては、mcp.js を参照してください。

ビルド

docker build -t local/roadmap:2.0 .

Node 20 Alpine を使用しているため、マルチアーキテクチャに対応しやすく、サイズは約150 MBで、ネイティブなビルド手順はありません。

WithVibe へのインストール

1. ワークスペース管理者 → プラグイン → プラグインをインストール。
2. manifest.yaml の内容をエディターに貼り付けます。
3. プラットフォームがイメージを取得または特定し、プラグインを登録します。
4. 任意の環境を開くと、プラグインパネルに ロードマップ タブが表示されます。

イメージを再ビルドした後に更新するには、管理者リストのプラグイン行にある 更新 をクリックします。実行中のインスタンスは停止されるため、次回の環境起動時に新しいイメージが使用されます。

マニフェスト

マニフェストがインストール時に指定する内容のすべてです。このプラグインで重要なフィールドは次のとおりです。

id: withvibe.roadmap          # URL + tool prefix; reverse-DNS-ish
name: Roadmap                 # display name in the env's plugin panel
version: 2.0.0
icon: list-todo               # Lucide icon
image: local/roadmap:2.0    # OCI ref

scope: env                    # one container per env
storage:
  kind: shared-postgres       # platform-managed Postgres role + schema

ui:
  path: /ui                   # iframe entry point
  websocket: false

mcp:
  enabled: true
  path: /mcp                  # MCP endpoint the AI auto-discovers

ローカル開発

# Build
docker build -t local/roadmap:2.0 .

# Run standalone (requires a Postgres reachable via DATABASE_URL)
docker run --rm -p 8080:8080 \
  -e DATABASE_URL="postgres://user:[email protected]:5432/withvibe_plugins" \
  -e PGSCHEMA="roadmap_dev" \
  local/roadmap:2.0

# Then open http://localhost:8080/ui

実際の WithVibe インストール環境を使って開発する場合は、再ビルドのたびに管理者向けのプラグインページで 更新 をクリックしてください。実行中のインスタンスが停止されるため、次回の環境起動時に新しいイメージが使用されます。

リポジトリ構成

manifest.yaml   WithVibe plugin manifest
Dockerfile      builds the runtime image
package.json    npm deps (express, pg, @modelcontextprotocol/sdk, zod)
server.js       express entry, HTTP + MCP routes
db.js           pg pool, schema init, query helpers
mcp.js          MCP tool registrations
ui.js           htmx UI rendering + dark-themed CSS

コントリビューション

Issue と PR を歓迎します。変更は対象を絞り、コミットでは なぜ 変更するのかを説明してください。

ライセンス

Apache License 2.0。著作権表示については NOTICE を参照してください。