# Herdr Workflows

> Apply local safeguards for Herdr session recovery and transferring linked-worktree changes back to a host checkout. Use alongside the herdr skill when diagnosing Herdr socket routing, recovering the default session, or moving, consolidating, or continuing Herdr worktree changes from the main or host checkout. The herdr skill remains authoritative for all Herdr CLI, topology, targeting, lifecycle, and safety behaviour.

- Skill: `timmo001/herdr-workflows` (Agent Skill)
- Install (CLI): `npx skillmds@latest add timmo001/herdr-workflows`
- Raw SKILL.md: https://api.skillmd.com/api/skills/timmo001/herdr-workflows/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: timmo001 (https://skillmd.com/u/timmo001)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/timmo001/herdr-workflows

---


# Herdr Workflows

Load `herdr` first. It is the sole source of truth for Herdr commands, command
semantics, topology, identifiers, targeting, agent lifecycle, output reading,
and general safety. Do not restate, override, or infer those rules here. This
companion adds only the local exceptions and transfer ordering below.

## Session Routing

- When diagnosing session routing, inspect the inherited `HERDR_SOCKET_PATH`.
  Do not assume the default socket identifies the current pane's server.
- Do not recover a stopped or unreachable shared session by running
  `herdr server` directly. Use `herdr session attach default`; its attach path
  safely starts the default server when absent.

## Worktree Transfer

Treat checkout removal and work transfer as separate operations. Use the
`herdr` skill and current CLI to determine the available worktree operations;
this workflow only decides when removal is safe.

### Establish Both Checkouts

1. Identify the linked source workspace, branch, checkout path, and exact Git
   state. Identify the repository's primary non-linked checkout as the host;
   "host" does not imply that its current branch is named `main`.
2. Use Herdr and Git's worktree metadata to establish paths and workspace IDs.
   Confirm whether the host checkout already has staged, unstaged, or untracked
   work.
3. Keep the final coordinator outside the linked checkout being removed. If the
   current agent runs inside that checkout, use an existing host workspace or
   open the host checkout with Herdr, then coordinate from that host workspace.
   Do not remove the checkout containing the coordinator's running process.
4. Give the host-side coordinator compacted knowledge from the linked-worktree
   session: the user's intent, reviewed scope, material decisions, current Git
   and preservation state, validation evidence, and any further requested work.
   Do not rely on the host coordinator reconstructing that context from files or
   terminal output.

### Preserve The Reviewed State

1. Record the exact reviewed source scope: staged files, unstaged files,
   untracked files, base commit, and branch. Verification from an earlier turn
   is stale until both checkouts are checked again immediately before removal.
2. Make the reviewed content durable outside the linked checkout using the
   smallest non-destructive method appropriate to its state:
   - If the host already contains the intended files, verify their paths and
     content are byte-for-byte identical to the reviewed source.
   - If work is committed on the linked branch, verify the commit and branch
     are reachable from the host repository.
   - If work exists only as an uncommitted linked-checkout diff, reproduce it in
     the host checkout or create and verify a complete transfer artefact before
     removal. Account separately for staged, unstaged, and untracked content;
     an ordinary `git diff` does not include untracked files.
3. Preserve unrelated host changes. A matching file name is not evidence that
   the contents match, and a clean source after a copy is not evidence that the
   host copy is complete.
4. Stop on conflicts, missing files, differing content, an unexpected base, or
   a host branch switch that would overwrite changes. Do not use reset,
   checkout restoration, or an implicit stash to make the transfer proceed.

Every source change must have a verified durable counterpart outside the
checkout that will be removed.

### Hand Off To The Host

1. From the host-side coordinator, recheck both worktrees and confirm the
   linked workspace ID to remove. Do not begin removal until deleting the source
   checkout cannot destroy the only copy of any intended change.
2. Use the `herdr` skill's current removal process to remove only that linked
   workspace.
3. Confirm Herdr and Git no longer list the linked checkout, and confirm the
   source branch still exists before proceeding.
4. Switch the host checkout to the source branch. Dirty host changes
   may follow the switch only when Git accepts it without overwriting content.
   If the switch fails, stop and preserve the current host state.
5. Reverify the host branch, changed-file set, content, staging state, and any
   prior test evidence. Rerun checks when checkout context or generated state
   could affect their result.
6. If the user requested further work, continue it from the host checkout.
   Otherwise, stop and report the completed transfer.

Report the source workspace removed, final host path and branch, preservation
method, final changed-file state, and verification run. Do not report a
transfer complete merely because the linked workspace disappeared.