fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests 1 Actions 4 Packages Projects Releases Wiki Activity

docs: surface sandcastle image-build step (one-time setup)

Browse Source 
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>
This commit is contained in:
Danijel Martinek
2026-05-13 17:51:30 +02:00
parent 014578c9a8
commit cd0a332443
4 changed files with 81 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/guides/runbook.md
View File

@@ -242,12 +242,28 @@ For the full design see `docs/architecture/agent-first-workflow-and-conformance.
### Prerequisites
1. **Docker running** — sandcastle uses Docker for the sandbox by default. `docker info` should succeed.
2. **Authentication — pick ONE:**
2. **Sandcastle image built (one-time)** — sandcastle dispatches into a tagged Docker image; you build it once per clone:
```bash
pnpm exec sandcastle docker build-image
# Tags as: sandcastle:template-vertical (derived from root package.json name)
```
If you see `Image 'sandcastle:template-vertical' not found locally. Build it first with 'sandcastle docker build-image'` on dispatch, this step was skipped.
To rebuild after editing `.sandcastle/Dockerfile`:
```bash
pnpm exec sandcastle docker remove-image
pnpm exec sandcastle docker build-image
```
3. **Authentication — pick ONE:**
- **Recommended: Claude Pro / Max subscription.** Run `claude login` once on the host. Sandcastle's sandbox bind-mounts your `~/.claude/` into the container so the Claude Code CLI inside the sandbox uses your subscription session. Zero per-task token spend for subscribers.
- **Alternative: API key.** Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in your environment. Falls back automatically when `~/.claude/` is absent.
- **Override the creds path** via `SANDCASTLE_CLAUDE_CREDS_DIR` if your Claude Code config lives somewhere non-standard.
3. **GitHub token** (optional) — `GITHUB_TOKEN` if you want the orchestrator to create PRs.
4. **`.sandcastle/` config present** — already in tree:
4. **GitHub token** (optional) — `GITHUB_TOKEN` if you want the orchestrator to create PRs.
5. **`.sandcastle/` config present** — already in tree:
- `Dockerfile` — node:22 + pnpm + Claude Code CLI; reads creds from `~/.claude/` inside the container
- `prd-eliciter.prompt.md`, `adr-eliciter.prompt.md`, `decomposer.prompt.md`, `implementer.prompt.md`, `reviewer.prompt.md` — the five role prompts