@ai-hero/sandcastle 0.3.0 → 0.4.1

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

@@ -0,0 +1,62 @@
+# TASK
+
+Fix issue #{{ISSUE_NUMBER}}: {{ISSUE_TITLE}}
+
+Pull in the issue using `gh issue view`. If it has a parent PRD, pull that in too.
+
+Only work on the issue specified.
+
+Work on branch {{BRANCH}}. Make commits, run tests, and close the issue when done.
+
+# 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 GitHub 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,249 @@
+// 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";
+
+// ---------------------------------------------------------------------------
+// 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 = {
+  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 copyToSandbox = ["node_modules"];
+
+// Cap the number of concurrent sandboxes to avoid resource exhaustion.
+const MAX_CONCURRENCY = 4;
+
+// ---------------------------------------------------------------------------
+// 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 — we parse that to drive Phase 2.
+  // -------------------------------------------------------------------------
+  const plan = await sandcastle.run({
+    hooks,
+    copyToSandbox,
+    sandbox: docker(),
+    name: "planner",
+    // One iteration is enough: the planner just needs to read and reason,
+    // not write code.
+    maxIterations: 1,
+    // Opus for planning: dependency analysis benefits from deeper reasoning.
+    agent: sandcastle.claudeCode("claude-opus-4-6"),
+    promptFile: "./.sandcastle/plan-prompt.md",
+  });
+
+  // Extract the <plan>…</plan> block from the agent's stdout.
+  const planMatch = plan.stdout.match(/<plan>([\s\S]*?)<\/plan>/);
+  if (!planMatch) {
+    throw new Error(
+      "Planning agent did not produce a <plan> tag.\n\n" + plan.stdout,
+    );
+  }
+
+  // The plan JSON contains an array of issues, each with number, title, branch.
+  const { issues } = JSON.parse(planMatch[1]!) as {
+    issues: { number: number; title: string; branch: string }[];
+  };
+
+  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.number}: ${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.
+  //
+  // A semaphore limits concurrency to MAX_CONCURRENCY sandboxes at once.
+  // Promise.allSettled means one failing pipeline doesn't cancel the others.
+  // -------------------------------------------------------------------------
+
+  // Simple semaphore for concurrency limiting
+  let running = 0;
+  const waiting: Array<() => void> = [];
+  const acquire = (): Promise<void> => {
+    if (running < MAX_CONCURRENCY) {
+      running++;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      waiting.push(() => {
+        running++;
+        resolve();
+      });
+    });
+  };
+  const release = () => {
+    running--;
+    const next = waiting.shift();
+    if (next) next();
+  };
+
+  const settled = await Promise.allSettled(
+    issues.map(async (issue) => {
+      await acquire();
+      try {
+        const sandbox = await sandcastle.createSandbox({
+          branch: issue.branch,
+          sandbox: docker(),
+          hooks,
+          copyToSandbox,
+        });
+
+        try {
+          // Run the implementer
+          const implement = await sandbox.run({
+            name: "implementer",
+            maxIterations: 100,
+            agent: sandcastle.claudeCode("claude-sonnet-4-6"),
+            promptFile: "./.sandcastle/implement-prompt.md",
+            promptArgs: {
+              ISSUE_NUMBER: String(issue.number),
+              ISSUE_TITLE: issue.title,
+              BRANCH: issue.branch,
+            },
+          });
+
+          // Only review if the implementer produced commits
+          if (implement.commits.length > 0) {
+            await sandbox.run({
+              name: "reviewer",
+              maxIterations: 1,
+              agent: sandcastle.claudeCode("claude-sonnet-4-6"),
+              promptFile: "./.sandcastle/review-prompt.md",
+              promptArgs: {
+                BRANCH: issue.branch,
+              },
+            });
+          }
+
+          return implement;
+        } finally {
+          await sandbox.close();
+        }
+      } finally {
+        release();
+      }
+    }),
+  );
+
+  // 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]!.number} (${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,
+    copyToSandbox,
+    sandbox: docker(),
+    name: "merger",
+    maxIterations: 1,
+    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 numbers and titles, one per line.
+      ISSUES: completedIssues
+        .map((i) => `- #${i.number}: ${i.title}`)
+        .join("\n"),
+    },
+  });
+
+  console.log("\nBranches merged.");
+}
+
+console.log("\nAll done.");

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

