# How to Use the Parallel-Planner and Parallel-Planner-With-Review Templates in Sandcastle

> Learn to use Sandcastle's parallel-planner and parallel-planner-with-review templates for parallel GitHub issue code management. Orchestrate plan, implement, review, and merge workflows.

- Repository: [Matt Pocock/sandcastle](https://github.com/mattpocock/sandcastle)
- Tags: how-to-guide
- Published: 2026-05-24

---

**The parallel-planner and parallel-planner-with-review templates provide three-phase and four-phase orchestration workflows that let Claude agents plan, implement, review, and merge code changes across multiple GitHub issues in parallel.**

These high-level orchestration templates in the `mattpocock/sandcastle` repository enable LLM-driven agents to process backlog items concurrently using Docker sandboxes. Both templates automate the creation of implementation branches, code generation, and final merging while handling dependency resolution between issues.

## Understanding the Parallel-Planner Templates

### The parallel-planner Template (Three-Phase)

The **parallel-planner** template orchestrates a **Plan → Execute → Merge** workflow. According to the source code in `src/templates/parallel-planner/main.mts`, this template:

- Uses a **planner** (Claude Opus) to read open issues and build a dependency graph
- Returns a `<plan>` JSON block describing unblocked issues and target branches
- Spawns one **implementer** (Claude Sonnet) per issue inside isolated Docker sandboxes via `docker()`
- Allows each implementer to iterate up to 100 times to write code and tests
- Employs a single **merger** (Claude Sonnet) to combine branches and close issues

### The parallel-planner-with-review Template (Four-Phase)

The **parallel-planner-with-review** template extends the workflow to **Plan → Execute + Review → Merge** as implemented in `src/templates/parallel-planner-with-review/main.mts`. The key differences include:

- An additional **reviewer** agent (Claude Sonnet) runs **in the same sandbox** immediately after the implementer
- The reviewer enforces coding standards (e.g., [`CODING-STANDARDS.md`](https://github.com/mattpocock/sandcastle/blob/main/CODING-STANDARDS.md)) before the merge phase
- Both implementer and reviewer commits are merged together before the final merge phase

## Core Source Files and Architecture

Both templates share a common configuration structure but operate from different entry points:

| File | Purpose |
|------|---------|
| `src/templates/parallel-planner/main.mts` | Orchestrates the three-phase loop (plan, execute, merge) |
| `src/templates/parallel-planner-with-review/main.mts` | Orchestrates the four-phase loop with integrated review |
| [`.sandcastle/plan-prompt.md`](https://github.com/mattpocock/sandcastle/blob/main/.sandcastle/plan-prompt.md) | Prompt instructing the planner to output `<plan>` JSON |
| [`.sandcastle/implement-prompt.md`](https://github.com/mattpocock/sandcastle/blob/main/.sandcastle/implement-prompt.md) | Prompt driving the implementer agent with `{{TASK_ID}}` and `{{ISSUE_TITLE}}` placeholders |
| [`.sandcastle/review-prompt.md`](https://github.com/mattpocock/sandcastle/blob/main/.sandcastle/review-prompt.md) | Prompt used by the reviewer agent (review template only) |
| [`.sandcastle/merge-prompt.md`](https://github.com/mattpocock/sandcastle/blob/main/.sandcastle/merge-prompt.md) | Prompt instructing the merger how to combine branches using `{{CLOSE_TASK_COMMAND}}` |

## How the Workflows Execute

### Phase 1: Planning

The planner runs with `maxIterations: 1` using the prompt at [`.sandcastle/plan-prompt.md`](https://github.com/mattpocock/sandcastle/blob/main/.sandcastle/plan-prompt.md). It emits a JSON structure:

```json
{
  "issues": [
    {
      "id": "123",
      "title": "Add cache layer",
      "branch": "sandcastle/issue-123-add-cache"
    },
    {
      "id": "124",
      "title": "Fix login bug",
      "branch": "sandcastle/issue-124-fix-login"
    }
  ]
}

```

The orchestrator parses this JSON (lines 69-80 in `parallel-planner/main.mts`) to identify which issues are unblocked and ready for parallel processing.

### Phase 2: Execution

For each issue, the implementer agent runs inside its own sandbox branch via `docker()`. The `promptArgs` object substitutes placeholders like `{{TASK_ID}}`, `{{ISSUE_TITLE}}`, and `{{BRANCH}}` into [`implement-prompt.md`](https://github.com/mattpocock/sandcastle/blob/main/implement-prompt.md). Each agent may iterate up to 100 times to write code, run tests, and commit changes.

### Phase 3: Review (parallel-planner-with-review only)

In the four-phase template, after the implementer produces commits, a reviewer runs **in the same sandbox** on the same branch (reusing the sandbox created via `createSandbox()`). The reviewer applies code-review standards from the project's standards file and returns additional commits. The two runs are merged together before proceeding.

### Phase 4: Merge

A single merger agent receives a markdown list of successful branches (`BRANCHES`) and issue identifiers (`ISSUES`). It merges all branches, resolves conflicts, runs the test suite, and closes the corresponding issues using the command specified by `{{CLOSE_TASK_COMMAND}}`.

## Configuration and Sandboxing

Both templates share a common configuration block in their respective `main.mts` files:

```ts
const hooks = {
  sandbox: {
    onSandboxReady: [{ command: "npm install" }]
  }
};
const copyToWorktree = ["node_modules"];

```

- **Hooks** run before each agent iteration, guaranteeing fresh dependencies in every sandbox
- **copyToWorktree** speeds up sandbox startup by copying the host's `node_modules` into the worktree rather than reinstalling

## Getting Started: Setup and Execution

### Scaffold a New Project

Initialize a project with the three-phase planner:

```bash
npx sandcastle init --template parallel-planner

```

Or use the four-phase version with review:

```bash
npx sandcastle init --template parallel-planner-with-review

```

These commands create a `.sandcastle` directory containing the prompt markdown files and a starter `main.mts` orchestrator.

### Run the Orchestrator

Execute the three-phase workflow:

```bash
npx tsx .sandcastle/main.mts

```

Add this to your [`package.json`](https://github.com/mattpocock/sandcastle/blob/main/package.json) scripts for convenience:

```json
{
  "scripts": {
    "sandcastle": "npx tsx .sandcastle/main.mts"
  }
}

```

When running the parallel-planner-with-review template, the output shows the additional review step:

```

... implementer produced commits, running reviewer ...
... reviewer completed, merging results ...

```

### Customize the Planning Criteria

Edit [`.sandcastle/plan-prompt.md`](https://github.com/mattpocock/sandcastle/blob/main/.sandcastle/plan-prompt.md) to change filtering criteria, such as modifying the GitHub label from `ready-for-agent` to `sandcastle`. The orchestrator automatically picks up changes on the next run without requiring code modifications.

### Limit Concurrency (Advanced)

Both templates use `Promise.allSettled` without a semaphore, meaning every issue runs concurrently. To cap concurrency, modify the `issues.map` section in `main.mts` to wrap each run in a limiting helper like `p-limit`. This change is localized to the template file and does not affect the core Sandcastle engine.

## Summary

- **parallel-planner** provides a three-phase workflow (plan, execute, merge) for parallel issue resolution
- **parallel-planner-with-review** adds a fourth review phase where Claude Sonnet validates code in the same sandbox before merging
- Configuration lives in `main.mts` while LLM behavior is controlled via `.sandcastle` markdown prompts
- The planner emits JSON plans parsed at lines 69-80 of the template source, determining which issues to process in parallel
- Implementers run in Docker sandboxes with `maxIterations: 100`, while the planner uses `maxIterations: 1`
- Both templates support hooks and `copyToWorktree` for dependency management and performance optimization

## Frequently Asked Questions

### What is the difference between the parallel-planner and parallel-planner-with-review templates?

The **parallel-planner** template runs three phases: planning, execution, and merging. The **parallel-planner-with-review** template adds a fourth phase where a reviewer agent examines the implementer's work in the same sandbox before merging. This review phase enforces coding standards and can produce additional commits to improve code quality.

### How do I customize which GitHub issues the planner selects?

Edit the [`.sandcastle/plan-prompt.md`](https://github.com/mattpocock/sandcastle/blob/main/.sandcastle/plan-prompt.md) file to modify the selection criteria. The default prompt asks the planner to filter by labels like `ready-for-agent`, but you can change this to any label or criteria specific to your workflow. The orchestrator reads this prompt file dynamically, so changes take effect immediately on the next run without rebuilding.

### Why does the implementer iterate up to 100 times while the planner only iterates once?

The planner performs a single-pass analysis (`maxIterations: 1`) to generate the dependency graph and issue plan, as planning requires a complete view of the backlog before execution begins. The implementer receives `maxIterations: 100` to allow iterative debugging, test running, and code refinement until the task is complete or the iteration limit is reached.

### Can I run these templates without Docker?

No, both templates rely on the `docker()` function to create isolated sandboxes for each implementer. The `hooks` configuration with `onSandboxReady` commands and the `copyToWorktree` optimization specifically target Docker-based sandboxes. Running without Docker would require modifying the core orchestration logic in `main.mts` to use a different sandbox provider.