WithVibe Roadmap Plugin

A per-env implementation roadmap board for WithVibe — Postgres-backed, with an MCP server the AI orchestrator drives directly.

Multi-phase features drift. Plans change mid-flight. After a few sessions you lose track of what shipped, what's pending, and which step you're actually on. This plugin gives the AI a structured place to keep that state — and the user a live view of it.

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

What's in the box

• Hierarchical roadmap — feature → phase → task, with pending / in_progress / done / blocked / deferred / canceled statuses.

• "You are here" marker — exactly one task is active at a time; the banner is the recovery anchor when you context-switch back.

• Plan-change log — every add/remove/rename/status-change records an actor (ai or user) and an optional reason. The trail makes drift visible.

• MCP tools the AI orchestrator uses without prompting: propose_plan, set_active_task, complete_task, add_note, update_task, log_change, …

• Live UI — htmx-based, polls a tiny version endpoint so the iframe updates within ~4s of any AI change without scroll jumps.

• Persistent — uses WithVibe's shared-postgres plugin storage, so state survives container restarts.

Related MCP server: MCP Planning Server

Architecture

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

• Scope: env — one container per (env, plugin). Each env gets its own roadmap, its own Postgres schema, its own port.

• Storage: shared-postgres — the platform provisions a dedicated role + schema in the withvibe_plugins database and injects DATABASE_URL + PGSCHEMA at spawn. The plugin role can't reach the main withvibe DB.

• State surface: four tables in db.js — plan (singleton), phase, task, plan_event (change log).

MCP tools

All tools return the full updated plan in the trailing text so the AI never holds stale state.

See mcp.js for the full schemas.

Build

docker build -t local/roadmap:2.0 .

The image is multi-arch-friendly via Node 20 Alpine, ~150 MB, no native build steps.

Install in WithVibe

1. Workspace admin → Plugins → Install plugin.

2. Paste the contents of manifest.yaml into the editor.

3. The platform pulls / locates the image and registers the plugin.

4. Open any env → the Roadmap tab appears in the plugin panel.

To update after rebuilding the image, hit Update on the plugin row in the admin list — running instances are stopped so the next env start picks up the new image.

Manifest

The manifest is the entire install input. The fields that matter for this plugin:

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

Local development

# 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:pass@host.docker.internal:5432/withvibe_plugins" \
  -e PGSCHEMA="roadmap_dev" \
  local/roadmap:2.0

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

When developing against a real WithVibe install, hit Update in the admin Plugins page after each rebuild — that stops running instances so the next env start picks up the new image.

Repository layout

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

Contributing

Issues and PRs welcome. Keep changes focused and document the why in commits.

License

Apache License 2.0. See NOTICE for attribution.