@@ -0,0 +1,22 @@
+# 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. Here are all the issues:
+
+{{ISSUES}}
+
+Once you've merged everything you can, output <promise>COMPLETE</promise>.

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

@@ -0,0 +1,33 @@
+# ISSUES
+
+Here are the open issues in the repo:
+
+<issues-json>
+
+!`gh issue list --state open --label Sandcastle --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`
+
+</issues-json>
+
+# 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 format `sandcastle/issue-{number}-{slug}`.
+
+# OUTPUT
+
+Output your plan as a JSON object wrapped in `<plan>` tags:
+
+<plan>
+{"issues": [{"number": 42, "title": "Fix auth bug", "branch": "sandcastle/issue-42-fix-auth-bug"}]}
+</plan>
+
+Include only unblocked issues. If every issue is blocked, include the single highest-priority candidate (the one with the fewest or weakest dependencies).

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

@@ -0,0 +1,55 @@
+# TASK
+
+Review the code changes on branch `{{BRANCH}}` and improve code clarity, consistency, and maintainability while preserving exact functionality.
+
+# CONTEXT
+
+## Branch diff
+
+!`git diff main...{{BRANCH}}`
+
+## Commits on this branch
+
+!`git log main..{{BRANCH}} --oneline`
+
+# REVIEW PROCESS
+
+1. **Understand the change**: Read the diff and commits above to understand the intent.
+
+2. **Analyze for improvements**: Look for opportunities to:
+   - Reduce unnecessary complexity and nesting
+   - Eliminate redundant code and abstractions
+   - Improve readability through clear variable and function names
+   - Consolidate related logic
+   - Remove unnecessary comments that describe obvious code
+   - Avoid nested ternary operators - prefer switch statements or if/else chains
+   - Choose clarity over brevity - explicit code is often better than overly compact code
+
+3. **Check correctness**:
+   - Does the implementation match the intent? Are edge cases handled?
+   - Are new/changed behaviours covered by tests?
+   - Are there unsafe casts, `any` types, or unchecked assumptions?
+   - Does the change introduce injection vulnerabilities, credential leaks, or other security issues?
+
+4. **Maintain balance**: Avoid over-simplification that could:
+   - Reduce code clarity or maintainability
+   - Create overly clever solutions that are hard to understand
+   - Combine too many concerns into single functions or components
+   - Remove helpful abstractions that improve code organization
+   - Make the code harder to debug or extend
+
+5. **Apply project standards**: Follow the coding standards defined in @.sandcastle/CODING_STANDARDS.md
+
+6. **Preserve functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
+
+# EXECUTION
+
+If you find improvements to make:
+
+1. Make the changes directly on this branch
+2. Run tests and type checking to ensure nothing is broken
+3. Commit describing the refinements
+
+If the code is already clean and well-structured, do nothing.
+
+Once complete, output <promise>COMPLETE</promise>.

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

@@ -0,0 +1,4 @@
+{
+  "name": "parallel-planner-with-review",
+  "description": "Plans parallelizable issues, executes with per-branch review, merges"
+}

package/dist/templates/sequential-reviewer/.env.example

@@ -1,4 +1,5 @@
 # Anthropic API key
+# If you want to use your Claude subscription instead of an API key, see https://github.com/mattpocock/sandcastle/issues/191
 ANTHROPIC_API_KEY=
 # GitHub personal access token
 GH_TOKEN=

package/dist/templates/sequential-reviewer/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/sequential-reviewer/implement-prompt.md

@@ -1,62 +1,51 @@
-# TASK
+# Context
 
-Fix issue #{{ISSUE_NUMBER}}: {{ISSUE_TITLE}}
+## Open issues
 
-Pull in the issue using `gh issue view`. If it has a parent PRD, pull that in too.
+!`gh issue list --label Sandcastle --json number,title,body --limit 20`
 
-Only work on the issue specified.
+## Recent RALPH commits (last 10)
 
-Work on branch {{BRANCH}}. Make commits, run tests, and close the issue when done.
+!`git log --oneline --grep="RALPH" -10`
 
-# CONTEXT
+# Task
 
-Here are the last 10 commits:
+You are RALPH — an autonomous coding agent working through GitHub issues one at a time.
 
