agentic-dev/docs/work/prds/platform-retrofit.prd.md

---
id: platform-retrofit
title: Platform retrofit — repurpose template-vertical as the Veect monorepo
type: prd
status: approved
author: Danijel Martinek
elicitation-session: session_016j8z4VHjedXDTjEDNg7qHK
created: 2026-07-12T09:05:00Z
---

## Problem

This repo is the `template-vertical` starter: five demo content features (auth, blog, media, marketing-pages, navigation), three frontend apps, and a work tree full of shipped template epics. We are building **Veect** in it — a hosted design-to-code SaaS (ADR-027) — and almost none of the demo *content* is Veect, while almost all of the *machinery* (conformance, coverage, generators, work pipeline, DI/testing conventions, compliance and instrumentation cores) is exactly what Veect needs.

Three concrete pains today:

1. **Dispatch agents cannot read the product spec.** The entire Veect specification bundle sits untracked in `.proto/` (plus a stray `veect-product-docs.zip` at root). Sandcastle implementers run in git worktrees, which contain only committed files — every PRD referencing the spec would be unreadable to the agents implementing it.
2. **The repo actively misleads.** `pnpm work status` surfaces eight shipped template epics; CLAUDE.md/AGENTS.md describe a blog/CMS starter; release-please tracks five demo features that are about to be deleted. Agent context assembled from this repo points at the wrong product.
3. **Demo content blocks the package map.** The Veect features (workspaces, projects, design-doc, discovery, ai — per the 2026-07-12 grill decisions) can't land cleanly while blog/media/navigation/marketing-pages occupy the workspace, the router/CMS composition, and the versioning config.

## Goal

The repo is a clean, truthful Veect monorepo: only Veect-relevant packages, the product docs committed and authoritative, the work pipeline showing only Veect work — with every conformance gate still green.

## In scope

