Withvibe Roadmap

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.

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.