Runcastle

Bug Triage Swarm

MIT↓ 0 downloads

by runcastle

v1.0.1
v1.0.1v1.0.0
Homepage ↗

An Opus planner triages your open `bug`-labelled GitHub issues into independent fixes, then a swarm of Sonnet fixers fans out — one per issue, each on its own branch — to reproduce, root-cause, patch, and test the bug in parallel.

#bug-triage#github-issues#fan-out#gh#docker

Topology

Disclosures

Disclosures — declared side-effect surface

Everything below runs on your machine or inside the sandbox when you use this workflow. Mismatches between these declarations and the actual code block publishing.

Host hooks

Commands executed on YOUR host machine by Sandcastle lifecycle hooks.

None declared.

Sandbox hooks

Commands executed inside the sandbox container.

  • npm install

Network access

Runs `gh` inside the sandbox to list issues labelled `bug` and to view the body of each issue being fixed on the current repository. No other hosts are contacted.

Shell expansion

Prompt files contain !`command` blocks — the agent CLI executes these commands at prompt-load time. They are highlighted amber in the prompt files below.

Files

Diff vs the stock Sandcastle 0.12.0 template Dockerfile — green lines were added by the author, red lines were removed from stock.

+# Sandbox image for the Bug Triage Swarm workflow.
+# Node 22 + git + the GitHub CLI (the planner and fixers read issues via `gh`)
+# + the Claude Code CLI, running as a non-root `agent` user.
 FROM node:22-bookworm
  
-# System dependencies.
+# System dependencies used by the agents and the gh issue blocks.
 RUN apt-get update && apt-get install -y --no-install-recommends \
       git \
       curl \
       jq \
       ca-certificates \
  && rm -rf /var/lib/apt/lists/*
  
-# Claude Code CLI (the agent runtime).
+# GitHub CLI — used by the !`gh ...` shell-expansion blocks in the prompts.
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update && apt-get install -y --no-install-recommends gh \
+ && rm -rf /var/lib/apt/lists/*
+ 
+# Claude Code CLI (the planner and fixer agent runtime).
 RUN npm install -g @anthropic-ai/claude-code
  
 # Non-root agent user. `sandcastle docker build-image` aligns AGENT_UID/GID to
 # the host user via --build-arg to avoid permission errors on bind mounts.
+# node:22-bookworm already ships a "node" user at UID/GID 1000, so we RENAME it
+# (the stock Sandcastle template pattern) — groupadd/useradd would collide with
+# the existing IDs on a default build.
 ARG AGENT_UID=1000
 ARG AGENT_GID=1000
-RUN groupadd --gid ${AGENT_GID} agent \
- && useradd --uid ${AGENT_UID} --gid ${AGENT_GID} --create-home --shell /bin/bash agent
+RUN groupmod -o -g ${AGENT_GID} node \
+ && usermod -o -u ${AGENT_UID} -g ${AGENT_GID} -d /home/agent -m -l agent node
  
-USER agent
-WORKDIR /workspace
+USER ${AGENT_UID}:${AGENT_GID}
+WORKDIR /home/agent
+ 
+# Sandcastle bind-mounts the worktree and sets the working directory at
+# container start; the container just needs to stay alive until then.
+ENTRYPOINT ["sleep", "infinity"]
Show full Dockerfile (highlighted)
# Sandbox image for the Bug Triage Swarm workflow.
# Node 22 + git + the GitHub CLI (the planner and fixers read issues via `gh`)
# + the Claude Code CLI, running as a non-root `agent` user.
FROM node:22-bookworm

# System dependencies used by the agents and the gh issue blocks.
RUN apt-get update && apt-get install -y --no-install-recommends \
      git \
      curl \
      jq \
      ca-certificates \
 && rm -rf /var/lib/apt/lists/*

# GitHub CLI — used by the !`gh ...` shell-expansion blocks in the prompts.
RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
      | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
 && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
      > /etc/apt/sources.list.d/github-cli.list \
 && apt-get update && apt-get install -y --no-install-recommends gh \
 && rm -rf /var/lib/apt/lists/*

# Claude Code CLI (the planner and fixer agent runtime).
RUN npm install -g @anthropic-ai/claude-code

# Non-root agent user. `sandcastle docker build-image` aligns AGENT_UID/GID to
# the host user via --build-arg to avoid permission errors on bind mounts.
# node:22-bookworm already ships a "node" user at UID/GID 1000, so we RENAME it
# (the stock Sandcastle template pattern) — groupadd/useradd would collide with
# the existing IDs on a default build.
ARG AGENT_UID=1000
ARG AGENT_GID=1000
RUN groupmod -o -g ${AGENT_GID} node \
 && usermod -o -u ${AGENT_UID} -g ${AGENT_GID} -d /home/agent -m -l agent node

USER ${AGENT_UID}:${AGENT_GID}
WORKDIR /home/agent

# Sandcastle bind-mounts the worktree and sets the working directory at
# container start; the container just needs to stay alive until then.
ENTRYPOINT ["sleep", "infinity"]

README

Bug Triage Swarm

Turn a backlog of open bug reports into a stack of ready-to-review fixes — in parallel. This workflow triages your bug-labelled GitHub issues, then dispatches a swarm of agents that each own one bug end to end: reproduce it, find the root cause, patch it, and prove the fix with tests.

What it does

First, a Claude Code planner (Opus) reads every open issue labelled bug and groups them into independent fixes. It notes the suspected root cause, the files each fix likely touches, and flags duplicates or overlaps so two agents never fight over the same code.

Then a swarm of fixers (Sonnet) fans out — one agent per issue, each on its own agent/bug-<n> branch. Every fixer pulls its own issue body, writes a failing reproduction test, fixes the root cause (not just the symptom), and makes sure the suite goes green before committing with a fix: #<n> message.

How it works

main.ts runs the planner once, then uses Promise.all to fan out the fixers, each pinned to a distinct branch so the parallel runs never collide on HEAD. Both the planner and the fixers read issues through !`gh issue list` and !`gh issue view` shell-expansion blocks inside their prompts — this is why the manifest discloses network access (via gh) and shell expansion. The topology is triage → fix ×N (fan-out) → fixes on branches. A npm install sandbox hook warms dependencies so every agent can run the test suite.

Requirements

Set CLAUDE_CODE_OAUTH_TOKEN in .sandcastle/.env (run claude setup-token). For private repositories, also set GITHUB_TOKEN so gh can authenticate. Label the issues you want handled with bug, and edit the issueNumbers demo list at the top of .sandcastle/main.ts to the issues you actually want fixed. Build the image once with npx @ai-hero/sandcastle docker build-image, then run npx tsx .sandcastle/main.ts. Each fix lands on its own branch, ready to open as a PR and review.