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 **Roadma

... View full README on GitHub