agentic-dev/TEMPLATE.md

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

# 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.