feat(visual-plan): native builder.io visual-plan replica — Phase 1 (all 3 providers)

[Ecko95]

Native Visual Plan for GITS (builder.io visual-plan parity) — Phase 1

Replicates Builder.io's visual-plan skill natively inside GITS with zero dependency on @agent-native/core, their hosted app, the local bridge, or their MCP. The agent authors a typed, structured plan that renders live in a new interactive side panel; all three providers (Claude / Codex / Cursor) are wired.

How it works

provider session (Claude / Codex / Cursor)
  └─ loads .claude/skills/visual-plan/SKILL.md → calls GITS's own MCP endpoint
       /api/gits/visual-plan/mcp  (Bearer = per-session token → threadId)
         tools: get-plan-blocks, create/update/get-visual-plan,
                get-plan-feedback, export-visual-plan
  → orchestrationEngine.dispatch(thread.visual-plan.upsert)
  → decider → event → projector → SQL projection (migration 031) → WS
  → client-runtime reducer → store → VisualPlanPanel.tsx (renders live)

The MCP handler runs in-process, resolves the calling thread from a per-session bearer token (a process-global registry singleton), and dispatches a thread.visual-plan-upserted event carrying a typed PlanContent block document.

Included (Phase 1 — all three providers)

• Contracts (packages/contracts/src/visualPlan.ts): typed block registry (rich-text, callout, checklist, table, code, annotated-code, file-tree, implementation-map, api-endpoint, data-model, question-form, tabs, columns), PlanContentPatch, flat PlanCommentAnchor.
• Orchestration data plane: thread.visual-plan-upserted through decider → projector → SQL projection (migration 031) → snapshot hydration → WS → web store / client-runtime.
• Native MCP endpoint: minimal Streamable-HTTP JSON-RPC server (6 tools) + per-session token gate.
• Provider wiring: Claude (mcpServers http), Cursor (ACP McpServer http via AcpSessionRuntime), Codex (per-thread thread/start config.mcp_servers override — no config.toml mutation).
• Skill: .claude/skills/visual-plan/SKILL.md.
• Web: VisualPlanPanel block renderer + ChatView mount (inline + sheet, lazy-loaded) + composer toggle + --wf-* wireframe theme tokens.

Verification

• All packages typecheck clean against this gits base (contracts / server / web / client-runtime).
• Unit tests: patch/export/catalog helpers.
• Headless boot (on the original base): server comes up with the full layer graph, migration 031 applied, MCP route mounted (401 on missing/invalid token, 404 control).
• HTTP integration test: drives the served MCP route end-to-end with a minted token (initialize → tools/list → tools/call get-plan-blocks) + token-rejection path.

Live agent round-trips weren't run end-to-end: codex/cursor-agent binaries aren't installed in the dev box, and a live Claude turn needs auth + nondeterministic tool-calling. Per-provider transport injection is typecheck-verified; the shared MCP path is exercised by the integration test.

Note on history

These commits were authored on a local base and replayed (cherry-picked) onto origin/gits; conflicts in server.ts, ChatView.tsx, ChatComposer.tsx, and server.test.ts were resolved to preserve both gits's recent work (Delamain sidebar, MCP inventory, lazy panels, review pipeline) and the visual-plan additions.

Deferred (follow-up phases)

• Skill distribution to managed provider homes (currently repo-local).
• P2: diagram render (inert HTML/CSS), anchored comments, in-panel edit→patch, send-back-to-session.
• P3: wireframe canvas + sandboxed-iframe Alpine.js prototype.

🤖 Generated with Claude Code