Danijel Martinek
fd8265cd29
The user surfaced that the binder-wrap-helper epic's stories
decomposed into horizontal sub-steps (read 3 files → write helper
→ write test → export → typecheck → coverage), not vertical
slices. Per the glossary's slice = task = PR = commit rule, every
checkbox should land as one green commit.
.sandcastle/decomposer.prompt.md:
- New "The slice rule (non-negotiable)" section near the top
defining the three constraints every task must satisfy: one
green commit; exercises a layer; independently meaningful.
- New "Tasks that are FORBIDDEN" list naming the anti-patterns
the previous output exhibited (read a file as a task; write
test without impl; standalone gate runs; standalone export;
sub-step decomposition of a single slice).
- New "Tasks that are CORRECT" list with examples drawn from
this codebase (gen invocation, full use-case slice, per-feature
binder migration, audit emission, bindAll wiring).
- New paragraph on "Manifest-first ordering INSIDE a task" —
the 4-step ordering (manifest → contracts → red test → green
impl) is what the implementer does within one task, not a
multi-checkbox decomposition.
- Constraints section gains two new bullets:
* Prefer FEWER but FATTER tasks (one per vertical slice)
over MANY thinner sub-steps
* Self-check: imagine the commit each checkbox produces;
do all gates pass on that commit alone?
.sandcastle/reviewer.prompt.md:
- New check #8 "Slice discipline" rejecting:
* Multi-commit diffs where any intermediate commit has red
gates
* Sub-step shape that should have been separate tasks
* Incomplete slices (use case w/o DI binding, manifest
publish w/o publish site, controller w/o router wiring)
.gitignore: adds `.pnpm-store/` so a misconfigured pnpm install
that places the store inside the project doesn't stage thousands
of cache files.
The existing binder-wrap-helper stories were decomposed under the
old (unconstrained) prompt and need re-decomposing under the new
rule. That's a separate action — this commit fixes the prompts;
the existing epic stays as-is until you re-decompose.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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-...
macOS users: subscription auth needs an extra step. Claude Code stores credentials in the macOS Keychain by default, so the host's ~/.claude/ directory has no .credentials.json for the sandbox to read. Two workarounds:
# (preferred for macOS subscription users) extract keychain -> file once:
security find-generic-password -s "Claude Code-credentials" -a "$USER" -w \
> ~/.claude/.credentials.json
chmod 600 ~/.claude/.credentials.json
# Trade-off: credentials now live as a plaintext file at the path; refresh
# when the token expires (re-run the same one-liner). The file is in your
# home directory — chmod 600 + your home permissions are the protection.
# OR fall back to API key — no host changes needed:
export ANTHROPIC_API_KEY=sk-ant-...
Linux + WSL users with claude login write ~/.claude/.credentials.json directly; nothing extra needed.
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 hereCLAUDE.md— full conventions referenceAGENTS.md— package map + boundary rulesdocs/guides/conformance-quickref.md— manifest + 5-gate daily referencedocs/architecture/agent-first-workflow-and-conformance.md— full designdocs/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.