@rafaeltab/sandcastle 0.13.0-fork.0

package/dist/sandboxes/vercel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sandboxes/vercel.ts"],"names":["result"],"mappings":"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","file":"vercel.js","sourcesContent":["/**\n * Vercel isolated sandbox provider — wraps `@vercel/sandbox` into a SandboxProvider.\n *\n * Usage:\n *   import { vercel } from \"sandcastle/sandboxes/vercel\";\n *   await run({ agent: claudeCode(\"claude-opus-4-8\"), sandbox: vercel() });\n */\n\nimport { execSync } from \"node:child_process\";\nimport { readFile, unlink, writeFile, mkdir, stat } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join, posix } from \"node:path\";\nimport { Writable } from \"node:stream\";\nimport {\n  createIsolatedSandboxProvider,\n  type ExecResult,\n  type IsolatedSandboxHandle,\n  type IsolatedSandboxProvider,\n} from \"../SandboxProvider.js\";\nimport { BoundedTail, MAX_TAIL_CHARS } from \"../boundedTail.js\";\nimport { redirectCommandStdinFromFile, withStdinFile } from \"./stdin-file.js\";\n\n/** Worktree directory inside the Vercel sandbox's default working directory. */\nconst VERCEL_WORKTREE_DIR = \"workspace\";\n\n/**\n * Options for creating a Vercel sandbox provider.\n *\n * All `@vercel/sandbox` `Sandbox.create()` options are accepted as pass-through,\n * plus Sandcastle-specific options for auth and branch strategy.\n */\nexport interface VercelOptions {\n  /**\n   * Vercel access token.\n   *\n   * Falls back to the SDK's default auth behavior, which reads\n   * `VERCEL_OIDC_TOKEN` (recommended for Vercel-hosted environments) or\n   * `VERCEL_TOKEN` from the environment.\n   */\n  readonly token?: string;\n\n  // ---- Pass-through @vercel/sandbox Sandbox.create() options ----\n\n  /**\n   * The source of the sandbox (git repo, tarball, or snapshot).\n   * Omit to start an empty sandbox.\n   */\n  readonly source?:\n    | {\n        type: \"git\";\n        url: string;\n        depth?: number;\n        revision?: string;\n        username?: string;\n        password?: string;\n      }\n    | {\n        type: \"tarball\";\n        url: string;\n      }\n    | {\n        type: \"snapshot\";\n        snapshotId: string;\n      };\n\n  /** Array of port numbers to expose from the sandbox (up to 4). */\n  readonly ports?: number[];\n\n  /** Timeout in milliseconds before the sandbox auto-terminates. */\n  readonly timeout?: number;\n\n  /**\n   * Resources to allocate to the sandbox.\n   * Each vCPU gets 2048 MB of memory.\n   */\n  readonly resources?: {\n    vcpus: number;\n  };\n\n  /**\n   * The runtime of the sandbox (e.g. `\"node24\"`, `\"node22\"`, `\"python3.13\"`).\n   * Defaults to `\"node24\"`.\n   */\n  readonly runtime?: string;\n\n  /**\n   * Network policy for the sandbox.\n   * Defaults to full internet access if not specified.\n   */\n  readonly networkPolicy?: Record<string, unknown>;\n\n  /**\n   * Vercel project ID to associate sandbox operations with.\n   */\n  readonly projectId?: string;\n\n  /**\n   * Vercel team ID to associate sandbox operations with.\n   */\n  readonly teamId?: string;\n\n  /**\n   * Timeout in milliseconds (alias for `timeout`, kept for discoverability).\n   */\n  readonly timeoutMs?: number;\n\n  /**\n   * Sandbox template shorthand (e.g. `\"node-22\"`).\n   * Maps to the `runtime` option.\n   */\n  readonly template?: string;\n\n  /** Environment variables injected by this provider. Merged at launch time with env resolver and agent provider env. */\n  readonly env?: Record<string, string>;\n\n  /**\n   * Maximum number of characters of streamed `exec` output retained per stream\n   * (stdout and stderr) when an `onLine` callback is supplied (default: 64KiB).\n   *\n   * Output is delivered live to `onLine` regardless; this only bounds the tail\n   * returned in `ExecResult`, preventing a long-running agent's output from\n   * overflowing V8's max string length and crashing the run.\n   */\n  readonly maxOutputTailChars?: number;\n}\n\n/**\n * Create a Vercel isolated sandbox provider.\n *\n * The returned provider creates Vercel Firecracker microVM sandboxes via\n * the `@vercel/sandbox` SDK. Each sandbox is ephemeral — one sandbox per run.\n *\n * Requires `@vercel/sandbox` to be installed as a peer dependency.\n */\nexport const vercel = (options?: VercelOptions): IsolatedSandboxProvider =>\n  createIsolatedSandboxProvider({\n    name: \"vercel\",\n    env: options?.env,\n    create: async (createOptions): Promise<IsolatedSandboxHandle> => {\n      const maxOutputTailChars = options?.maxOutputTailChars ?? MAX_TAIL_CHARS;\n      // Dynamic import so the peer dependency is only loaded at runtime\n      const { Sandbox } = await import(\"@vercel/sandbox\");\n\n      const createParams: Record<string, unknown> = {};\n\n      // Pass through SDK options\n      if (options?.source) createParams.source = options.source;\n      if (options?.ports) createParams.ports = options.ports;\n      if (options?.resources) createParams.resources = options.resources;\n      if (options?.networkPolicy)\n        createParams.networkPolicy = options.networkPolicy;\n      // runtime takes precedence over the template convenience alias\n      const resolvedRuntime = options?.runtime ?? options?.template;\n      if (resolvedRuntime) createParams.runtime = resolvedRuntime;\n\n      // Timeout: prefer explicit timeout, fall back to timeoutMs alias\n      const timeoutValue = options?.timeout ?? options?.timeoutMs;\n      if (timeoutValue !== undefined) createParams.timeout = timeoutValue;\n\n      // Merge provider env with Sandcastle env\n      createParams.env = createOptions.env;\n\n      // Auth: pass token and team/project IDs if provided\n      if (options?.token) createParams.token = options.token;\n      if (options?.projectId) createParams.projectId = options.projectId;\n      if (options?.teamId) createParams.teamId = options.teamId;\n\n      const sandbox = await Sandbox.create(\n        createParams as Parameters<typeof Sandbox.create>[0],\n      );\n\n      let worktreePath: string;\n      try {\n        // Vercel SDK 2.x starts in /vercel/sandbox, while 3.x starts in\n        // /vercel. Discover the default rather than depending on image layout.\n        const pwdResult = await sandbox.runCommand({ cmd: \"pwd\" });\n        const defaultCwd = (await pwdResult.stdout()).trim();\n        if (pwdResult.exitCode !== 0 || !posix.isAbsolute(defaultCwd)) {\n          const stderr = await pwdResult.stderr();\n          throw new Error(\n            `Could not determine Vercel sandbox working directory: ${stderr || defaultCwd}`,\n          );\n        }\n\n        worktreePath = posix.join(defaultCwd, VERCEL_WORKTREE_DIR);\n        const mkdirResult = await sandbox.runCommand({\n          cmd: \"mkdir\",\n          args: [\"-p\", worktreePath],\n        });\n        if (mkdirResult.exitCode !== 0) {\n          throw new Error(\n            `Could not create Vercel sandbox worktree directory: ${await mkdirResult.stderr()}`,\n          );\n        }\n      } catch (error) {\n        await sandbox.stop().catch(() => {});\n        throw error;\n      }\n\n      const handle: IsolatedSandboxHandle = {\n        worktreePath,\n\n        exec: async (\n          command: string,\n          opts?: {\n            onLine?: (line: string) => void;\n            cwd?: string;\n            sudo?: boolean;\n            stdin?: string;\n          },\n        ): Promise<ExecResult> => {\n          const stdin = opts?.stdin;\n\n          return withStdinFile(\n            stdin,\n            {\n              upload: (path, content) =>\n                sandbox.writeFiles([{ path, content }]),\n              remove: async (path) => {\n                await sandbox.runCommand({\n                  cmd: \"rm\",\n                  args: [\"-f\", \"--\", path],\n                });\n              },\n            },\n            async (stdinPath) => {\n              const commandToRun = stdinPath\n                ? redirectCommandStdinFromFile(command, stdinPath)\n                : command;\n\n              if (opts?.onLine) {\n                const onLine = opts.onLine;\n                const stdoutTail = new BoundedTail(maxOutputTailChars, \"\\n\");\n                const stderrTail = new BoundedTail(maxOutputTailChars, \"\");\n                let partial = \"\";\n\n                const stdoutWritable = new Writable({\n                  write(chunk, _encoding, callback) {\n                    const text = partial + chunk.toString();\n                    const lines = text.split(\"\\n\");\n                    partial = lines.pop() ?? \"\";\n                    for (const line of lines) {\n                      stdoutTail.push(line);\n                      onLine(line);\n                    }\n                    callback();\n                  },\n                  final(callback) {\n                    if (partial) {\n                      stdoutTail.push(partial);\n                      onLine(partial);\n                      partial = \"\";\n                    }\n                    callback();\n                  },\n                });\n\n                const stderrWritable = new Writable({\n                  write(chunk, _encoding, callback) {\n                    stderrTail.push(chunk.toString());\n                    callback();\n                  },\n                });\n\n                const result = await sandbox.runCommand({\n                  cmd: \"sh\",\n                  args: [\"-c\", commandToRun],\n                  cwd: opts?.cwd ?? worktreePath,\n                  stdout: stdoutWritable,\n                  stderr: stderrWritable,\n                  ...(opts?.sudo ? { sudo: true } : {}),\n                });\n\n                return {\n                  stdout: stdoutTail.toString(),\n                  stderr: stderrTail.toString(),\n                  exitCode: result.exitCode,\n                };\n              }\n\n              const result = await sandbox.runCommand({\n                cmd: \"sh\",\n                args: [\"-c\", commandToRun],\n                cwd: opts?.cwd ?? worktreePath,\n                ...(opts?.sudo ? { sudo: true } : {}),\n              });\n\n              const stdout = await result.stdout();\n              const stderr = await result.stderr();\n\n              return {\n                stdout,\n                stderr,\n                exitCode: result.exitCode,\n              };\n            },\n          );\n        },\n\n        copyIn: async (\n          hostPath: string,\n          sandboxPath: string,\n        ): Promise<void> => {\n          const info = await stat(hostPath);\n          if (info.isDirectory()) {\n            const tarPath = join(\n              tmpdir(),\n              `sandcastle-copyin-${Date.now()}.tar.gz`,\n            );\n            execSync(`tar -czf \"${tarPath}\" -C \"${hostPath}\" .`);\n            try {\n              const tarContent = await readFile(tarPath);\n              const sandboxTarPath = `/tmp/sandcastle-copyin-${Date.now()}.tar.gz`;\n              await sandbox.writeFiles([\n                { path: sandboxTarPath, content: tarContent },\n              ]);\n              await sandbox.runCommand({\n                cmd: \"sh\",\n                args: [\n                  \"-c\",\n                  `mkdir -p \"${sandboxPath}\" && tar -xzf \"${sandboxTarPath}\" -C \"${sandboxPath}\" && rm -f \"${sandboxTarPath}\"`,\n                ],\n              });\n            } finally {\n              await unlink(tarPath).catch(() => {});\n            }\n          } else {\n            const content = await readFile(hostPath);\n            await sandbox.writeFiles([{ path: sandboxPath, content }]);\n          }\n        },\n\n        copyFileOut: async (\n          sandboxPath: string,\n          hostPath: string,\n        ): Promise<void> => {\n          const buffer = await sandbox.readFileToBuffer({\n            path: sandboxPath,\n          });\n          if (!buffer) {\n            throw new Error(`File not found in Vercel sandbox: ${sandboxPath}`);\n          }\n          await mkdir(dirname(hostPath), { recursive: true });\n          await writeFile(hostPath, buffer);\n        },\n\n        close: async (): Promise<void> => {\n          await sandbox.stop();\n        },\n      };\n\n      return handle;\n    },\n  });\n"]}

