fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: README + CLAUDE.md + .env.example + quickref reflect latest gates

Browse Source
This commit is contained in:
Danijel Martinek
2026-05-13 09:05:10 +02:00
parent 05ebbb4719
commit 88edde342e
3 changed files with 116 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
.env.example
View File

@@ -1,9 +1,60 @@
# Database # =============================================================================
# Environment variables — copy this file to .env and fill in your values.
# See docs/guides/runbook.md for the full reference.
# =============================================================================
# --- Required for `pnpm dev` ---
# Postgres connection. Matches `docker compose up -d` default.
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/template DATABASE_URL=postgresql://postgres:postgres@localhost:5433/template
# Payload CMS # Payload CMS encryption key. Any random 32+ char string in dev.
PAYLOAD_SECRET=your-secret-here PAYLOAD_SECRET=replace-with-a-random-32-char-string
# --- Optional: app URLs (defaults work in dev) ---
# App URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000 NEXT_PUBLIC_APP_URL=http://localhost:3000
CMS_URL=http://localhost:3001 CMS_URL=http://localhost:3001
# Force dev-seed binders (mock repos) regardless of NODE_ENV. Useful for
# running pnpm dev without Payload booted.
# USE_DEV_SEED=true
# --- Optional: Sentry observability ---
# Leaving these unset → instrumentation falls back to the no-op tracer/logger.
# Set the DSN for any app you want OTel + Sentry on.
# WEB_NEXT_SENTRY_DSN=
# NEXT_PUBLIC_WEB_NEXT_SENTRY_DSN=
# CMS_SENTRY_DSN=
# WEB_TANSTACK_SENTRY_DSN=
# VITE_WEB_TANSTACK_SENTRY_DSN=
# Source-map upload at build time (production only).
# SENTRY_AUTH_TOKEN=
# SENTRY_ORG=
# SENTRY_PROJECT_WEB_NEXT=
# SENTRY_PROJECT_CMS=
# SENTRY_PROJECT_WEB_TANSTACK=
# OTel trace sample rate (0.0 = none, 1.0 = all). 0.1 recommended in dev.
# SENTRY_TRACES_SAMPLE_RATE=0.1
# SENTRY_ENVIRONMENT=development
# --- Optional: git commit SHA for releases ---
# VERCEL_GIT_COMMIT_SHA=
# NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA=
# VITE_GIT_COMMIT_SHA=
# --- Optional: core-audit (only when `gen core-package audit` is scaffolded) ---
# Salt for GDPR pseudonymisation. PRODUCTION MUST set this to a stable secret.
# AUDIT_PSEUDONYM_SALT=
# --- Optional: sandcastle dispatch (only when running `pnpm work dispatch --execute`) ---
# ANTHROPIC_API_KEY=
# OPENAI_API_KEY=
# GITHUB_TOKEN=
# SANDCASTLE_PROVIDER=docker

34
CLAUDE.md
View File

@@ -3,20 +3,30 @@
## Quick Start ## Quick Start
```bash ```bash
pnpm install # Install all dependencies pnpm install # Install + auto-wire husky pre-commit hooks
pnpm dev # Start all dev servers pnpm dev # Start all dev servers
pnpm build # Build all packages pnpm build # Build all packages
pnpm test # Run all tests pnpm test # Run all tests
pnpm turbo boundaries # Validate workspace dependency graph pnpm typecheck # TypeScript across all packages
pnpm turbo gen feature # Scaffold a new feature package (see docs/guides/scaffolding-a-feature.md) pnpm lint # ESLint (incl. 8 conformance/* rules)
pnpm turbo gen event # Scaffold an event contract (publish) or handler (consume) pnpm conformance # Cross-feature event closure
pnpm turbo gen job # Scaffold a background job pnpm fallow # Whole-codebase: dead exports, dupes, complexity
pnpm turbo gen realtime # Scaffold a realtime channel or inbound handler pnpm fallow:audit # AI-change audit (run before commits)
pnpm turbo gen core-package # Scaffold an optional core package (see docs/scaffolding/core-package-generator.md) pnpm turbo boundaries # Workspace dependency graph
pnpm turbo gen core-ui-component # Scaffold a core-ui atomic-design component (see docs/scaffolding/core-ui-component-generator.md) pnpm work status # docs/work/ epic + story state
docker compose up -d # Start PostgreSQL pnpm work next # Next ready story
pnpm work dispatch # Print next dispatch plan (use --execute to invoke sandcastle)
pnpm turbo gen feature # Scaffold a new feature package
pnpm turbo gen event # Scaffold an event contract or handler
pnpm turbo gen job # Scaffold a background job
pnpm turbo gen realtime # Scaffold a realtime channel or handler
pnpm turbo gen core-package # Scaffold an optional core package
pnpm turbo gen core-ui-component # Scaffold an atomic-design component
docker compose up -d # Start PostgreSQL
``` ```
**First time?** Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) end-to-end.
## TDD ## TDD
```bash ```bash

