Danijel Martinek
cd0a332443
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>
58 lines
2.5 KiB
Markdown
58 lines
2.5 KiB
Markdown
# .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.
|