From cf8d69106ea00da5cb24ad6f245bc09ec237f902 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 13 May 2026 09:03:15 +0200 Subject: [PATCH 1/4] docs(work): scaffold docs-and-runbook-v1 epic + stories --- docs/work/_state.json | 47 +++++++++++++++++-- .../docs-and-runbook-v1/01-runbook/_story.md | 15 ++++++ .../02-doc-sweep/_story.md | 18 +++++++ docs/work/docs-and-runbook-v1/_epic.md | 20 ++++++++ 4 files changed, 97 insertions(+), 3 deletions(-) create mode 100644 docs/work/docs-and-runbook-v1/01-runbook/_story.md create mode 100644 docs/work/docs-and-runbook-v1/02-doc-sweep/_story.md create mode 100644 docs/work/docs-and-runbook-v1/_epic.md diff --git a/docs/work/_state.json b/docs/work/_state.json index a146b8f..1b3d465 100644 --- a/docs/work/_state.json +++ b/docs/work/_state.json @@ -1,5 +1,5 @@ { - "updated_at": "2026-05-13T06:55:52.068Z", + "updated_at": "2026-05-13T07:03:16.899Z", "epics": { "agent-workflow-docs-v1": { "status": "done", @@ -165,6 +165,32 @@ } } }, + "docs-and-runbook-v1": { + "status": "in-progress", + "title": "Developer runbook + post-Fallow doc sweep", + "stories": { + "01-runbook": { + "status": "in-progress", + "title": "docs/guides/runbook.md — day-1 onboarding", + "ac_total": 2, + "ac_completed": 0, + "depends_on": [], + "blocks": [ + "02-doc-sweep" + ] + }, + "02-doc-sweep": { + "status": "todo", + "title": "README + CLAUDE.md + .env.example sweep", + "ac_total": 5, + "ac_completed": 0, + "depends_on": [ + "01-runbook" + ], + "blocks": [] + } + } + }, "elicitation-prompts-v1": { "status": "done", "title": "Elicitation + dispatch prompt templates", @@ -409,6 +435,21 @@ } } }, - "ready": [], - "blocked": [] + "ready": [ + { + "epic": "docs-and-runbook-v1", + "story": "01-runbook", + "title": "docs/guides/runbook.md — day-1 onboarding" + } + ], + "blocked": [ + { + "epic": "docs-and-runbook-v1", + "story": "02-doc-sweep", + "title": "README + CLAUDE.md + .env.example sweep", + "waiting_on": [ + "docs-and-runbook-v1/01-runbook" + ] + } + ] } diff --git a/docs/work/docs-and-runbook-v1/01-runbook/_story.md b/docs/work/docs-and-runbook-v1/01-runbook/_story.md new file mode 100644 index 0000000..aeee3c9 --- /dev/null +++ b/docs/work/docs-and-runbook-v1/01-runbook/_story.md @@ -0,0 +1,15 @@ +--- +id: 01-runbook +epic: docs-and-runbook-v1 +title: docs/guides/runbook.md — day-1 onboarding +type: technical-story +status: in-progress +feature: docs +depends-on: [] +blocks: [02-doc-sweep] +--- + +## Tasks + +- [ ] Story scaffold +- [ ] Write docs/guides/runbook.md (sections: Prerequisites, First-time setup, Daily commands, Env vars, Agent-first workflow, Conformance gates reference, Troubleshooting, Where to read next) diff --git a/docs/work/docs-and-runbook-v1/02-doc-sweep/_story.md b/docs/work/docs-and-runbook-v1/02-doc-sweep/_story.md new file mode 100644 index 0000000..7010b7d --- /dev/null +++ b/docs/work/docs-and-runbook-v1/02-doc-sweep/_story.md @@ -0,0 +1,18 @@ +--- +id: 02-doc-sweep +epic: docs-and-runbook-v1 +title: README + CLAUDE.md + .env.example sweep +type: technical-story +status: todo +feature: docs +depends-on: [01-runbook] +blocks: [] +--- + +## Tasks + +- [ ] Update README.md to point at runbook + reflect 5 gates +- [ ] Expand .env.example to cover all relevant env vars with comments +- [ ] Sweep CLAUDE.md "Quick Start" for new commands (pnpm work, pnpm fallow, pnpm fallow:audit) +- [ ] Add a "Conformance gates" reference line to docs/guides/conformance-quickref.md noting Fallow is the 5th +- [ ] Final verification + closeout diff --git a/docs/work/docs-and-runbook-v1/_epic.md b/docs/work/docs-and-runbook-v1/_epic.md new file mode 100644 index 0000000..307b26f --- /dev/null +++ b/docs/work/docs-and-runbook-v1/_epic.md @@ -0,0 +1,20 @@ +--- +id: docs-and-runbook-v1 +prd: null +title: Developer runbook + post-Fallow doc sweep +type: epic +status: in-progress +features: [docs] +created: 2026-05-13 +--- + +## Goal + +Write the day-1 developer runbook + sweep top-level docs for staleness +against the now-shipped conformance-system, work-system, sandcastle, +and Fallow integration. + +## Stories + +- [ ] [01 — Developer runbook](01-runbook/_story.md) +- [ ] [02 — Doc sweep + .env.example expansion](02-doc-sweep/_story.md) From 05ebbb471920f54a286fdecdc8cbccc7da78e09b Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 13 May 2026 09:04:28 +0200 Subject: [PATCH 2/4] =?UTF-8?q?docs(guides):=20developer=20runbook=20?= =?UTF-8?q?=E2=80=94=20day-1=20onboarding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/guides/runbook.md | 283 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 docs/guides/runbook.md diff --git a/docs/guides/runbook.md b/docs/guides/runbook.md new file mode 100644 index 0000000..c4fa253 --- /dev/null +++ b/docs/guides/runbook.md @@ -0,0 +1,283 @@ +# 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 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 +``` + +This emits: + +- `packages//src/feature.manifest.ts` — the conformance manifest (use cases, audits, publishes, consumes) +- `packages//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//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 # optional core package (events/realtime/trpc/ui/audit) +pnpm turbo gen core-ui-component # 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.md + └── / + └── _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 ` to scaffold the canonical shape, or hand-write the manifest at `packages//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 ` 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. From 88edde342ee1b39d4eea1dea55c6d17460385ab4 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 13 May 2026 09:05:10 +0200 Subject: [PATCH 3/4] docs: README + CLAUDE.md + .env.example + quickref reflect latest gates --- .env.example | 59 ++++++++++++++++++++++++++++++++++++++++++++++++---- CLAUDE.md | 34 +++++++++++++++++++----------- README.md | 59 ++++++++++++++++++++++++++++++++++------------------ 3 files changed, 116 insertions(+), 36 deletions(-) diff --git a/.env.example b/.env.example index a432c9c..f088b6b 100644 --- a/.env.example +++ b/.env.example @@ -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 -# Payload CMS -PAYLOAD_SECRET=your-secret-here +# Payload CMS encryption key. Any random 32+ char string in dev. +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 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 diff --git a/CLAUDE.md b/CLAUDE.md index 6413b53..6385f7c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,20 +3,30 @@ ## Quick Start ```bash -pnpm install # Install all dependencies -pnpm dev # Start all dev servers -pnpm build # Build all packages -pnpm test # Run all tests -pnpm turbo boundaries # Validate workspace dependency graph -pnpm turbo gen feature # Scaffold a new feature package (see docs/guides/scaffolding-a-feature.md) -pnpm turbo gen event # Scaffold an event contract (publish) or handler (consume) -pnpm turbo gen job # Scaffold a background job -pnpm turbo gen realtime # Scaffold a realtime channel or inbound handler -pnpm turbo gen core-package # Scaffold an optional core package (see docs/scaffolding/core-package-generator.md) -pnpm turbo gen core-ui-component # Scaffold a core-ui atomic-design component (see docs/scaffolding/core-ui-component-generator.md) -docker compose up -d # Start PostgreSQL +pnpm install # Install + auto-wire husky pre-commit hooks +pnpm dev # Start all dev servers +pnpm build # Build all packages +pnpm test # Run 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 fallow:audit # AI-change audit (run before commits) +pnpm turbo boundaries # Workspace dependency graph +pnpm work status # docs/work/ epic + story state +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 ```bash diff --git a/README.md b/README.md index 6907290..8784754 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,51 @@ # 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 -pnpm install # Install all dependencies -pnpm dev # Start all dev servers -pnpm build # Build all packages -pnpm test # Run all tests -pnpm turbo boundaries # Validate workspace dependency graph -pnpm turbo gen feature # Scaffold a new feature package +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`](./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 # 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 # Optional core: events / realtime / trpc / ui / audit +pnpm turbo gen core-ui-component # 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 -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 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) ``` -See `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 | +See [`docs/architecture/template-tiers.md`](./docs/architecture/template-tiers.md) for the full tier list. From 244313c91485a82af3f65d5897393158def75560 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 13 May 2026 09:05:54 +0200 Subject: [PATCH 4/4] docs(work): close docs-and-runbook-v1 epic --- docs/work/_state.json | 31 +++++-------------- .../docs-and-runbook-v1/01-runbook/_story.md | 6 ++-- .../02-doc-sweep/_story.md | 12 +++---- docs/work/docs-and-runbook-v1/_epic.md | 6 ++-- 4 files changed, 20 insertions(+), 35 deletions(-) diff --git a/docs/work/_state.json b/docs/work/_state.json index 1b3d465..b2d2dfc 100644 --- a/docs/work/_state.json +++ b/docs/work/_state.json @@ -1,5 +1,5 @@ { - "updated_at": "2026-05-13T07:03:16.899Z", + "updated_at": "2026-05-13T07:05:55.913Z", "epics": { "agent-workflow-docs-v1": { "status": "done", @@ -166,24 +166,24 @@ } }, "docs-and-runbook-v1": { - "status": "in-progress", + "status": "done", "title": "Developer runbook + post-Fallow doc sweep", "stories": { "01-runbook": { - "status": "in-progress", + "status": "done", "title": "docs/guides/runbook.md — day-1 onboarding", "ac_total": 2, - "ac_completed": 0, + "ac_completed": 2, "depends_on": [], "blocks": [ "02-doc-sweep" ] }, "02-doc-sweep": { - "status": "todo", + "status": "done", "title": "README + CLAUDE.md + .env.example sweep", "ac_total": 5, - "ac_completed": 0, + "ac_completed": 5, "depends_on": [ "01-runbook" ], @@ -435,21 +435,6 @@ } } }, - "ready": [ - { - "epic": "docs-and-runbook-v1", - "story": "01-runbook", - "title": "docs/guides/runbook.md — day-1 onboarding" - } - ], - "blocked": [ - { - "epic": "docs-and-runbook-v1", - "story": "02-doc-sweep", - "title": "README + CLAUDE.md + .env.example sweep", - "waiting_on": [ - "docs-and-runbook-v1/01-runbook" - ] - } - ] + "ready": [], + "blocked": [] } diff --git a/docs/work/docs-and-runbook-v1/01-runbook/_story.md b/docs/work/docs-and-runbook-v1/01-runbook/_story.md index aeee3c9..e7bf982 100644 --- a/docs/work/docs-and-runbook-v1/01-runbook/_story.md +++ b/docs/work/docs-and-runbook-v1/01-runbook/_story.md @@ -3,7 +3,7 @@ id: 01-runbook epic: docs-and-runbook-v1 title: docs/guides/runbook.md — day-1 onboarding type: technical-story -status: in-progress +status: done feature: docs depends-on: [] blocks: [02-doc-sweep] @@ -11,5 +11,5 @@ blocks: [02-doc-sweep] ## Tasks -- [ ] Story scaffold -- [ ] Write docs/guides/runbook.md (sections: Prerequisites, First-time setup, Daily commands, Env vars, Agent-first workflow, Conformance gates reference, Troubleshooting, Where to read next) +- [x] Story scaffold +- [x] Write docs/guides/runbook.md (sections: Prerequisites, First-time setup, Daily commands, Env vars, Agent-first workflow, Conformance gates reference, Troubleshooting, Where to read next) diff --git a/docs/work/docs-and-runbook-v1/02-doc-sweep/_story.md b/docs/work/docs-and-runbook-v1/02-doc-sweep/_story.md index 7010b7d..c02fa64 100644 --- a/docs/work/docs-and-runbook-v1/02-doc-sweep/_story.md +++ b/docs/work/docs-and-runbook-v1/02-doc-sweep/_story.md @@ -3,7 +3,7 @@ id: 02-doc-sweep epic: docs-and-runbook-v1 title: README + CLAUDE.md + .env.example sweep type: technical-story -status: todo +status: done feature: docs depends-on: [01-runbook] blocks: [] @@ -11,8 +11,8 @@ blocks: [] ## Tasks -- [ ] Update README.md to point at runbook + reflect 5 gates -- [ ] Expand .env.example to cover all relevant env vars with comments -- [ ] Sweep CLAUDE.md "Quick Start" for new commands (pnpm work, pnpm fallow, pnpm fallow:audit) -- [ ] Add a "Conformance gates" reference line to docs/guides/conformance-quickref.md noting Fallow is the 5th -- [ ] Final verification + closeout +- [x] Update README.md to point at runbook + reflect 5 gates +- [x] Expand .env.example to cover all relevant env vars with comments +- [x] Sweep CLAUDE.md "Quick Start" for new commands (pnpm work, pnpm fallow, pnpm fallow:audit) +- [x] Add a "Conformance gates" reference line to docs/guides/conformance-quickref.md noting Fallow is the 5th +- [x] Final verification + closeout diff --git a/docs/work/docs-and-runbook-v1/_epic.md b/docs/work/docs-and-runbook-v1/_epic.md index 307b26f..d663f76 100644 --- a/docs/work/docs-and-runbook-v1/_epic.md +++ b/docs/work/docs-and-runbook-v1/_epic.md @@ -3,7 +3,7 @@ id: docs-and-runbook-v1 prd: null title: Developer runbook + post-Fallow doc sweep type: epic -status: in-progress +status: done features: [docs] created: 2026-05-13 --- @@ -16,5 +16,5 @@ and Fallow integration. ## Stories -- [ ] [01 — Developer runbook](01-runbook/_story.md) -- [ ] [02 — Doc sweep + .env.example expansion](02-doc-sweep/_story.md) +- [x] [01 — Developer runbook](01-runbook/_story.md) +- [x] [02 — Doc sweep + .env.example expansion](02-doc-sweep/_story.md)