284 lines
15 KiB
Markdown
284 lines
15 KiB
Markdown
# Developer Runbook
|
||
|
||
You just cloned this repo. This is the only doc you need to read end-to-end. Everything else is reference.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
| Tool | Version | Why |
|
||
| ------- | ------- | ------------------------------------- |
|
||
| Node.js | 22+ | Runtime for all apps + scripts |
|
||
| pnpm | 9+ | Package manager (workspace-aware) |
|
||
| Docker | 24+ | Local Postgres + sandcastle sandboxes |
|
||
| Git | 2.40+ | Version control + worktrees |
|
||
|
||
Recommended editor: VS Code or Cursor with the official TypeScript, ESLint, and Prettier extensions.
|
||
|
||
---
|
||
|
||
## First-time setup
|
||
|
||
```bash
|
||
# 1. Clone + install
|
||
git clone <repo-url> template-vertical
|
||
cd template-vertical
|
||
pnpm install
|
||
|
||
# 2. Start Postgres (background)
|
||
docker compose up -d
|
||
|
||
# 3. Copy env template and fill in secrets
|
||
cp .env.example .env
|
||
# Edit .env (see "Environment variables" section below for what each one does)
|
||
|
||
# 4. Verify the gate stack is green
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm lint
|
||
pnpm conformance
|
||
pnpm fallow
|
||
pnpm turbo boundaries
|
||
```
|
||
|
||
All six should exit 0. If any fails on a fresh clone, file an issue — the main branch is supposed to stay green.
|
||
|
||
```bash
|
||
# 5. Start the dev servers
|
||
pnpm dev
|
||
```
|
||
|
||
This runs Next.js (3000), Payload CMS (3001), TanStack Start (3002), and Storybook (6006) in parallel. The `bindAll()` dispatcher in each app picks the dev-seed binders by default (mock repositories, no Payload connection needed beyond Postgres).
|
||
|
||
---
|
||
|
||
## Daily commands
|
||
|
||
```bash
|
||
# Development
|
||
pnpm dev # all dev servers
|
||
pnpm dev --filter @repo/web-next # one app
|
||
|
||
# Tests
|
||
pnpm test # everything
|
||
pnpm test --filter @repo/auth # one package
|
||
pnpm test:e2e # Playwright e2e
|
||
pnpm test:stories # Storybook smoke tests
|
||
pnpm test:visual # visual regression (Playwright screenshots)
|
||
|
||
# Linting + type checking
|
||
pnpm typecheck # tsc across all packages
|
||
pnpm lint # ESLint across all packages
|
||
pnpm format # Prettier write
|
||
pnpm format:check # Prettier check (CI mode)
|
||
|
||
# Conformance gates
|
||
pnpm conformance # cross-feature event closure
|
||
pnpm fallow # whole-codebase: dead exports, dupes, complexity
|
||
pnpm fallow:audit # AI-change audit (run before commits)
|
||
|
||
# Boundary validation
|
||
pnpm turbo boundaries # workspace dependency graph
|
||
|
||
# Work system
|
||
pnpm work status # tree of epics + stories
|
||
pnpm work next # next ready story
|
||
pnpm work ready # all ready stories
|
||
pnpm work blocked # blocked stories + what they wait on
|
||
pnpm work rebuild-state # regenerate docs/work/_state.json
|
||
pnpm work dispatch # print next dispatch plan
|
||
pnpm work dispatch --execute # invoke sandcastle (requires ANTHROPIC_API_KEY)
|
||
```
|
||
|
||
---
|
||
|
||
## Environment variables
|
||
|
||
Copy `.env.example` to `.env` and fill what you need. NOT every variable is required for `pnpm dev` — defaults are dev-friendly.
|
||
|
||
### Required for `pnpm dev`
|
||
|
||
| Var | Example | Why |
|
||
| ---------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
|
||
| `DATABASE_URL` | `postgresql://postgres:postgres@localhost:5433/template` | Postgres connection (docker compose default) |
|
||
| `PAYLOAD_SECRET` | `your-secret-here` | Payload CMS encryption key (any random 32+ char string in dev) |
|
||
|
||
### Optional — app URLs (defaults work in dev)
|
||
|
||
| Var | Default | Why |
|
||
| --------------------- | ----------------------- | ------------------------------------------------------ |
|
||
| `NEXT_PUBLIC_APP_URL` | `http://localhost:3000` | Public-facing web-next URL |
|
||
| `CMS_URL` | `http://localhost:3001` | Payload CMS URL |
|
||
| `USE_DEV_SEED` | `true` in dev | Force dev-seed binders (mock repos) instead of Payload |
|
||
| `NODE_ENV` | inherited | `production` flips bind dispatcher to real Payload |
|
||
|
||
### Optional — Sentry observability (no DSN = no-op tracer/logger)
|
||
|
||
| Var | Why |
|
||
| ----------------------------------------------------- | ------------------------------------------------- |
|
||
| `WEB_NEXT_SENTRY_DSN` | Server-side OTel + Sentry for web-next |
|
||
| `NEXT_PUBLIC_WEB_NEXT_SENTRY_DSN` | Browser Sentry for web-next |
|
||
| `CMS_SENTRY_DSN` | Server-side for Payload CMS |
|
||
| `WEB_TANSTACK_SENTRY_DSN` | Server-side for TanStack Start |
|
||
| `VITE_WEB_TANSTACK_SENTRY_DSN` | Browser-side for TanStack Start |
|
||
| `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT_*` | Source-map upload at build time |
|
||
| `SENTRY_TRACES_SAMPLE_RATE` | OTel trace sample rate (`0.1` recommended in dev) |
|
||
| `SENTRY_ENVIRONMENT` | `development` / `staging` / `production` |
|
||
|
||
### Optional — Git commit SHA for releases
|
||
|
||
| Var | Why |
|
||
| ------------------------------------------------------------------------------------- | --------------------------------------------------- |
|
||
| `VERCEL_GIT_COMMIT_SHA` / `VITE_GIT_COMMIT_SHA` / `NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA` | Surfaces commit SHA in Sentry releases + UI footers |
|
||
|
||
### Optional — core-audit (only when `gen core-package audit` is scaffolded)
|
||
|
||
| Var | Why |
|
||
| ---------------------- | -------------------------------------------------------------------------------------------------- |
|
||
| `AUDIT_PSEUDONYM_SALT` | Salt for the audit log's GDPR-erasure pseudonymisation (production only — must be a stable secret) |
|
||
|
||
### Optional — sandcastle dispatch (only when running `pnpm work dispatch --execute`)
|
||
|
||
| Var | Why |
|
||
| --------------------- | ------------------------------------------------- |
|
||
| `ANTHROPIC_API_KEY` | Claude API key (sandcastle's default agent) |
|
||
| `OPENAI_API_KEY` | OpenAI/Codex alternative |
|
||
| `GITHUB_TOKEN` | GitHub access for PR creation by the orchestrator |
|
||
| `SANDCASTLE_PROVIDER` | `docker` (default) / `podman` / `vercel` |
|
||
|
||
---
|
||
|
||
## The agent-first workflow
|
||
|
||
This template enforces a **manifest-first, generator-driven, gate-protected** workflow.
|
||
|
||
### When adding a new feature
|
||
|
||
```bash
|
||
pnpm turbo gen feature <name>
|
||
```
|
||
|
||
This emits:
|
||
|
||
- `packages/<name>/src/feature.manifest.ts` — the conformance manifest (use cases, audits, publishes, consumes)
|
||
- `packages/<name>/src/di/bind-production.ts` with `assertFeatureConformance(...)` at the tail (refuses to boot on drift)
|
||
- Mock repository, factory, seed, entity, use-case, controller, tests — full Lazar-conformant shape
|
||
- `packages/<name>/src/index.ts` exports
|
||
|
||
After scaffolding, the four-step ordering for any new use case:
|
||
|
||
1. **Manifest entry** — declare the use case in `feature.manifest.ts`
|
||
2. **Contracts** — export `xInputSchema`, `xOutputSchema`, `IXUseCase` (factory body throws `not implemented`)
|
||
3. **Tests (red)** — write the failing test
|
||
4. **Implementation (green)** — fill the factory body
|
||
|
||
The five conformance gates catch drift at every step. See `docs/guides/conformance-quickref.md` for the manifest field reference.
|
||
|
||
### When adding cross-feature primitives
|
||
|
||
```bash
|
||
pnpm turbo gen event # event contract or handler (needs gen core-package events)
|
||
pnpm turbo gen job # background job
|
||
pnpm turbo gen realtime # realtime channel or handler (needs gen core-package realtime)
|
||
pnpm turbo gen core-package <x> # optional core package (events/realtime/trpc/ui/audit)
|
||
pnpm turbo gen core-ui-component <x> # atomic-design component (needs gen core-package ui)
|
||
```
|
||
|
||
**Always prefer generators over hand-rolling.** The generators emit the canonical shape; hand-rolled code drifts from generator output and breaks the CI scaffold-drift check.
|
||
|
||
### Tracking work
|
||
|
||
The repo uses `docs/work/` for epic/story/task tracking:
|
||
|
||
```
|
||
docs/work/
|
||
├── README.md
|
||
├── _state.json # derived, regenerated by pre-commit hook
|
||
├── prds/ # PRDs go here
|
||
├── _templates/ # markdown templates
|
||
└── <epic-slug>/
|
||
├── _epic.md
|
||
└── <story-slug>/
|
||
└── _story.md # contains the Tasks checklist
|
||
```
|
||
|
||
Use `pnpm work next` to see what's ready. Use `pnpm work dispatch` to plan the next sandcastle dispatch.
|
||
|
||
---
|
||
|
||
## The five conformance gates
|
||
|
||
| Gate | Latency | What it catches | Runs when |
|
||
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------ | --------------------- |
|
||
| TypeScript brands | 0s | forgotten `withSpan` / `withCapture` / `withAudit`; manifest ↔ binding-slot type mismatch | on save (IDE) |
|
||
| ESLint (8 conformance/\* rules) | <1s | manifest ↔ code drift; missing sibling test; missing manifest; atomic-tier import direction | on save / `pnpm lint` |
|
||
| Boot assertion | ~3s | runtime binding without required brand; manifest edited without rebinder | `pnpm dev` startup |
|
||
| `pnpm conformance` | ~120s | orphan event consumers across features | CI |
|
||
| `pnpm fallow` | ~30–60s | dead exports / unused files; duplicate code; circular deps; complexity hotspots; AI-change audit | CI |
|
||
|
||
For the full design see `docs/architecture/agent-first-workflow-and-conformance.md`. For the daily reference see `docs/guides/conformance-quickref.md`.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
**`pnpm dev` refuses to boot with `ConformanceError`**
|
||
— A feature's binding lost a required brand. The error message tells you which use case + which brand. Re-bind through `withSpan` / `withCapture` / `withAudit` as needed.
|
||
|
||
**`pnpm lint` errors with `conformance/feature-must-have-manifest`**
|
||
— You created a feature with use cases but no `feature.manifest.ts`. Run `pnpm turbo gen feature <name>` to scaffold the canonical shape, or hand-write the manifest at `packages/<feature>/src/feature.manifest.ts`.
|
||
|
||
**`pnpm conformance` says "orphan consumer"**
|
||
— A feature declares `consumes: ["X"]` but no feature publishes `X`. Either add the publish to the producing feature's manifest + factory, or remove the consumer.
|
||
|
||
**`pnpm fallow` reports new dead exports or dupes**
|
||
— Your change added unused exports or duplicated logic. Either remove the dead code or accept with `pnpm fallow:audit --gate all` (the audit considers the baseline; only NEW findings fail).
|
||
|
||
**Pre-commit hook refuses to commit with "state-sync-guard"**
|
||
— You staged `docs/work/_state.json` but it's not byte-identical to `pnpm work rebuild-state` output. Run `pnpm work rebuild-state && git add docs/work/_state.json` and try again.
|
||
|
||
**Tests fail in `@repo/turbo-generators` with Vitest worker timeouts**
|
||
— Known flaky on slow machines. Re-run; if persistent, increase the `turbo-generators` package's vitest `testTimeout`.
|
||
|
||
**`pnpm work dispatch --execute` errors with "ANTHROPIC_API_KEY required"**
|
||
— You're trying to run the sandcastle orchestrator without an agent API key. Set the env var, or run `pnpm work dispatch` (no flag) to just print the plan.
|
||
|
||
---
|
||
|
||
## Where to read next
|
||
|
||
Once you've got `pnpm dev` running:
|
||
|
||
1. **`AGENTS.md`** — package map, boundary rules, per-package conventions
|
||
2. **`CLAUDE.md`** — full convention reference (manifest-first ordering, factory patterns, instrumentation rules)
|
||
3. **`docs/guides/conformance-quickref.md`** — daily manifest + gates reference
|
||
4. **`docs/guides/tdd-workflow.md`** — red-green-refactor with the gate stack
|
||
5. **`docs/guides/scaffolding-a-feature.md`** — `pnpm turbo gen feature` reference
|
||
6. **`docs/guides/adding-a-feature.md`** — end-to-end walkthrough
|
||
7. **`docs/architecture/agent-first-workflow-and-conformance.md`** — the full design
|
||
8. **`docs/architecture/feature-conformance-explainer.html`** — interactive explainer (open in browser)
|
||
|
||
For deeper topics:
|
||
|
||
- **`docs/guides/events-and-jobs.md`** — cross-feature events (requires `gen core-package events`)
|
||
- **`docs/guides/realtime.md`** — Socket.IO channels (requires `gen core-package realtime`)
|
||
- **`docs/guides/audit-and-compliance.md`** — DPA-compliant audit logging (requires `gen core-package audit`)
|
||
- **`docs/guides/frontend-work-shape.md`** — atomic design + Storybook conventions
|
||
- **`docs/guides/infrastructure-work-shape.md`** — ADR-first flow for new infrastructure
|
||
|
||
---
|
||
|
||
## Common pitfalls
|
||
|
||
- **Skipping the generator.** Always run `pnpm turbo gen <kind>` before hand-rolling. Generators emit the canonical shape; the CI scaffold-drift check will fail on hand-rolled features.
|
||
- **Forgetting `pnpm work rebuild-state` after editing `docs/work/` markdown.** The pre-commit hook handles this automatically when you stage markdown; only matters if you push without committing.
|
||
- **Bypassing `--no-verify` on commits.** The pre-commit hook catches drift early. If it's blocking a legitimate change, fix the underlying issue, not the hook.
|
||
- **Hand-editing `_state.json`.** Don't. The state-sync-guard refuses commits that drift from rebuild output. Edit the markdown; let the rebuild script propagate.
|
||
- **Committing `.env`.** It's gitignored. Use `.env.example` for new vars.
|
||
|
||
---
|
||
|
||
For deeper philosophy: this template is built around the assumption that **AI agents will author most feature work**. The conformance system is designed as an agent feedback loop. Latency-layered gates compound: 0s + <1s + 3s + 120s + 60s. The faster the inner loop, the more iterations agents can make per task.
|
||
|
||
If you're a human contributor, the same workflow applies — the gates aren't punitive, they're navigational aids.
|