From 7fc4c2303676d1391d82a8ae5ec5d7cb9b861f29 Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Wed, 13 May 2026 08:10:04 +0200
Subject: [PATCH] feat(sandcastle): scaffold .sandcastle/ + README + env
 example

---
 .sandcastle/.env.example | 11 +++++++++++
 .sandcastle/.gitignore   |  3 +++
 .sandcastle/README.md    | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 .sandcastle/.env.example
 create mode 100644 .sandcastle/.gitignore
 create mode 100644 .sandcastle/README.md

diff --git a/.sandcastle/.env.example b/.sandcastle/.env.example
new file mode 100644
index 0000000..ed27fb0
--- /dev/null
+++ b/.sandcastle/.env.example
@@ -0,0 +1,11 @@
+# Anthropic Claude API
+ANTHROPIC_API_KEY=
+
+# OpenAI / Codex
+OPENAI_API_KEY=
+
+# GitHub (for PR creation by the orchestrator)
+GITHUB_TOKEN=
+
+# Sandcastle's own configuration — sandbox provider (docker | podman | vercel | custom)
+SANDCASTLE_PROVIDER=docker
diff --git a/.sandcastle/.gitignore b/.sandcastle/.gitignore
new file mode 100644
index 0000000..44da1e7
--- /dev/null
+++ b/.sandcastle/.gitignore
@@ -0,0 +1,3 @@
+.env
+*.log
+.cache/
diff --git a/.sandcastle/README.md b/.sandcastle/README.md
new file mode 100644
index 0000000..a4ca239
--- /dev/null
+++ b/.sandcastle/README.md
@@ -0,0 +1,37 @@
+# .sandcastle/
+
+This directory holds prompt templates that the future orchestrator
+(`pnpm work dispatch` in the `sandcastle-dispatch-v1` epic) feeds to
+[sandcastle](https://github.com/mattpocock/sandcastle) when dispatching
+agents.
+
+## Prompt templates
+
+| File                     | Role                                      | Variables                           |
+| ------------------------ | ----------------------------------------- | ----------------------------------- |
+| `prd-eliciter.prompt.md` | Interview a human to produce a PRD draft  | `{{INITIAL_BRIEF}}`                 |
+| `adr-eliciter.prompt.md` | Interview a human to produce an ADR draft | `{{INITIAL_PROPOSAL}}`              |
+| `decomposer.prompt.md`   | Turn a PRD into epic + story files        | `{{PRD_FILE_CONTENT}}`              |
+| `implementer.prompt.md`  | Execute a single task                     | `{{TASK_FILE_CONTENT}}`             |
+| `reviewer.prompt.md`     | Review the implementer's diff             | `{{TASK_FILE_CONTENT}}`, `{{DIFF}}` |
+
+## Convention: every prompt enforces "generators first"
+
+Each prompt template starts with the same non-negotiable rule: **the agent
+must prefer `pnpm turbo gen <kind>` over hand-rolled scaffolding.** This
+applies to feature packages, events, jobs, realtime channels, optional
+core packages, and atomic-design components. Hand-rolled code is only
+acceptable when the generator's output doesn't cover the case — and even
+then, the agent runs the generator first and modifies its output rather
+than starting from scratch.
+
+## Environment
+
+Configure runtime tokens via `.env` (gitignored). Copy `.env.example`
+and fill values for the providers you use.
+
+## Manual usage
+
+Until the orchestrator ships, these templates are usable manually: copy
+the relevant `.prompt.md` content into a Claude / Codex / other agent
+session, fill the `{{VARIABLE}}` placeholders by hand, and run.