package/dist/templates/blank/main.mts

@@ -0,0 +1,12 @@
+import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+
+// Blank template: customize this to build your own orchestration.
+// Run this with: npx tsx .sandcastle/main.mts
+// Or add to package.json scripts: "sandcastle": "npx tsx .sandcastle/main.mts"
+
+await run({
+  agent: claudeCode("claude-opus-4-8"),
+  sandbox: docker(),
+  promptFile: "./.sandcastle/prompt.md",
+});

package/dist/templates/blank/prompt.md

@@ -0,0 +1,12 @@
+# Context
+
+<!-- Use !`command` to pull in dynamic context. Commands run inside the sandbox. -->
+<!-- Example: !`git log --oneline -10` or !`{{LIST_TASKS_COMMAND}}` -->
+
+# Task
+
+<!-- Describe what the agent should do. -->
+
+# Done
+
+<!-- When the task is complete, output <promise>COMPLETE</promise> to signal early termination. -->

package/dist/templates/blank/template.json

@@ -0,0 +1,4 @@
+{
+  "name": "blank",
+  "description": "Bare scaffold — write your own prompt and orchestration"
+}

package/dist/templates/parallel-planner/implement-prompt.md

@@ -0,0 +1,62 @@
+# TASK
+
+Fix issue {{TASK_ID}}: {{ISSUE_TITLE}}
+
+Pull in the issue using `{{VIEW_TASK_COMMAND}}`. If it has a parent PRD, pull that in too.
+
+Only work on the issue specified.
+
+Work on branch {{BRANCH}}. Make commits and run tests.
+
+# CONTEXT
+
+Here are the last 10 commits:
+
+<recent-commits>
+
+!`git log -n 10 --format="%H%n%ad%n%B---" --date=short`
+
+</recent-commits>
+
+# EXPLORATION
+
+Explore the repo and fill your context window with relevant information that will allow you to complete the task.
+
+Pay extra attention to test files that touch the relevant parts of the code.
+
+# EXECUTION
+
+If applicable, use RGR to complete the task.
+
+1. RED: write one test
+2. GREEN: write the implementation to pass that test
+3. REPEAT until done
+4. REFACTOR the code
+
+# FEEDBACK LOOPS
+
+Before committing, run `npm run typecheck` and `npm run test` to ensure the tests pass.
+
+# COMMIT
+
+Make a git commit. The commit message must:
+
+1. Start with `RALPH:` prefix
+2. Include task completed + PRD reference
+3. Key decisions made
+4. Files changed
+5. Blockers or notes for next iteration
+
+Keep it concise.
+
+# THE ISSUE
+
+If the task is not complete, leave a comment on the issue with what was done.
+
+Do not close the issue - this will be done later.
+
+Once complete, output <promise>COMPLETE</promise>.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.

