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

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) 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	Prompt instructing the planner to output <plan> JSON
.sandcastle/implement-prompt.md	Prompt driving the implementer agent with {{TASK_ID}} and {{ISSUE_TITLE}} placeholders
.sandcastle/review-prompt.md	Prompt used by the reviewer agent (review template only)
.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. It emits a JSON structure:

{
  "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. 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:

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:

npx sandcastle init --template parallel-planner

Or use the four-phase version with review:

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:

npx tsx .sandcastle/main.mts

Add this to your package.json scripts for convenience:

{
  "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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}