Danijel Martinek
cd0a332443
Closes the gap the user hit running `pnpm work decompose --execute`: sandcastle errored with `Image 'sandcastle:template-vertical' not found locally. Build it first with 'sandcastle docker build-image'`, but neither the README nor the runbook documented this step. README.md: new "Sandcastle setup (one-time)" section after Quick reference. Three commands (docker info, build-image, auth) — the minimum needed to make dispatch work. Links to the runbook for the full lifecycle. docs/guides/runbook.md: Prerequisites in "Using Sandcastle" grow from 4 to 5 items. New step 2 walks through `sandcastle docker build-image`, quotes the exact "Image not found locally" error so agents searching for the string land on the fix, and shows the remove-image + rebuild flow for Dockerfile edits. .sandcastle/README.md: new "Build the sandbox image (one-time)" section parallel to the env section, cross-linking to the runbook. scripts/work/decompose.mjs + scripts/work/dispatch.mjs: when the sandcastle error message matches the "Image '.+' not found locally" pattern, the dispatcher now prints the build-image command inline above the generic "See runbook" line. The error stack itself remains unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
98 lines
4.6 KiB
Markdown
98 lines
4.6 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
|
|
```
|
|
|
|
## Sandcastle setup (one-time)
|
|
|
|
Required only if you'll use `pnpm work dispatch --execute` or `pnpm work decompose <id> --execute` (agent dispatch). The dispatch loop runs the implementer / reviewer / decomposer agents inside an isolated Docker sandbox; the image is built once locally.
|
|
|
|
```bash
|
|
# 1. Ensure Docker is running
|
|
docker info >/dev/null
|
|
|
|
# 2. Build the sandcastle image (reads .sandcastle/Dockerfile)
|
|
pnpm exec sandcastle docker build-image
|
|
# Tags as: sandcastle:template-vertical (derived from the root package.json name)
|
|
|
|
# 3. Pick ONE auth path:
|
|
# (a) Recommended — Claude Pro/Max subscription:
|
|
claude login # one-time; ~/.claude/ becomes the auth source
|
|
# (b) Fallback — API key:
|
|
export ANTHROPIC_API_KEY=sk-ant-...
|
|
```
|
|
|
|
After the image exists, dispatch flows work without further setup:
|
|
|
|
```bash
|
|
pnpm work dispatch # print plan (safe anywhere)
|
|
pnpm work dispatch --execute # actually dispatch via sandcastle
|
|
pnpm work decompose <prd-id> # print decompose plan
|
|
pnpm work decompose <prd-id> --execute # decompose an approved PRD
|
|
```
|
|
|
|
To rebuild the image after changing `.sandcastle/Dockerfile`:
|
|
|
|
```bash
|
|
pnpm exec sandcastle docker remove-image
|
|
pnpm exec sandcastle docker build-image
|
|
```
|
|
|
|
See [`docs/guides/runbook.md` → Using Sandcastle](./docs/guides/runbook.md#using-sandcastle-for-agent-dispatch) for the full dispatch lifecycle, auth modes, and troubleshooting.
|
|
|
|
## 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.
|