package/dist/templates/parallel-planner/main.mts

@@ -0,0 +1,204 @@
+// Parallel Planner — three-phase orchestration loop
+//
+// This template drives a multi-phase workflow:
+//   Phase 1 (Plan):    An opus agent analyzes open issues, builds a dependency
+//                      graph, and outputs a <plan> JSON listing unblocked issues
+//                      with their target branch names.
+//   Phase 2 (Execute): N sonnet agents run in parallel via Promise.allSettled,
+//                      each working a single issue on its own branch.
+//   Phase 3 (Merge):   A sonnet agent merges all branches that produced commits.
+//
+// The outer loop repeats up to MAX_ITERATIONS times so that newly unblocked
+// issues are picked up after each round of merges.
+//
+// Usage:
+//   npx tsx .sandcastle/main.mts
+// Or add to package.json:
+//   "scripts": { "sandcastle": "npx tsx .sandcastle/main.mts" }
+
+import * as sandcastle from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
+import { z } from "zod";
+
+// The planner emits its plan as JSON inside <plan> tags; Output.object extracts
+// and validates it against this schema. We use Zod here, but any Standard
+// Schema validator works just as well — Valibot, ArkType, etc. See
+// https://standardschema.dev.
+const planSchema = z.object({
+  issues: z.array(
+    z.object({ id: z.string(), title: z.string(), branch: z.string() }),
+  ),
+});
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+// Maximum number of plan→execute→merge cycles before stopping.
+// Raise this if your backlog is large; lower it for a quick smoke-test run.
+const MAX_ITERATIONS = 10;
+
+// Hooks run inside the sandbox before the agent starts each iteration.
+// npm install ensures the sandbox always has fresh dependencies.
+const hooks = {
+  sandbox: { onSandboxReady: [{ command: "npm install" }] },
+};
+
+// Copy node_modules from the host into the worktree before each sandbox
+// starts. Avoids a full npm install from scratch; the hook above handles
+// platform-specific binaries and any packages added since the last copy.
+const copyToWorktree = ["node_modules"];
+
+// ---------------------------------------------------------------------------
+// Main loop
+// ---------------------------------------------------------------------------
+
+for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
+  console.log(`\n=== Iteration ${iteration}/${MAX_ITERATIONS} ===\n`);
+
+  // -------------------------------------------------------------------------
+  // Phase 1: Plan
+  //
+  // The planning agent (opus, for deeper reasoning) reads the open issue list,
+  // builds a dependency graph, and selects the issues that can be worked in
+  // parallel right now (i.e., no blocking dependencies on other open issues).
+  //
+  // It outputs a <plan> JSON block — Output.object parses and validates it.
+  // -------------------------------------------------------------------------
+  const plan = await sandcastle.run({
+    hooks,
+    sandbox: docker(),
+    name: "planner",
+    // One iteration is enough: the planner just needs to read and reason,
+    // not write code. (Structured output requires maxIterations: 1.)
+    maxIterations: 1,
+    // Opus for planning: dependency analysis benefits from deeper reasoning.
+    agent: sandcastle.claudeCode("claude-opus-4-8"),
+    promptFile: "./.sandcastle/plan-prompt.md",
+    // Extract and validate the <plan> JSON into a typed object. Throws
+    // StructuredOutputError if the tag is missing, the JSON is malformed, or
+    // validation fails — which aborts the loop.
+    output: sandcastle.Output.object({ tag: "plan", schema: planSchema }),
+  });
+
+  const issues = plan.output.issues;
+
+  if (issues.length === 0) {
+    // No unblocked work — either everything is done or everything is blocked.
+    console.log("No unblocked issues to work on. Exiting.");
+    break;
+  }
+
+  console.log(
+    `Planning complete. ${issues.length} issue(s) to work in parallel:`,
+  );
+  for (const issue of issues) {
+    console.log(`  ${issue.id}: ${issue.title} → ${issue.branch}`);
+  }
+
+  // -------------------------------------------------------------------------
+  // Phase 2: Execute
+  //
+  // Spawn one sonnet agent per issue, all running concurrently.
+  // Each agent works on its own branch so there are no conflicts during
+  // execution — merging happens in Phase 3.
+  //
+  // Promise.allSettled means one failing agent doesn't cancel the others.
+  // -------------------------------------------------------------------------
+  const settled = await Promise.allSettled(
+    issues.map((issue) =>
+      sandcastle.run({
+        hooks,
+        copyToWorktree,
+        // Each agent starts on its own branch via branchStrategy on run().
+        sandbox: docker(),
+        branchStrategy: { type: "branch", branch: issue.branch },
+        name: "implementer",
+        // Give each agent plenty of room to implement and iterate on tests.
+        maxIterations: 100,
+        // Sonnet for execution: fast and capable enough for typical issue work.
+        agent: sandcastle.claudeCode("claude-sonnet-4-6"),
+        promptFile: "./.sandcastle/implement-prompt.md",
+        // Prompt arguments substitute {{TASK_ID}}, {{ISSUE_TITLE}},
+        // and {{BRANCH}} placeholders in implement-prompt.md before the
+        // agent sees the prompt.
+        promptArgs: {
+          TASK_ID: issue.id,
+          ISSUE_TITLE: issue.title,
+          BRANCH: issue.branch,
+        },
+      }),
+    ),
+  );
+
+  // Log any agents that threw (network error, sandbox crash, etc.).
+  for (const [i, outcome] of settled.entries()) {
+    if (outcome.status === "rejected") {
+      console.error(
+        `  ✗ ${issues[i]!.id} (${issues[i]!.branch}) failed: ${outcome.reason}`,
+      );
+    }
+  }
+
+  // Only pass branches that actually produced commits to the merge phase.
+  // An agent that ran successfully but made no commits has nothing to merge.
+  const completedIssues = settled
+    .map((outcome, i) => ({ outcome, issue: issues[i]! }))
+    .filter(
+      (
+        entry,
+      ): entry is {
+        outcome: PromiseFulfilledResult<
+          Awaited<ReturnType<typeof sandcastle.run>>
+        >;
+        issue: (typeof issues)[number];
+      } =>
+        entry.outcome.status === "fulfilled" &&
+        entry.outcome.value.commits.length > 0,
+    )
+    .map((entry) => entry.issue);
+
+  const completedBranches = completedIssues.map((i) => i.branch);
+
+  console.log(
+    `\nExecution complete. ${completedBranches.length} branch(es) with commits:`,
+  );
+  for (const branch of completedBranches) {
+    console.log(`  ${branch}`);
+  }
+
+  if (completedBranches.length === 0) {
+    // All agents ran but none made commits — nothing to merge this cycle.
+    console.log("No commits produced. Nothing to merge.");
+    continue;
+  }
+
+  // -------------------------------------------------------------------------
+  // Phase 3: Merge
+  //
+  // One sonnet agent merges all completed branches into the current branch,
+  // resolving any conflicts and running tests to confirm everything still works.
+  //
+  // The {{BRANCHES}} and {{ISSUES}} prompt arguments are lists that the agent
+  // uses to know which branches to merge and which issues to close.
+  // -------------------------------------------------------------------------
+  await sandcastle.run({
+    hooks,
+    sandbox: docker(),
+    name: "merger",
+    maxIterations: 1,
+    // Sonnet is sufficient for merge conflict resolution.
+    agent: sandcastle.claudeCode("claude-sonnet-4-6"),
+    promptFile: "./.sandcastle/merge-prompt.md",
+    promptArgs: {
+      // A markdown list of branch names, one per line.
+      BRANCHES: completedBranches.map((b) => `- ${b}`).join("\n"),
+      // A markdown list of issue IDs and titles, one per line.
+      ISSUES: completedIssues.map((i) => `- ${i.id}: ${i.title}`).join("\n"),
+    },
+  });
+
+  console.log("\nBranches merged.");
+}
+
+console.log("\nAll done.");