59
README.md
View File

@@ -1,22 +1,51 @@
# Clean Architecture Monorepo Template # Clean Architecture Monorepo Template
Turborepo + pnpm monorepo organized by vertical features. See `CLAUDE.md` for the full conventions reference and `AGENTS.md` for the package map. Turborepo + pnpm monorepo organised by vertical features, with an **agent-first workflow** and **five conformance gates**.
## Quick Start ## Start here
Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) — day-1 onboarding (prerequisites, env vars, daily commands, troubleshooting).
## Quick reference
```bash ```bash
pnpm install # Install all dependencies pnpm install # Install + auto-wire husky pre-commit hooks
pnpm dev # Start all dev servers pnpm dev # All dev servers (web-next:3000, cms:3001, web-tanstack:3002, storybook:6006)
pnpm build # Build all packages pnpm test # All tests
pnpm test # Run all tests pnpm typecheck # TypeScript across all packages
pnpm turbo boundaries # Validate workspace dependency graph pnpm lint # ESLint (incl. 8 conformance/* rules)
pnpm turbo gen feature # Scaffold a new feature package 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 docker compose up -d # Start PostgreSQL
``` ```
## Documentation map
- **[`docs/guides/runbook.md`](./docs/guides/runbook.md)** — start here
- **[`CLAUDE.md`](./CLAUDE.md)** — full conventions reference
- **[`AGENTS.md`](./AGENTS.md)** — package map + boundary rules
- **[`docs/guides/conformance-quickref.md`](./docs/guides/conformance-quickref.md)** — manifest + 5-gate daily reference
- **[`docs/architecture/agent-first-workflow-and-conformance.md`](./docs/architecture/agent-first-workflow-and-conformance.md)** — full design
- **[`docs/architecture/feature-conformance-explainer.html`](./docs/architecture/feature-conformance-explainer.html)** — interactive explainer
## Scaffolding
```bash
pnpm turbo gen feature <name> # Lazar-conformant 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 ## Optional packages
The default template includes the must-have core packages and all 5 feature packages. Five core packages are optional and scaffold on demand: Five core packages scaffold on demand:
```bash ```bash
pnpm turbo gen core-package realtime # Socket.IO realtime layer (ADR-016) pnpm turbo gen core-package realtime # Socket.IO realtime layer (ADR-016)
@@ -26,14 +55,4 @@ pnpm turbo gen core-package ui # Design system
pnpm turbo gen core-package audit # DPA-compliant audit logging (ADR-018) pnpm turbo gen core-package audit # DPA-compliant audit logging (ADR-018)
``` ```
See `docs/architecture/template-tiers.md` for the full tier list. See [`docs/architecture/template-tiers.md`](./docs/architecture/template-tiers.md) for the full tier list.
## Key ports
| Service | Port |
|---|---|
| Next.js | 3000 |
| Payload CMS | 3001 |
| TanStack Start | 3002 |
| PostgreSQL | 5432 |
| Storybook | 6006 |