Files

Danijel Martinek cd0a332443 docs: surface sandcastle image-build step (one-time setup)

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>

2026-05-13 17:51:30 +02:00

4.6 KiB

Raw Blame History

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 is the orchestration substrate; pnpm work dispatch is the entry point. See ADR-019 for the decision rationale and docs/guides/runbook.md for end-to-end usage.

Start here

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

Quick reference

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.

# 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:

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:

pnpm exec sandcastle docker remove-image
pnpm exec sandcastle docker build-image

See docs/guides/runbook.md → Using Sandcastle for the full dispatch lifecycle, auth modes, and troubleshooting.

Documentation map

docs/guides/runbook.md — start here
CLAUDE.md — full conventions reference
AGENTS.md — package map + boundary rules
docs/guides/conformance-quickref.md — manifest + 5-gate daily reference
docs/architecture/agent-first-workflow-and-conformance.md — full design
docs/architecture/feature-conformance-explainer.html — interactive explainer

Scaffolding

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:

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 for the full tier list.

4.6 KiB Raw Blame History