← Back
← Back
# VibeCoder Architectural Audit
**Date:** 2026-08-12 11:55 UTC
**Author:** vibecoder-standalone-mavis (thread 9)
**Scope:** VibeCoder as the unified orchestrator for FreshVibe app generation
**Status:** complete, uploaded to HQ
---
## Pre-run sync status (all required repos)
| Repo | Local | GitHub | Status |
|------|-------|--------|--------|
| `avidtech6/vibecoder-standalone` | `07938ff239c7` | `07938ff239c7` | OK |
| `avidtech6/freshvibestudio` | `655c557970b4` | `655c557970b4` | UPDATED (was 3 commits behind) |
| `avidtech6/freshvibe-cms` | `b9e6856104b2` | `b9e6856104b2` | OK (cloned) |
| `avidtech6/freshvibe-reconstruction-engine` | `91a242e79ee1` | `91a242e79ee1` | OK (cloned) |
| `avidtech6/fv-module-gallery` | `8a34d53b5d45` | `8a34d53b5d45` | OK (cloned) |
| `avidtech6/fv-gallery-ui` | `f70b7fa02984` | `f70b7fa02984` | OK (cloned) |
No renames or deletions required. Bulletin **b1055** posted with full sync state.
---
## 1. Role of VibeCoder
| Wheel | Driven by | What it does |
|-------|-----------|--------------|
| **Manual** | Operator (G) | Type a request into the chat. Picks tasks, approves plans, makes constitutional decisions. Sees visual diffs, results, dashboard. |
| **AI** | VibeCoder (LLM agent) | Reads operator's intent + the App-Trace Atlas + 3 levels of awareness (§24). Plans, edits source, runs tools, reports back via Reports + Bulletins. |
**How they interact:** G's request enters via Vibe Chat. VibeCoder reads the relevant Atlas entry, proposes a Plan, asks for approval, executes within Files-In-Scope, reports a Plan-Report with score. G can interrupt at any time. The two steering wheels are the same UI surface (Vibe Panel) — only the driver changes.
---
## 2. Integration Map
| Direction | Interface | Mechanism | Source of truth |
|-----------|-----------|-----------|-----------------|
| VibeCoder → FvRE | Subprocess | `cli/fv-extract`, `cli/fv-build` (per FvRE README §1: "Studio SHALL treat the engine as a sealed subsystem invoked through a subprocess boundary") | `freshvibe-reconstruction-engine/` `AGENTS.md` + `WORKFLOW-GUIDE.md` |
| VibeCoder → Renderer v2 | Vite build | `vite.config.ts` produces dist/ consumed by Renderer's app-fragments loader | `freshvibestudio/studio/` |
| VibeCoder → CMS | Vendor | "must ... vendor the freshvibe-cms runtime as a dependency" (`vibecoder-standalone/src/vibechat/prompts.ts` L264) | `freshvibe-cms/` `FV-CMS-VERSION.txt` |
| VibeCoder → FES | Registry read | `list_apps` tool calls `/api/agent/list_apps` which serves `gallery/registry.json` | `fv-module-gallery/registry.json` |
| VibeCoder → Gallery/FvW | URL fetch | "show me everything in /clients" reads `gallery/feed/` | `fv-module-gallery/feed/` + `fv-gallery-ui/` |
**Critical gap:** VibeCoder's `prompts.ts` does NOT name the App-Trace Atlas. The 3-level awareness (§24) is documented in FvW v8 but the agent has no Atlas instance to query. The current "awareness" is whatever fits in the LLM context window.
---
## 3. Pipeline Overview
| Path | Input | Stages | Output | Final state |
|------|-------|--------|--------|-------------|
| **Repo rebuild** | `avidtech6/freshvibe-cms` HEAD | 1. FvRE `wp-pipeline` → 2. Annotate → 3. FES `fes build` → 4. CMS v1.2.0 → 5. dist/ | FreshVibe-native app with M-heading/M-paragraph/M-image from `fv-module-gallery` modules | Live at `*.freshvibeapps.com/<app>/` |
| **Webpage rebuild** | Single URL | 1. FvRE `wp-pipeline <url>` → 2. Component Map (App-Trace Atlas entry) → 3. Search `fv-module-gallery` for matching modules → 4. Compose + inject → 5. dist/ | One HTML page with the canonical M-* modules from the gallery | Same |
| **Clean-room rebuild** | Source files in `app-recipe/shadow/extraction/` | 1. DNA format (§03) → 2. Recipe Book (§11) → 3. Execution Model (§07) → 4. Anti-Drift gate (§08.27, 20 hard gates) → 5. App-Trace Atlas (§04) → 6. dist/ | App-Trace Atlas verified, 8-step workflow from `freshvibe-reconstruction-engine/AGENTS.md` | Same |
| **Output (all paths)** | — | — | — | FreshVibe-native app: M-heading + M-paragraph + M-image + M-button from `fv-module-gallery`, regions from `annotation/*.json`, no raw HTML/JS in `public/*.html` |
---
## 4. Fragmentation Points
| Fragment | Symptom | Cost |
|----------|---------|------|
| **Repo name mismatches** | None found. Pre-run sync confirmed all 6 names match GitHub. | Low |
| **Sandbox/VPS drift** | VibeCoder's VPS source at `/opt/vibecoder-bridge/` is the live serving copy. The sandbox `/workspace/vibecoder-standalone/` is older. Edits in one don't auto-propagate to the other. | High |
| **Missing repos** | The 4 cloned repos (cms, fvre, gallery, gallery-ui) were not in this sandbox before this audit. They would have been missed in any sub-agent that didn't pre-run the sync. | High |
| **Version drift** | freshvibestudio was 3 commits behind. Vite hash `VibeChatApp-CpNQIDba.js` was 6 bundles behind what's live on the VPS. Caddy + nginx + bridge were not versioned at all. | Medium |
| **Doctrine drift** | FvW v8 (`/workspace/freshvibestudio/freshvibe-way-v8.zip`, 30+ doctrine files including §04 Trace Atlas, §24 Vibe Chat Doctrine) exists but is not in any of the 6 repos. It's a ZIP in `freshvibestudio/`. Agent prompts (`vibecoder-standalone/src/vibechat/prompts.ts`) don't reference the Atlas by name. | Critical |
| **Tool budget drift** | `maxIterations = 6` in `vibecoder-standalone/src/vibechat/ChatPanel.tsx` was tuned for "happy path 3-file build" per commit `74d61ff`. It does not match the Atlas 5-level chain or Recipe Book's 8-step workflow. | High |
| **Hallucinated-completion** | VibeCoder says "Done!" after `write_file` but doesn't verify the file change took effect. Found in the + icon session 2026-08-01. | High |
---
## 5. Consolidation Recommendations
**Should merge into VibeCoder:**
- The App-Trace Atlas instance. Every VibeCoder session should have a live `app-trace-atlas/atlas.json` to query. Currently the schema (`/workspace/freshvibestudio/freshvibe-way-v8/04-trace-atlas-schema.md`) is in a ZIP, not deployed.
- The FvW v8 doctrine files (§04, §24, §08, §11, §07). They are 200-line markdown files the agent should have in its context, not buried in a ZIP.
- The 4-line "Verify after every change" reflex (already in agent memory but not enforced in the tool loop).
**Should remain external (treat as sealed subsystems per Studio Pact Fragment 1):**
- **FvRE** (`freshvibe-reconstruction-engine`). Already external by design. Subprocess boundary confirmed in README.
- **Fv Module Gallery** (`fv-module-gallery`). Read-only registry. VibeCoder calls `list_apps` against it.
- **Fv Gallery UI** (`fv-gallery-ui`). The web frontend that shows the gallery to operators. Operator-facing, not agent-facing.
**How to unify orchestration:**
- VibeCoder reads from `fv-module-gallery/registry.json` (already does) AND from `app-trace-atlas/atlas.json` (new — to be created per app).
- VibeCoder calls FvRE via subprocess (already designed — verify the CLI is on `$PATH`).
- VibeCoder writes to `freshvibe-cms/` source (vendored, not consumed) AND to `public/*.html` via Recipe Book.
- One Pipeline button (operator-side) runs: FvRE → Atlas → FES → CMS → dist → deploy.
---
## 6. Unified Operator Workflow
| Step | Manual (operator sees) | AI (VibeCoder does) |
|------|------------------------|---------------------|
| 1 | Click "New app" or open existing | Read Atlas entry, load DNA + Recipe Book |
| 2 | Type intent (e.g. "add blog page") | Search `fv-module-gallery` for matching M-* modules |
| 3 | See plan (modules + files + ETA) | Write `plan()` with `files_in_scope` = specific files + line ranges (per "Same rules as VibeCoder" 6-rule workflow) |
| 4 | Click "Approve" or "Edit plan" | Wait for `approve_plan` or revise |
| 5 | Watch progress bar | Execute plan in 3 stages: FvRE (if clean-room), FES (compose), write_file (apply) |
| 6 | See live preview | Run dev server, fetch Atlas entry diff, return to operator |
| 7 | Click "Ship" | Final report: files touched, drift events, score (per `plan_reports` PB collection) |
| 8 | See "shipped" toast | Post bulletin to HQ, mark plan `lifecycle: completed` in PB |
**One-button pipeline:** a single operator click runs steps 1-7 with the plan auto-approved from the operator's high-level intent. Both wheels visible at every step: operator sees the result, VibeCoder sees the Atlas + Recipe Book + drift events.
**Visibility rules:**
- Operator always sees: current step, plan diff, live preview, drift events
- Operator never sees: raw LLM tool call JSON, intermediate file edits
- VibeCoder always sees: Atlas, Recipe Book, file diff, drift events, tool result errors
- VibeCoder never decides: constitutional changes (per §24.5 "constrained by constitutional truth")
---
## Summary
VibeCoder is positioned as the unified orchestrator but is operating without its primary lookup tool (App-Trace Atlas) and without the 30+ FvW v8 doctrine files in its context. The 6 repos are now all synced to GitHub, but the agent's prompts.ts and tool loop don't reference the Atlas by name. The fix is structural: deploy the Atlas + doctrine into the agent's context, then enforce a verify-after-every-change step in the tool loop. The "rushed to do work" pattern flagged by the operator on 2026-08-08 is downstream of this missing lookup — the agent improvises because it can't query.
**Recommended next step:** one Mavis session to (a) add `app-trace-atlas/atlas.json` to vibecoder-standalone, (b) extend `prompts.ts` to inject the relevant FvW v8 sections by name, (c) add a post-write verify step in the tool loop. Estimated 2-3 hours, no parallel work.