sandcastle (mattpocock) — Workflow and Phases
No Prescribed Workflow
sandcastle is an orchestration SDK, not a workflow framework. It ships no built-in phases, no approval gates, and no prescribed feature-development lifecycle. The user designs their own workflow in run.ts.
Default Single-Run Pattern
run() called
→ create git worktree
→ start sandbox (Docker/Podman/Vercel)
→ invoke agent with promptFile
→ agent loops up to maxIterations
→ extract structured output (optional)
→ merge branch to HEAD (if merge-to-head strategy)
→ clean up worktree + container
Suggested Multi-Phase Pattern (from examples/docs)
1. Init Phase
sandcastle init
# Creates .sandcastle/ with template files
# User edits implement-prompt.md, plan-prompt.md, etc.
2. Plan Phase
User writes run.ts:
const planResult = await run({
agent: claudeCode("claude-opus-4-7"),
sandbox: docker(),
promptFile: ".sandcastle/plan-prompt.md",
output: { tags: ["plan"] },
});
const tasks = JSON.parse(planResult.structured.plan).tasks;
3. Parallel Implement Phase
await Promise.allSettled(
tasks.map(task => run({
agent: claudeCode("claude-opus-4-7"),
sandbox: docker(),
maxParallel: 4,
promptFile: ".sandcastle/implement-prompt.md",
prompt: `Task: ${task.description}`,
maxIterations: 10,
}))
);
4. Review Phase (optional)
await run({
agent: claudeCode("claude-opus-4-7"),
sandbox: docker(),
promptFile: ".sandcastle/review-prompt.md",
});
5. Merge Phase
Automatic when branchStrategy: "merge-to-head" — no explicit phase needed.
No Approval Gates
sandcastle has no built-in human-in-the-loop checkpoints. Any approval gates must be implemented by the user in run.ts (e.g., using @clack/prompts to pause and ask for confirmation between phases).
No State Machine
No .sandcastle/state/ directory, no phase tracking, no resumable execution. Each run() is independent — if a run fails, the user re-runs from where their run.ts left off (or implements their own checkpointing).
Sandbox Lifecycle per Phase
Each phase gets its own sandbox (container/VM):
- Containers are created fresh for each
run() call
- Host git worktree is the handoff mechanism between phases
- If phase N commits to branch X, phase N+1 can read branch X from within its own sandbox
CI/CD Integration Pattern
The typical production pattern is CI-triggered:
# .github/workflows/sandcastle.yml
- run: npx tsx .sandcastle/run.ts
The user's run.ts orchestrates the full multi-phase pipeline as a single Node.js script.
Interactive Mode
For development/exploration:
sandcastle interactive
# REPL-style agent session with @clack/prompts TUI
# Not part of CI — for human-driven exploration
No Spec-Driven Development
sandcastle has no spec file format, no requirements-first gate, and no design approval step. It is purely an execution and isolation primitive. The user decides what the agent works on via promptFile content.