Danijel Martinek
3f0d60e082
Captures the decision to adopt @ai-hero/sandcastle as the orchestration substrate for agent-driven development in this template. Records the 8-point decision (workspace dep, .sandcastle/ prompts, Dockerfile, dispatch.mjs orchestrator, planning vs execute modes, generator-first reviewer check, bring-your-own-key, per-task max-attempts), the four alternatives considered (bare CLI / Copilot Workspace / custom-from- scratch / no orchestrator), and four trade-offs (external dep, token cost, Docker dependency, manual state mutation in v1). Surfaces the decision at the top of README.md and AGENTS.md so new contributors see the agent-driven framing before they hit the package map or daily commands.
61 lines
3.2 KiB
Markdown
61 lines
3.2 KiB
Markdown
# 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> # 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
|
|
|
|
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.
|