Initial commit

2026-07-12 08:15:46 +00:00
commit ee0fec0691
1397 changed files with 127242 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,114 @@
+# 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-...
+```
+
+**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:
+
+```bash
+# (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:
+
+```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.