package/dist/templates/parallel-planner/merge-prompt.md

@@ -0,0 +1,26 @@
+# TASK
+
+Merge the following branches into the current branch:
+
+{{BRANCHES}}
+
+For each branch:
+
+1. Run `git merge <branch> --no-edit`
+2. If there are merge conflicts, resolve them intelligently by reading both sides and choosing the correct resolution
+3. After resolving conflicts, run `npm run typecheck` and `npm run test` to verify everything works
+4. If tests fail, fix the issues before proceeding to the next branch
+
+After all branches are merged, make a single commit summarizing the merge.
+
+# CLOSE ISSUES
+
+For each branch that was merged, close its issue using the following command:
+
+`{{CLOSE_TASK_COMMAND}}`
+
+Here are all the issues:
+
+{{ISSUES}}
+
+Once you've merged everything you can, output <promise>COMPLETE</promise>.

package/dist/templates/parallel-planner/plan-prompt.md

@@ -0,0 +1,37 @@
+# ISSUES
+
+Here are the open issues in the repo:
+
+<issues-json>
+
+!`{{LIST_TASKS_COMMAND}}`
+
+</issues-json>
+
+The list above has already been filtered to issues ready for work.
+
+# TASK
+
+Analyze the open issues and build a dependency graph. For each issue, determine whether it **blocks** or **is blocked by** any other open issue.
+
+An issue B is **blocked by** issue A if:
+
+- B requires code or infrastructure that A introduces
+- B and A modify overlapping files or modules, making concurrent work likely to produce merge conflicts
+- B's requirements depend on a decision or API shape that A will establish
+
+An issue is **unblocked** if it has zero blocking dependencies on other open issues.
+
+For each unblocked issue, assign a branch name using the exact format `sandcastle/issue-{id}` (no slug or other suffix). This must be deterministic so that re-planning the same issue always produces the same branch name and accumulated progress is preserved.
+
+# OUTPUT
+
+Output your plan as a JSON object wrapped in `<plan>` tags:
+
+<plan>
+{"issues": [{"id": "42", "title": "Fix auth bug", "branch": "sandcastle/issue-42"}]}
+</plan>
+
+Include only unblocked issues. If every issue is blocked, include the single highest-priority candidate (the one with the fewest or weakest dependencies).
+
+Always emit the `<plan>` tags, even when there is nothing to do. If there are no issues to work on at all, output `<plan>{"issues": []}</plan>` so the run can exit cleanly.

