Danijel Martinek
f4254aae48
Adds the day-to-day cookbook for the 4-layer coverage architecture
(ADR-020) and threads it into the discovery path:
docs/guides/coverage.md (new):
- 4 layers at a glance + when each fires
- Single-source-of-truth pattern (feature.manifest.ts coverage:
section) and the three readers (vitest, assertFeatureConformance,
coverage:diff)
- Daily workflow: pnpm test --coverage -> aggregate -> diff
- How to read a failure (stderr human + stdout JSON examples)
- How to fix uncovered slices (TDD walkthrough)
- The full allowlist (test files, configs, docs, scripts, dev
tooling, per-feature excludes)
- Adjusting bands (manifest-first, when to override vitest)
- CI behavior (two workflows: validate + coverage-snapshot)
- Reading the committed trend via git log -- coverage/summary.json
- Mutation testing primer (L3, opt-in, scope, lands in next story)
- Troubleshooting
CLAUDE.md Read First gets the new guide pinned between audit and
template-tiers, with the L0-L3 layer summary inline so agents see the
shape at a glance.
Feature generator updates (turbo/generators/templates/feature/):
- feature.manifest.ts.hbs: new `coverage:` block at <gen:coverage>
anchor scaffolded with the documented defaults + mutationTargets
- vitest.config.ts.hbs: now uses vitestThresholdsFromBands(
DEFAULT_COVERAGE_BANDS) instead of the duplicated literal — new
features ship conformance-compliant by default
Next features generated via `pnpm turbo gen feature` are coverage-
aware from the first commit: bands declared in manifest, vitest
config consumes the helper, no duplication to drift.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Clean Architecture Monorepo Template
Turborepo + pnpm monorepo organised by vertical features, with an agent-first workflow and five conformance gates.
This template is built for agent-driven development. Sandcastle is the orchestration substrate; pnpm work dispatch is the entry point. See ADR-019 for the decision rationale and docs/guides/runbook.md for end-to-end usage.
Start here
Read docs/guides/runbook.md — day-1 onboarding (prerequisites, env vars, daily commands, troubleshooting, Using Sandcastle for agent dispatch).
Quick reference
pnpm install # Install + auto-wire husky pre-commit hooks
pnpm dev # All dev servers (web-next:3000, cms:3001, web-tanstack:3002, storybook:6006)
pnpm test # All tests
pnpm typecheck # TypeScript across all packages
pnpm lint # ESLint (incl. 8 conformance/* rules)
pnpm conformance # Cross-feature event closure
pnpm fallow # Whole-codebase: dead exports, dupes, complexity
pnpm turbo boundaries # Workspace dependency graph
pnpm work status # docs/work/ epic + story state
docker compose up -d # Start PostgreSQL
Documentation map
docs/guides/runbook.md— start hereCLAUDE.md— full conventions referenceAGENTS.md— package map + boundary rulesdocs/guides/conformance-quickref.md— manifest + 5-gate daily referencedocs/architecture/agent-first-workflow-and-conformance.md— full designdocs/architecture/feature-conformance-explainer.html— interactive explainer
Scaffolding
pnpm turbo gen feature <name> # Scaffold a feature (manifest + contracts + tests)
pnpm turbo gen event # Event contract or handler (requires gen core-package events)
pnpm turbo gen job # Background job
pnpm turbo gen realtime # Realtime channel (requires gen core-package realtime)
pnpm turbo gen core-package <name> # Optional core: events / realtime / trpc / ui / audit
pnpm turbo gen core-ui-component <name> # Atomic-design component
Generator-first is non-negotiable — hand-rolled feature/event/job/realtime/component code is rejected by reviewer agents and may fail the CI scaffold-drift check.
Optional packages
Five core packages scaffold on demand:
pnpm turbo gen core-package realtime # Socket.IO realtime layer (ADR-016)
pnpm turbo gen core-package events # Cross-feature events + Payload jobs (ADR-015)
pnpm turbo gen core-package trpc # tRPC server setup
pnpm turbo gen core-package ui # Design system
pnpm turbo gen core-package audit # DPA-compliant audit logging (ADR-018)
See docs/architecture/template-tiers.md for the full tier list.