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

id, title, type, status, author, elicitation-session, created

id	title	type	status	author	elicitation-session	created
platform-retrofit	Platform retrofit — repurpose template-vertical as the Veect monorepo	prd	approved	Danijel Martinek	session_016j8z4VHjedXDTjEDNg7qHK	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.