# 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](https://github.com/mattpocock/sandcastle) is the orchestration substrate; `pnpm work dispatch` is the entry point. See [ADR-019](./docs/decisions/adr-019-sandcastle-for-agent-orchestration.md) for the decision rationale and [`docs/guides/runbook.md`](./docs/guides/runbook.md) for end-to-end usage.

## Start here

Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) — day-1 onboarding (prerequisites, env vars, daily commands, troubleshooting, **Using Sandcastle for agent dispatch**).

## Quick reference

```bash
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 <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:

```bash
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`](./docs/architecture/template-tiers.md) for the full tier list.