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

## Build the sandbox image (one-time)

Sandcastle dispatches into a Docker image tagged `sandcastle:<root-package-name>`.
Build it once per clone before `pnpm work dispatch --execute` or
`pnpm work decompose <id> --execute` will work:

```bash
pnpm exec sandcastle docker build-image
# Tags: sandcastle:template-vertical
```

Rebuild after editing this `Dockerfile`:

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

See [`docs/guides/runbook.md` → Using Sandcastle → Prerequisites](../docs/guides/runbook.md#using-sandcastle-for-agent-dispatch) for the full setup.

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