@rockclaver/sandcastle 0.7.0

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.agent({ default: "claude-code" }),
+    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.agent({ default: "claude-code" }),
+        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.agent({ default: "claude-code" }),
+    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.

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

@@ -0,0 +1,226 @@
+// Parallel Planner with Review — four-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 branch names.
+//   Phase 2 (Execute + Review): For each issue, a sandbox is created via
+//                               createSandbox(). The implementer runs first
+//                               (100 iterations). If it produces commits, a
+//                               reviewer runs in the same sandbox on the same
+//                               branch (1 iteration). All issue pipelines run
+//                               concurrently via Promise.allSettled().
+//   Phase 3 (Merge):            A single agent merges all completed branches
+//                               into the current branch.
+//
+// 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.agent({ default: "claude-code" }),
+    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 + Review
+  //
+  // For each issue, create a sandbox via createSandbox() so the implementer
+  // and reviewer share the same sandbox instance per branch. The implementer
+  // runs first; if it produces commits, the reviewer runs in the same sandbox.
+  //
+  // Promise.allSettled means one failing pipeline doesn't cancel the others.
+  // -------------------------------------------------------------------------
+
+  const settled = await Promise.allSettled(
+    issues.map(async (issue) => {
+      const sandbox = await sandcastle.createSandbox({
+        branch: issue.branch,
+        sandbox: docker(),
+        hooks,
+        copyToWorktree,
+      });
+
+      try {
+        // Run the implementer
+        const implement = await sandbox.run({
+          name: "implementer",
+          maxIterations: 100,
+          agent: sandcastle.agent({ default: "claude-code" }),
+          promptFile: "./.sandcastle/implement-prompt.md",
+          promptArgs: {
+            TASK_ID: issue.id,
+            ISSUE_TITLE: issue.title,
+            BRANCH: issue.branch,
+          },
+        });
+
+        // Only review if the implementer produced commits
+        if (implement.commits.length > 0) {
+          const review = await sandbox.run({
+            name: "reviewer",
+            maxIterations: 1,
+            agent: sandcastle.agent({ default: "claude-code" }),
+            promptFile: "./.sandcastle/review-prompt.md",
+            promptArgs: {
+              BRANCH: issue.branch,
+            },
+          });
+
+          // Merge commits from both runs so the merge phase sees all of them.
+          // Each sandbox.run() only returns commits from its own run.
+          return {
+            ...review,
+            commits: [...implement.commits, ...review.commits],
+          };
+        }
+
+        return implement;
+      } finally {
+        await sandbox.close();
+      }
+    }),
+  );
+
+  // 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.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 agent merges all completed branches into the current branch,
+  // resolving any conflicts and running tests to confirm everything 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,
+    agent: sandcastle.agent({ default: "claude-code" }),
+    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.");