92 lines
4.5 KiB
Markdown
92 lines
4.5 KiB
Markdown
# Template snapshot — provenance and usage
|
||
|
||
This branch (`template/clean-slate`) is a curated, product-agnostic snapshot of
|
||
the Clean Architecture monorepo template — "template-vertical v2". It is a
|
||
single orphan commit with no shared history with `main`.
|
||
|
||
## Provenance
|
||
|
||
- **Source:** the Veect monorepo (local repo `Projects/Veect`), commit
|
||
`bb4a0c7219b62aefb77d3eede3d29ccedc970c97` on the platform-retrofit line
|
||
("test(web-next): boot smoke asserts auth-only bindAll").
|
||
- **Snapshot date:** 2026-07-12.
|
||
- **Why that commit:** it is the maximally generic moment of the retrofit —
|
||
demo content deleted, `auth` as the only (reference) feature, `web-next` a
|
||
clean authenticated shell, all gates green including live lint — before any
|
||
product-specific optional cores or agent-docs rewrites landed.
|
||
|
||
## What was curated out (relative to the source commit)
|
||
|
||
Product-specific material was removed; everything else is content-identical to
|
||
the source tree (the commit hook's Prettier pass normalized line-wrapping in
|
||
~96 files that predated Prettier conformance — cosmetic only, gates unaffected):
|
||
|
||
- `docs/product/` — the entire product spec bundle + reference prototypes.
|
||
- `docs/decisions/adr-027-*.md`, `adr-028-*.md`, `adr-029-*.md` — the three
|
||
product-domain ADRs (ADR-001–026, which are template-generic, remain).
|
||
- The "Veect product domain" section of `docs/glossary.md` (the rest of the
|
||
glossary is untouched).
|
||
- `docs/work/prds/platform-retrofit.prd.md`, `docs/work/prds/walking-skeleton.prd.md`
|
||
and their epics `docs/work/epics/{platform-retrofit,walking-skeleton}/`.
|
||
- `docs/work/archive/` — the source repo's archived template-era work items.
|
||
Choice: **deleted**, not kept — it was the source repo's history bookkeeping
|
||
(epic/story state for work already merged), which has no value to a project
|
||
starting fresh; the material remains in the source repo's git history.
|
||
- `docs/library-decisions/2026-07-12-zustand.md` and
|
||
`2026-07-12-@xyflow/react.md` — product-editor library traces for
|
||
dependencies that are not present in any `package.json` of this tree (they
|
||
referenced the deleted ADR-028/029).
|
||
- Product naming in the app shell (`apps/web-next/src/app/{layout,page}.tsx`
|
||
now say "Template"), the `docs/product/reference/` lint/format/coverage
|
||
excludes in `eslint.config.js`, `.prettierignore`,
|
||
`scripts/coverage/diff.mjs` (+ its test case), and the release-please
|
||
workflow comment.
|
||
- `docs/work/_system/_state.json` regenerated for the curated tree (0 epics).
|
||
|
||
The only intentional occurrence of the source product's name on this branch
|
||
is this provenance note (grep target: Veect).
|
||
|
||
## Baseline defects fixed relative to the original template
|
||
|
||
This snapshot carries repairs the original `template-vertical` shipped broken:
|
||
|
||
1. **Broken turbo lint graph** — a demo-feature dependency cycle made
|
||
`pnpm lint` unable to run across the workspace. The demo features are gone
|
||
and lint runs live across the whole graph.
|
||
2. **Missing `@vitest/coverage-v8`** — 9 packages declared coverage without
|
||
the provider devDep, so `--coverage` runs failed. Every package that runs
|
||
vitest with coverage now has the provider installed.
|
||
3. **Unparseable documented L0 invocation** — docs prescribed
|
||
`pnpm test -- --coverage`, which turbo cannot parse. The root
|
||
`test:coverage` script (`turbo run test -- --coverage`) is the supported
|
||
invocation and the docs reference it.
|
||
|
||
Also retained: calibrated per-package coverage excludes, generator anchors +
|
||
generators, the `web-next` shell + boot smoke test, and the root-only
|
||
release-please config as the template default (hybrid per-feature versioning
|
||
is a documented alternative — see ADR-021, `docs/guides/releasing.md`, and
|
||
the pre-retrofit config in the source repo's git history).
|
||
|
||
## How to start a project from this branch
|
||
|
||
```bash
|
||
# 1. Create a fresh repo from the snapshot (no template history needed):
|
||
git clone <this-repo> my-app && cd my-app
|
||
git checkout template/clean-slate
|
||
git checkout --orphan main && git commit -m "chore: init from template/clean-slate"
|
||
|
||
# 2. Bootstrap:
|
||
pnpm install # installs + wires husky pre-commit hooks
|
||
pnpm dev # boots in dev-seed mode (no Postgres needed)
|
||
|
||
# 3. Verify the gates:
|
||
pnpm typecheck && pnpm lint && pnpm test && pnpm conformance
|
||
|
||
# 4. Rename the root package (optional) and add your first feature:
|
||
pnpm turbo gen feature <name>
|
||
```
|
||
|
||
Read `docs/guides/runbook.md` first; `CLAUDE.md` is the conventions
|
||
reference. The `auth` package is the reference feature — study it, don't
|
||
delete it until you have a second feature to learn from.
|