Sandcastle

Hand a batch of tickets to Sandcastle's sandboxed agents and let them work AFK. Each run is a lane: its own worktree, its own branch, its own run config naming exactly its tickets — so concurrent lanes never interact and nothing ever queries a shared pool. The loop implements then reviews one ticket per iteration, folds each onto the lane branch, runs until dry (an iteration lands no commits), and ends with a PR agent that gates the branch and opens the lane's PR.

Sandcastle (@ai-hero/sandcastle) orchestrates coding-agent CLIs inside Docker sandboxes, driven from a repo's tracked .sandcastle/ template. Prereqs: Docker running, plus tokens for the agent (CLAUDE_CODE_OAUTH_TOKEN) and GitHub (GH_TOKEN).

1. Define the lane

The batch is whatever work list you were handed — usually the ticket numbers a /to-tickets run just published (they are already in the conversation), but any tracker query result or literal list works. Read references/ticket-sources.md for how your source expresses tickets in the run config, its commit trailer, and its mark-done action. Name the lane: branch sandcastle/<batch-slug>, worktree ../<repo>-<batch-slug>.

Done when you can enumerate the batch exactly — ids in hand, nothing left implied by a label or query that another session could grow.

2. Wire the lane

• git worktree add -b <branch> ../<repo>-<batch-slug> <base>

• Repo has no .sandcastle/ template yet: scaffold with npx sandcastle init (check --help; pick sequential-reviewer), then adapt: main.mts reads the run config and passes the batch in via promptArgs, ends with the PR phase and a process.exit(0); mount ~/.claude/skills read-only so in-sandbox agents can run /implement, /tdd, /code-review; pin the docker imageName (the default derives from the directory name and breaks in a worktree); persist the package-manager store across runs — and anchor every runtime dir you add (pnpm-store/, patches/, plus run.json) in the root gitignore, since re-init regenerates the nested one.

• In the worktree, write the untracked .sandcastle/run.json:

  { "branch": "sandcastle/<batch-slug>", "base": "main",
    "tickets": [292, 293], "notes": "sandbox has no browser/emulator — verify via unit/jsdom tests" }

  cap is optional and defaults to tickets + 1 — pure dry-stop headroom, so a lane always ends dry, never at a cap. notes reaches the implement prompt verbatim.

• .sandcastle/.env is per-working-dir (untracked, never travels with a branch) — copy the agent token in, refresh GH_TOKEN=$(gh auth token). Seed the package-manager store warm from another worktree's store dir (cp -Rc), then install.

Done when the run config echoes exactly the step-1 batch and the resolved ticket list prints their full bodies.

3. Launch

Show the lane in the same message that launches it — tickets, branch, base, cap, model — then start the orchestrator (pnpm sandcastle, or npx tsx .sandcastle/main.mts) in the background. Config is read once at launch: a wrong cap or list means relaunch, never an edit under a live run.

Done when the loop is running and iteration 1 shows in .sandcastle/logs/.