- Delete demo features `blog`, `media`, `navigation`, `marketing-pages` and app `web-tanstack`, including all composition wiring (core-api router, core-cms collections, web-next pages/imports, bindAll dispatcher, seeds, e2e specs, Storybook references).
- Reduce `apps/web-next` to a compiling shell: auth (sign-in/out) + a placeholder home. `apps/cms` stays (Payload admin over the remaining collections). `apps/storybook` stays.
- Keep and leave wired: `auth` feature, `core-audit`, `core-analytics`, `core-consent`, `core-dsr`, OTel/Sentry instrumentation (ADR-027 §6 flips the spec's "no telemetry" stance).
- Scaffold `core-events` and `core-realtime` via `pnpm turbo gen core-package` (needed by the walking skeleton for runner status events/pushes).
- Migrate `.proto/veect-product-docs/` → `docs/product/` (committed); migrate the design references (`Veect.dc.html`, `Veect Landing.dc.html`, `Weave backup`, `veect-codebase/` prototype, upload PNGs) → `docs/product/reference/` (committed, read-only reference — the prototype codebase is **never** vendored into `packages/`, per ADR-029). Delete `veect-product-docs.zip` and the emptied `.proto/`.
- Amend the committed product README's authority table with the ADR-027/028/029 supersessions and the `Veect.dc.html` ground-truth row (ADR-029 §5).
- Archive the eight shipped template epics and their nine PRDs to `docs/work/archive/`; rebuild `_state.json` so `pnpm work status` shows only Veect work.
- Rewrite `release-please-config.json` + manifest to track the **root only** (single product version; hosted SaaS deploys continuously — per-feature versions return only if an npm distribution ships).
- Rewrite CLAUDE.md and AGENTS.md project-overview sections for Veect (control-plane/runner vocabulary, new package map, ADR-027/028/029 references); fix the "15 conformance rules" → sixteen miscount.
- Library-trace batch (`/evaluate-library`, ADR-022) for the feature-tier runtime deps the next PRD needs: `@xyflow/react`, `zustand` (v5). (Runner-side deps like execa/vite/react-docgen-typescript live in the app-tier `apps/runner` and are exempt from ADR-022; traces for them are optional hardening.)
- Verify the ESLint/turbo boundary configs and generators survive the deletions (generators are template-driven, not dependent on the deleted features).

## Out of scope

- Any new Veect feature code (walking-skeleton PRD and successors).
- The landing page (arrives with the `polish-playground-landing` PRD; this PRD deletes `marketing-pages` and leaves no marketing surface).
- Generator retargeting beyond what deletions force — the feature generator's Payload+tRPC shape is **correct** for Veect's control plane (ADR-027 §5) and stays as-is.
- Runner infrastructure, Docker images, fixtures (walking-skeleton PRD).
- Billing, GitHub App, self-host distribution (all deferred per ADR-027).

## Constraints

- ADR-027 (hosted SaaS + runner split), ADR-028 (iframe canvas), ADR-029 (DesignDoc v1 + editor rebuild) are the decision baseline; this PRD implements their repo-level consequences only.
- ADR-021 (release-please) — the versioning rewrite must keep Conventional-Commit → release automation working; ADR-022 (library traces) — pre-commit hook must pass on every slice.
- Conformance rules stay enforced throughout: every deletion slice leaves `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit` green — no "big bang broken middle".
- The `auth` feature's manifest, tests, and coverage bands must remain intact (it is load-bearing for Veect accounts, ADR-027 §4).
- Deletions must not orphan `docs/glossary.md` terms — the template terms describing deleted features get pruned in the same slice that deletes the feature.

## Success criteria

- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow && pnpm coverage:diff` all green on the final commit.
- `pnpm dev` boots web-next (dev-seed mode, no Payload required) with sign-in working and no imports from deleted features anywhere (`pnpm turbo boundaries` clean).
- `git ls-files docs/product/` shows the full committed spec bundle; `.proto/` and `veect-product-docs.zip` are gone.
- `pnpm work status` lists zero template epics; archived work remains greppable under `docs/work/archive/`.
- `release-please-config.json` validates and tracks only the root package.
- `docs/library-decisions/` contains approved traces for `@xyflow/react` and `zustand`.
- CLAUDE.md/AGENTS.md describe Veect (spot check: no mention of blog/media/marketing-pages as live features).

## User stories

1. As an AI implementer dispatched into a worktree, I want the product spec committed under `docs/product/`, so that I can read the authoritative requirements without host-machine access.
2. As the founder, I want `pnpm work status` to show only Veect work, so that dispatch context and prioritization aren't polluted by shipped template epics.
3. As an AI decomposer, I want CLAUDE.md/AGENTS.md/glossary to describe the Veect architecture, so that generated epics use the right vocabulary and package map.
4. As a developer, I want the repo to typecheck/test green with only auth + core packages, so that Veect features land on a stable floor.
5. As a release engineer, I want release-please to track a single product version, so that merges to main produce one meaningful release PR instead of five demo-feature bumps.
6. As an AI implementer, I want library traces for the editor's runtime deps pre-approved, so that walking-skeleton tasks don't stall on the library-policy pre-commit hook.
7. As a future contributor, I want the prototype codebase and HTML prototypes committed as reference material with a stated authority order, so that design questions have a canonical source (ADR-029 §5).

## Implementation decisions

- **Deletion order is dependency-order:** apps first (`web-tanstack`), then features (`blog`, `media`, `marketing-pages`, `navigation`), pruning each feature's wiring (core-api router anchor, core-cms collection anchor, bindAll entry, web-next UI imports, seeds, e2e) in the same slice as the package deletion. Each deletion is one slice/commit.
- **`web-next` shell:** keep the auth UI surfaces and app bootstrap (`bindAll()`, instrumentation); replace the home page with a minimal authenticated placeholder (the workspaces UI arrives in the next PRD).
- **`docs/product/` layout:** spec docs at top level (filenames preserved from the bundle); `reference/` subfolder for HTML prototypes + prototype codebase + PNGs. The prototype codebase's `package.json` stays outside pnpm workspace globs (`packages/*`, `apps/*`) by construction; add it to fallow/lint ignore lists so whole-codebase auditors skip reference material.
- **Authority amendment:** a short "Repo supersessions" section prepended to `docs/product/README.md` linking ADR-027/028/029 and adding the `Veect.dc.html` row to the authority table.
- **Work archive:** `docs/work/archive/{epics,prds}/` with a one-line README; `pnpm work rebuild-state` regenerates `_state.json`. Verify the work CLI ignores the archive path (adjust its glob if not).
- **release-please:** root-only config; `include-component-in-tag` dropped (single `v*` tags); pre-1.0 bump policy retained.
- **Optional cores:** `core-events` + `core-realtime` scaffolded by generator with their pre-shipped traces (ADR-022 "pre-shipped trace" mechanism); no consumers wired yet beyond compile-green.
- **Glossary:** Veect domain section already exists (added 2026-07-12); prune `blog`/`media`/`marketing-pages`/`navigation` mentions from the Packages section as those features are deleted; `auth` stays.
- No Payload schema changes; no new collections (those come with `workspaces` in the next PRD).

## Testing decisions

- This PRD is mostly subtractive: the test suite itself is the safety net — every slice must keep the full gate set green, and deleting a feature deletes its tests in the same slice.
- `auth` keeps its full test suite + coverage bands untouched (regression canary for the surviving floor).
- Add one boot smoke assertion (dev-seed): `bindAll()` resolves with only auth bound — proves no dangling DI symbols from deleted features (mirror the existing boot-assertion pattern in web-next's server bootstrap tests).
- Scaffolded `core-events`/`core-realtime` ship with their generator-emitted test suites; no additional coverage required until consumers exist.
- e2e: prune deleted-feature Playwright specs; keep an auth sign-in spec green as the surviving e2e baseline.

## Open questions

- Q1: Do the HTML prototypes (~640 KB total) go into git as-is or via LFS? — **As-is**; they're text, they diff, and the repo has no LFS setup to maintain.
- Q2: Should `navigation` survive temporarily as a generator reference? — **No**; the generators are template-driven (`turbo/generators/templates/`), not derived from live features. Delete all four content features.
- Q3: Keep `sentry-pii-guard.yml` CI? — **Yes**; ADR-027 keeps the Sentry/OTel stack, so the PII guard remains meaningful.

## Out of scope (deferred)

- Retargeting generator templates toward runner-side patterns (revisit after the first runner feature ships — rule-of-three).
- Security FAQ / trust documentation for design partners (needed before outreach, not before code — founder-owned, tracked in `docs/product/founder-os-audit.md`).
- npm `veect` name registration and related legal items (founder-owned).

## Further notes

- Builds on: ADR-027, ADR-028, ADR-029; the 2026-07-12 grill session decision log (13 decisions).
- Blocks: `walking-skeleton` (next PRD) — that PRD assumes the clean floor this one produces.
- The `.proto` bundle's own README §3 lists what the prototype seeds; ADR-029 supersedes its "codebase seeds packages/editor" instruction — reference-only now.