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:

   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: 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 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.