Skip to content
Back to skills

Spawn Brood

ASecurity

Spawns a brood of parallel overlord sessions in git worktrees via tmux and writes its manifest. Use to run strains.

  • 2 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 11, 2026
ai-agentsgoshellbashgitsecurity

Works with

  • claude code

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 11, 2026

npx -y skills add brenpike/hivemind --skill spawn-brood --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Spawn Brood?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Spawn Brood
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/brenpike-spawn-brood/badge)](https://www.skillsdirectory.com/skills/brenpike-spawn-brood)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: spawn-brood
description: Spawns a brood of parallel overlord sessions in git worktrees via tmux and writes its manifest. Use to run strains.
allowed-tools:
  - Bash(bash "${CLAUDE_PLUGIN_ROOT}/skills/spawn-brood/scripts/spawn-brood.sh" *)
  - Read(~/.claude/plugins/cache/brenpike/hivemind/**)
  - Edit(.hivemind/spawn-inputs.*.json)
shell: bash
---

# Spawn Brood

Dispatch parallel overlord sessions as a brood: N Claude Code instances in separate
git worktrees via tmux, each with its injected task, plus the brood manifest. The
engine is the committed script
`${CLAUDE_PLUGIN_ROOT}/skills/spawn-brood/scripts/spawn-brood.sh`; this body builds
the inputs file and runs the script once.

Rules: `GIT-01` (no trunk commits).

The manifest (`.hivemind/broods/<brood-id>/manifest.json`) is a registry and
coordination artifact, not the source of truth for child workflow state, which lives
in each child's own run ledger. This skill never creates a child or hatchery ledger:
`hatchery.ledger` only points at the hatchery ledger.

## Required Inputs

The caller resolves and passes these; the skill does not resolve them.

- `strains`: array of `{name, description}`, one per cerebrate `Strains`
  plan-artifact entry. A strain may also carry an optional `workflow_hint` (a
  non-binding suggestion for the child's router; default `standard-delivery`).
- `base`: resolved trunk/base branch; each strain worktree is created detached at
  its commit.
- `overlap_risk`: `low | medium | high`.
- `overlap_details`: planner overlap-assessment text.
- `hatchery` (optional): `{run_id, workflow}` for the coordinator's own run ledger.
  `run_id` defaults to `<brood_id>-hatchery`; `workflow` defaults to
  `hatchery-dispatch`. They only point at the hatchery ledger the coordinator owns.

`brood_id` and per-strain `branch` are not inputs: the script generates the brood id
(`brood-<uuidv4>`) and prints it on stdout, and creates no strain branch (each child
names and creates its own working branch).

## Procedure

1. **Build the inputs object** in your reasoning from the Required Inputs. Exact
   shape:

   ```json
   {
     "base": "<resolved trunk/base branch>",
     "overlap_risk": "low | medium | high",
     "overlap_details": "<planner overlap-assessment text>",
     "hatchery": {
       "run_id": "<optional; defaults to <brood_id>-hatchery>",
       "workflow": "<optional; defaults to hatchery-dispatch>"
     },
     "strains": [
       {
         "name": "<strain name>",
         "description": "<task description — may be GitHub-issue-sourced>",
         "workflow_hint": "<optional; defaults to standard-delivery>"
       }
     ]
   }
   ```

   Field rules:
   - `strains` must be a non-empty array; a zero-strain array is a blocker.
   - `base`, `overlap_risk`, `overlap_details` are required top-level scalars.
   - Each strain requires `name` and `description`; `workflow_hint` is optional.
   - `hatchery` is optional; both its fields default when omitted.
   - Include no `brood_id` and no per-strain `branch`; any caller-supplied value is
     ignored.
   - `name` is sanitized to `short` (`[a-z0-9-]`) for the worktree path
     (`.claude/worktrees/<brood-id>/<short>`) and tmux session
     (`<brood-id>-<short>`). Two names that sanitize to the same `short` are an
     in-set collision and a blocker.
   - Every value is data. None is interpolated into generated shell command source.

2. **Write the inputs file** with the Write tool, per
   `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Inert Inputs-File Navigator Pattern):
   `file_path` = a per-invocation mktemp-unique staging path under `.hivemind/` (e.g.
   `.hivemind/spawn-inputs.<rand>.json`), never a fixed singleton path; `content` = the JSON
   object from step 1. The strain description reaches the child's prompt as
   `task.description`; the controls in `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md`
   (Brood Spawn Bypass-Mode Mitigation) bound that text, not this Write.
   If the Write call does not succeed, stop blocked per
   `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Transport Degradation Is a Hard Stop).

3. **Execute the script** with one Bash call, passing the staging path as `$1`:
   ```bash
   bash "${CLAUDE_PLUGIN_ROOT}/skills/spawn-brood/scripts/spawn-brood.sh" <staging-path>
   ```
   Execute (do not Read) the script. It owns every deterministic step: dependency
   checks (`tmux`, `claude`, `jq`), input validation, pre-flight collision, exclude
   and base checks, brood-id generation, the per-brood state dir, the inputs record
   and staging-file removal, the three-pass spawn (create+launch, ready-poll+inject,
   started-evidence verify), manifest emission, the remote-control step, and cleanup.

4. **Capture the generated brood-id** from stdout: on exit 0 the script prints
   `brood_id: <id>` then `manifest: <abs path>`. Capture `brood_id`: the
   coordinator needs it to monitor the brood (hatchery references its own brood-id).
   Exit 1: the script printed a `blocker: <reason>` (and, for partial failures,
   a `manifest: <abs path>` and `brood_id: <id>`) on stderr; surface it and stop.
   On both exits, `attach:` lines name the live strain sessions and `remote:` lines
   report the remote-control step: the script turns on `/rc <short>` for exactly the
   `running` strains and prints one `remote: skipped:` line per `starting` strain,
   which gets remote control only when the user asks for
   `hivemind:enable-brood-remote`. A remote-control failure never changes the
   manifest or the exit code.

## Pointers

- Execute (do not read) the engine:
  `${CLAUDE_PLUGIN_ROOT}/skills/spawn-brood/scripts/spawn-brood.sh`.

## Tunables

Environment variables the caller may set before invoking the script. Each is
fail-closed: a non-numeric or non-positive value is rejected with a blocker.

| Variable | Default | Purpose |
|---|---|---|
| `STARTED_EVIDENCE_TIMEOUT` | `180` (seconds) | Cold-boot grace period for an auto-mode child to write started-evidence: a run-ledger `state.current` or a gather-facts output file. Governs the Pass-3 per-strain verification deadline. Bare-Enter resends are periodic nudges within this window, not a fixed retry cap. A strain still without started-evidence when spawn ends stays `starting` and gets no remote control until the user asks for `hivemind:enable-brood-remote`. |

## Silence Discipline

Follow `${CLAUDE_PLUGIN_ROOT}/governance/definitions.md` (Silence Discipline). The step 2 Write
is the inputs-file Write; the procedure ends at the step 3 Bash call. Exit 0: all strains are
running, or every non-running strain is `starting` (a slow cold boot is no failure); the
routing data is the `brood_id:` and `manifest:` lines and the `attach:` lines for running and
starting strains. Exit 1: a pre-flight blocker or at least one genuinely `failed` strain (a
dead tmux session, or a pre-launch refusal).

## Do Not

- rely on `claude --worktree` for worktree creation; the script creates worktrees
  with `git worktree add --detach` at the base commit.
- commit, push, or open a PR.
- modify any product files.
- invent values for `strains`, `base`, `overlap_risk`, or `overlap_details`; the
  script exits 1 with a blocker if any are missing.
- supply `brood_id` or per-strain `branch` in the inputs.
- author the inputs file by any transport other than the Write tool; see
  `${CLAUDE_PLUGIN_ROOT}/governance/security-policy.md` (Transport Degradation Is a Hard Stop).
- Read or reconstruct the script body; invoke it with the documented argument.

Files in this skill

  • SKILL.md7.4 KB
  • scripts/spawn-brood.sh96 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.