package/dist/templates/parallel-planner/template.json

@@ -0,0 +1,4 @@
+{
+  "name": "parallel-planner",
+  "description": "Plans parallelizable issues, executes on separate branches, merges"
+}

package/dist/templates/parallel-planner-with-review/CODING_STANDARDS.md

@@ -0,0 +1,27 @@
+# Coding Standards
+
+<!-- Customize this file with your project's coding standards.
+     The reviewer agent loads it during code review via @.sandcastle/CODING_STANDARDS.md
+     so these standards are enforced during review without costing tokens during implementation. -->
+
+## Style
+
+<!-- Example:
+- Use camelCase for variables and functions
+- Use PascalCase for classes and types
+- Prefer named exports over default exports
+-->
+
+## Testing
+
+<!-- Example:
+- Every public function must have at least one test
+- Use descriptive test names that explain the expected behavior
+-->
+
+## Architecture
+
+<!-- Example:
+- Keep modules focused on a single responsibility
+- Prefer composition over inheritance
+-->

package/dist/templates/parallel-planner-with-review/implement-prompt.md

@@ -0,0 +1,62 @@
+# TASK
+
+Fix issue {{TASK_ID}}: {{ISSUE_TITLE}}
+
+Pull in the issue using `{{VIEW_TASK_COMMAND}}`. If it has a parent PRD, pull that in too.
+
+Only work on the issue specified.
+
+Work on branch {{BRANCH}}. Make commits and run tests.
+
+# CONTEXT
+
+Here are the last 10 commits:
+
+<recent-commits>
+
+!`git log -n 10 --format="%H%n%ad%n%B---" --date=short`
+
+</recent-commits>
+
+# EXPLORATION
+
+Explore the repo and fill your context window with relevant information that will allow you to complete the task.
+
+Pay extra attention to test files that touch the relevant parts of the code.
+
+# EXECUTION
+
+If applicable, use RGR to complete the task.
+
+1. RED: write one test
+2. GREEN: write the implementation to pass that test
+3. REPEAT until done
+4. REFACTOR the code
+
+# FEEDBACK LOOPS
+
+Before committing, run `npm run typecheck` and `npm run test` to ensure the tests pass.
+
+# COMMIT
+
+Make a git commit. The commit message must:
+
+1. Start with `RALPH:` prefix
+2. Include task completed + PRD reference
+3. Key decisions made
+4. Files changed
+5. Blockers or notes for next iteration
+
+Keep it concise.
+
+# THE ISSUE
+
+If the task is not complete, leave a comment on the issue with what was done.
+
+Do not close the issue - this will be done later.
+
+Once complete, output <promise>COMPLETE</promise>.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.