# Herdr Git Parallel Worktrees

> Use when independent write lanes need isolated Herdr-managed Git linked worktrees with safe allocation, reuse, and cleanup.

- Skill: `gw31415/herdr-git-parallel-worktrees` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add gw31415/herdr-git-parallel-worktrees`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gw31415/herdr-git-parallel-worktrees/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gw31415 (https://skillmd.com/u/gw31415)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gw31415/herdr-git-parallel-worktrees

---


# Herdr Git Parallel Worktrees

Allocate one Git linked worktree and one Herdr workspace per concurrently
running write lane. This is a lifecycle contract: it does not choose, start,
or configure an agent.

## When to Use

Use for independent write work in one repository when each lane can have its
own branch, checkout, workspace, and root pane. The caller supplies a stable
`lane_id`, branch, purpose, and write scope, then uses the returned allocation
contract.

## Do Not Use

Do not use for read-only work, mutually conflicting edits, a task that must
share one checkout, or when required Git/Herdr capabilities are unavailable.
Never fall back to a shared checkout for parallel writes.

## Operational contract

1. Preflight the repository and capabilities:
   - resolve and verify the caller's Git repository root;
   - inspect `git worktree list --porcelain` and record existing branches and
     checkout paths;
   - confirm that `herdr` is available;
   - query the live CLI help at each relevant level (using `--help` where the
     installed CLI advertises that option, including worktree and workspace
     operations) and use only commands, options, and output modes it advertises.
     Live CLI help is authoritative; do not guess a variant;
   - verify any requirement that the worktree be Herdr-managed before
     allocating a lane.
   Stop before parallel writes if any check fails.
2. Select the allocation root. A caller-specified root takes precedence;
   otherwise use `${HERDR_WORKTREE_ROOT:-$HOME/.herdr/worktrees}`. Under that
   root, use the repository basename plus a stable repository identity derived
   from the verified root (for example, a normalized remote identity or a
   deterministic local identity). Keep the identity stable across calls,
   reject traversal or ambiguous collisions, and refuse reuse until the
   candidate's Git root, branch, and lane metadata match.
3. Allocate serially. The allocator is the only concurrent-write boundary:
   acquire the repository allocator's serialization mechanism, re-read Git
   state after acquiring it, and complete one lane's discovery and allocation
   before starting the next. If create reports an already-existing resource,
   re-discover and open the matching resource rather than retrying create.
   First find an existing matching branch/worktree from Git's porcelain data.
   For a match, invoke the live-help-confirmed `worktree open` operation to
   reuse its Herdr workspace. Otherwise invoke the confirmed `worktree create`
   operation with the caller's branch and checkout path. Read the workspace
   ID from the actual create/open response. Obtain `root_pane_id` from that
   response or from a live-help-confirmed follow-up query whose selection rule
   proves it is the lane's root pane; never infer IDs from ordering, names, or
   prior state. A missing or ambiguous response ID is an allocation failure.
4. Return this logical contract exactly:

   ```text
   lane_id
   repo_root
   branch
   checkout_path
   workspace_id
   root_pane_id
   allocation: created | reused
   ```

   The consumer may launch work in `root_pane_id`, but must not change the
   allocation or cleanup semantics.
5. Track the lane through the state machine in
   [lifecycle-contract.md](references/lifecycle-contract.md):
   `planned -> created|reused -> working -> blocked|verified -> cleaned`.
   Record failures and preserve the allocation for inspection when cleanup is
   not safe.
6. On completion, obtain the consumer's verification result and integration
   handoff for the lane before cleanup. Close the Herdr workspace successfully
   before removing its Git worktree. A dirty or uncommitted worktree must be
   refused by the standard cleanup flow; do not force-remove it. If close
   fails, do not remove the worktree.

Read [compatibility.md](references/compatibility.md) when capability discovery,
output parsing, platform support, or a failure mode is uncertain.

## Installation and maintenance

Install this directory as an agent-neutral `SKILL.md` source, preserving its
path under `skills/devops/`. Configure the chosen agent's skill-discovery
mechanism to load it, then validate the installed copy before use. This
repository is the canonical source of the allocation contract.

Consumers may add local adapter skills for agent launch, local command
environment, authentication, or other machine integration. Adapters consume
the allocation contract; they may not weaken one-worktree-per-write-lane,
serial allocation, response-derived IDs, dirty-worktree refusal, or
close-before-remove.

Version this contract semantically: use a patch release for wording or
compatibility corrections, a minor release for newly supported capabilities,
and a major release for an allocation-contract or cleanup-order change. After
an upgrade, inspect live Herdr help, run disposable lifecycle tests on each
supported platform, and remove stale examples rather than accumulating
contradictory guidance.