ai-artifacts/projects/skills/044-implement-skill-herdr-worktree-research.md

status, parent, claimed-by, claimed-at, blocked-by, tags

status	parent	claimed-by	claimed-at	blocked-by	tags
resolved	038-implement-skill-map	019fbb66-80d0-7a01-8ac9-01255adfc7b2	2026-07-31T23:46:29-04:00		ticket/research

Implement skill Herdr worktree research

Question

What Herdr worktree conventions or plugins are relevant to the migrated implement skill's branch and workspace handling?

Findings

Herdr itself has built-in worktree management according to herdr-worktrunk's README, which says Herdr ships herdr worktree create/open/remove/list. The same source says the Worktrunk plugin exists because Worktrunk adds lifecycle hooks that Herdr's built-in worktree commands lack. The migrated implement skill should not assume it must create panes itself if Herdr is already the user's workspace manager, but lifecycle setup may need a plugin or external manager. Source: https://raw.githubusercontent.com/devashish2203/herdr-worktrunk/main/README.md.

herdr-worktrunk opens existing or newly created worktrees as either Herdr tabs or native linked-worktree workspaces, and it delegates unmerged branch and untracked-file safety to Worktrunk during removal. This suggests an implementation workflow can treat Herdr as presentation and Worktrunk as branch/worktree lifecycle, rather than combining all responsibilities inside implement. Source: https://raw.githubusercontent.com/devashish2203/herdr-worktrunk/main/README.md.

herdr-sessionizer fuzzy-opens projects and Git worktrees into configured Herdr workspaces, using layouts to bootstrap tabs, pane splits, commands, and per-repo overrides. It supports a Worktree action to create or reopen a Git worktree workspace. This is relevant for interactive human-driven session startup, but less relevant for a skill that should run inside an already-started Pi process. Source: https://raw.githubusercontent.com/andrewchng/herdr-sessionizer/main/README.md.

herdr-plugin-workspace-manager applies declarative tab, pane, environment, startup-command, and agent layouts automatically to every new worktree. It can wait until Herdr reports an agent ready for input and optionally hand it a prompt, and it can remove worktrees whose upstream branch is gone. A future orchestration layer could use this to launch implementer/reviewer/tester panes, but the core implement skill should not depend on it unless the destination expands to Herdr orchestration. Source: https://raw.githubusercontent.com/razajamil/herdr-plugin-workspace-manager/main/README.md.

herdr-worktree-setup listens for Herdr's worktree.created event and runs per-project setup steps such as copying .env, mise trust, direnv allow, and package installation. It exposes HERDR_MAIN_REPO, HERDR_WORKTREE, and HERDR_BRANCH to those steps. If implement uses Herdr-created worktrees, it should rely on such setup hooks rather than scripting environment copying itself. Source: https://raw.githubusercontent.com/tdi/herdr-worktree-setup/main/README.md.

herdr-worktree-from-linear and herdr-worktree-from-pr create worktrees from external tracker items or PRs and open them as Herdr workspaces. They are useful references for selecting a branch base, reusing an existing worktree, and separating worktree creation from setup plugins. They are less directly applicable to Wayfinder Markdown task tickets unless a later decision adds a tracker bridge. Sources: https://raw.githubusercontent.com/tdi/herdr-worktree-from-linear/main/README.md, https://raw.githubusercontent.com/tdi/herdr-worktree-from-pr/main/README.md.

herdr-worktreeinclude copies gitignored files matching .worktreeinclude into newly created Herdr worktrees and explicitly cites Claude Code's .worktreeinclude convention. For implementation worktrees, this is a safer project-declared way to copy local config than having implement guess which ignored files are needed. Source: https://raw.githubusercontent.com/tanshio/herdr-worktreeinclude/main/README.md.

pi-herd is a Pi-first Herdr orchestration project that creates visible lead and worker sessions, keeps source-changing roles in isolated git worktrees, and stores durable run artifacts under .pi-herd/runs/. This is relevant if the implement workflow later becomes multi-agent orchestration, but it is broader than a single-ticket implement skill. Source: https://raw.githubusercontent.com/ribbons-digital/pi-herd/main/README.md.

Conclusion

Herdr research supports keeping worktree and pane orchestration optional and external to the core implement skill. The skill should be compatible with Herdr-managed worktrees, should not duplicate lifecycle setup hooks, and should prefer project-declared mechanisms such as .worktreeinclude or worktree setup plugins for ignored local config. Dedicated Herdr orchestration belongs outside the first migrated implement contract unless the user explicitly broadens the destination.