-<recent-commits>
+## Priority order
 
-!`git log -n 10 --format="%H%n%ad%n%B---" --date=short`
+Work on issues in this order:
 
-</recent-commits>
+1. **Bug fixes** — broken behaviour affecting users
+2. **Tracer bullets** — thin end-to-end slices that prove an approach works
+3. **Polish** — improving existing functionality (error messages, UX, docs)
+4. **Refactors** — internal cleanups with no user-visible change
 
-# EXPLORATION
+Pick the highest-priority open issue that is not blocked by another open issue.
 
-Explore the repo and fill your context window with relevant information that will allow you to complete the task.
+## Workflow
 
-Pay extra attention to test files that touch the relevant parts of the code.
+1. **Explore** — read the issue carefully. Pull in the parent PRD if referenced. Read the relevant source files and tests before writing any code.
+2. **Plan** — decide what to change and why. Keep the change as small as possible.
+3. **Execute** — use RGR (Red → Green → Repeat → Refactor): write a failing test first, then write the implementation to pass it.
+4. **Verify** — run `npm run typecheck` and `npm run test` before committing. Fix any failures before proceeding.
+5. **Commit** — make a single git commit. The message MUST:
+   - Start with `RALPH:` prefix
+   - Include the task completed and any PRD reference
+   - List key decisions made
+   - List files changed
+   - Note any blockers for the next iteration
+6. **Close** — close the issue with `gh issue close <number> --comment "..."` explaining what was done.
 
-# EXECUTION
+## Rules
 
-If applicable, use RGR to complete the task.
+- Work on **one issue per iteration**. Do not attempt multiple issues in a single iteration.
+- Do not close an issue until you have committed the fix and verified tests pass.
+- Do not leave commented-out code or TODO comments in committed code.
+- If you are blocked (missing context, failing tests you cannot fix, external dependency), leave a comment on the issue and move on — do not close it.
 
-1. RED: write one test
-2. GREEN: write the implementation to pass that test
-3. REPEAT until done
-4. REFACTOR the code
+# Done
 
-# FEEDBACK LOOPS
+When all actionable issues are complete (or you are blocked on all remaining ones), output the completion signal:
 
-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 GitHub 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.
+<promise>COMPLETE</promise>

package/dist/templates/sequential-reviewer/main.mts

@@ -87,8 +87,9 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
     hooks,
     copyToSandbox,
     sandbox: docker(),
+    branchStrategy: { type: "branch", branch },
     name: "reviewer",
-    maxIterations: 10,
+    maxIterations: 1,
     agent: sandcastle.claudeCode("claude-sonnet-4-6"),
     promptFile: "./.sandcastle/review-prompt.md",
     // Prompt arguments substitute {{BRANCH}} in review-prompt.md before the
@@ -96,7 +97,6 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
     promptArgs: {
       BRANCH: branch,
     },
-    worktree: { mode: "branch", branch },
   });
 
   console.log("\nReview complete.");

package/dist/templates/sequential-reviewer/review-prompt.md

@@ -38,7 +38,7 @@ Review the code changes on branch `{{BRANCH}}` and improve code clarity, consist
    - Remove helpful abstractions that improve code organization
    - Make the code harder to debug or extend
 
-5. **Apply project standards**: Follow the established coding standards in the project.
+5. **Apply project standards**: Follow the coding standards defined in @.sandcastle/CODING_STANDARDS.md
 
 6. **Preserve functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
 

package/dist/templates/simple-loop/.env.example

@@ -1,4 +1,5 @@
 # Anthropic API key
+# If you want to use your Claude subscription instead of an API key, see https://github.com/mattpocock/sandcastle/issues/191
 ANTHROPIC_API_KEY=
 # GitHub personal access token
 GH_TOKEN=

package/dist/testSandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testSandbox.d.ts","sourceRoot":"","sources":["../src/testSandbox.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AAQvC,OAAO,EAAmB,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAa/D,eAAO,MAAM,qBAAqB,4DA8GjC,CAAC"}
+{"version":3,"file":"testSandbox.d.ts","sourceRoot":"","sources":["../src/testSandbox.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAC;AAQvC,OAAO,EAAmB,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAa/D,eAAO,MAAM,qBAAqB,4DAiHjC,CAAC"}