Herdr + jj task workflow
Check HERDR_BACKEND and the host configuration before controlling Herdr. Native uses herdr-app and hc, not the legacy herdr workspace protocol. In dotfiles, read config/herdr/README.md for native commands. Use herdr-dev open PATH for an existing checkout and Hunk; its agent follows DEFAULT_CODING_AGENT unless explicitly overridden. Native jj creation and guarded cleanup are not ported. Keep existing checkouts, task bookmarks, receipts and commit approval gates; report unsupported lifecycle operations instead of switching to the old TUI or bypassing cleanup guards.
The lifecycle commands below apply only to an explicitly selected legacy backend. Do not launch legacy Herdr to make them available in a native session.
Use one durable Herdr workspace per issue, PR, or task. Share one stable name across the checkout, jj workspace, jj bookmark, Herdr workspace label, and PR head when a PR exists:
issue-N-slugpr-N-slugtask-slug
Treat that name as durable. Treat Herdr workspace, tab, and pane IDs as live handles; re-read them after lifecycle changes.
Use Hunk from the task checkout's own Git root. For a non-colocated jj workspace, use jj diff --git -r @ in the agent pane and record findings plus check output in the worklog when present, otherwise in the final handoff. "Review surface" below means either path.
When to use
Use this skill for create, resume, approve commit, publish, ship, submit review, cleanup, or abandon requests involving a Herdr jj task workspace.
Non-negotiable rules
- Before controlling Herdr, require
HERDR_ENV=1; use the current session and never launch nested Herdr. - Before any jj mutation, run
pwdandjj log -r @. Never usejj editonly to inspect history. - Keep one task bookmark per workspace. Reuse it; do not create a replacement branch.
- Shape the current change in place with
jj describeandjj squash. Runjj newonly when starting another reviewed intent. - Review every intended commit. Use Hunk from the Git root when available; otherwise use the pure-jj review surface defined above. Commit only after the user says
approve commitand findings plus checks are clear. - In non-colocated jj workspaces, review in the agent pane; never point Hunk at the primary checkout or another workspace to work around a missing Git root.
- Fetch only during explicit
publishorship, never during workspace creation. - Never stop or kill Herdr. Use config reloads and read-only state checks.
Create or resume
- Use
prefix+ato create a jj workspace. Enter the stable task name and base revision. Base defaults totrunk(); use a published parent bookmark for a stacked task. - Let Herdr create the workspace and bootstrap its tabs. Do not create another workspace from the new agent session.
- Run
hey agent-startwithout--workspacefrom the created checkout and retain its receipt. FollowAGENT_WORKFLOW.mdwhen applicable; its worklog is optional, not a second tracker. - The dotfiles
devlayout opens$AGENTfirst, then Hunk. ExportAGENTas the agent executable name or path in the pane's shell environment, without arguments. There is no hard-coded OMP fallback. The layout does not conditionally omit Hunk for non-colocated workspaces; use the agent pane for review there. - Use
herdr agent listandherdr workspace listto resolve current live handles; never reuse example IDs. - Use
prefix+gonly for the native Git-only worktree flow. - Resume from the issue or PR, jj log/bookmarks, review findings, the run receipt, any worklog, and live Herdr state. Conversation history is not authoritative.
Colocated child workspaces
With jj 0.46 or newer, jj workspace add creates a corresponding Git worktree when the source workspace is colocated and git.colocate is true, its default. The Herdr plugin uses this default without an override. Children created from a colocated child inherit the same behavior. No separate git worktree add or jj initialization is needed.
After creation, run these inside the child checkout:
jj root --ignore-working-copy
git rev-parse --show-toplevel
Both must resolve to the child checkout before using Hunk. Keep VCS mutations in jj and retain the explicit task bookmark; colocation does not make the task a Git-only workflow.
Existing non-colocated jj children do not change automatically. To convert one, first confirm its jj root, run pwd and jj log -r @, then run jj git colocation enable inside that child. Recheck both roots and reopen Hunk there. Do not create a replacement workspace. If keeping the child non-colocated, review with jj diff --git -r @ in the agent pane. Manual creation can force either mode with jj workspace add --colocate or --no-colocate.
This conversion applies only to an existing jj workspace. Never run jj git init --colocate inside a Git-only worktree created by Codex or Herdr's native Git flow.
Review and commit
- Inspect
jj diffand the current task bookmark. - Refresh the review surface: Hunk from
git rev-parse --show-toplevel, orjj diff --git -r @for pure jj. - Address every applicable finding and run the focused check.
- On
approve commit, re-read the same review surface and check output. - Run
jj describe -m '<message>'. - Run
jj bookmark set <task-name> -r @. - If another independent intent remains, run
jj new; otherwise leave@at the reviewed task tip.
Publish
On explicit publish, load done and follow only its authorized publication stages. Preserve this skill's review and commit approval gates, task bookmark, and jj-only mutation rules. Do not turn branch publication into landing or cleanup.
Create or update a PR only when explicitly requested or required by repository policy or protected-branch rules. For stacked publication, verify the parent is reviewed and published; require a parent PR only for the PR path. A stacked PR targets its parent bookmark; otherwise it targets the repository default branch.
Ship
On explicit ship, load done for landing, authoritative remote proof, receipts, and safe cleanup. Preserve recorded review approval and this skill's commit approval gates. Follow done's direct-landing default unless a PR is explicitly requested or required; do not substitute deferred auto-merge for proved landing. Keep CI repair within done's bounded authority. After a parent lands, rebase each child from its own workspace and retarget any child PR as needed.
Cleanup and abandon
prefix+dremoves only a clean secondary workspace whose PR is closed or merged.- A verified direct landing can satisfy
done's landing requirement without a PR. Use only a supported guarded cleanup path; if the installed plugin cannot accept that proof, reportLanded; cleanup deferredrather than bypassing its guard. prefix+Dis the explicit abandon path. It still requires a clean workspace and exact typed task-name confirmation.- Never remove the main jj workspace. Never clean up work that is changed, ambiguous, or still under an open PR.
- Keep the plugin's guarded cleanup. Its
jj workspace forgetalso unregisters the corresponding Git worktree before directory removal. Do not bypass it withgit worktree removeor an unguardedjj workspace remove.
External PR review
Use pr-N-slug. Stay read-only by default. Put findings in the active review surface and submit them upstream only on explicit submit review. Modify the PR only after explicit takeover.