Herdr advisor

Invoked by the user (/herdr-advisor), or by you in one case: a grilling session (the grilling skill, however it was entered) has just ended with its frontier empty, and the user's next message confirms the plan for you to execute in this session, with no <worker-name>-advisor live and no opt-out in the confirmation ("no advisor", "go alone", or the like). Then follow this file before the first step of the work: the chooser, the pair, the handoff. A pair already live means nothing to do; do not prompt it. Never on your own judgment otherwise: not during the grill, not on a plan-mode approval, not on a "go ahead" after a written plan.

This file is the worker's. Advisor: your manual is ADVISOR.md in this directory; read that instead.

Unrelated to Claude Code's built-in advisor tool (--advisor, https://code.claude.com/docs/en/advisor) and to Codex auto-review (https://learn.chatgpt.com/docs/sandboxing/auto-review), a reviewer model that judges permission prompts: this skill launches a separate agent process that drives the worker.

Roles

• Worker: you, the main Herdr agent doing the user's work. Only you create the pair, and you make every change. Verify advice before acting on it.
• Advisor: a read-only leaf agent. It answers your questions on the user's behalf to unblock you, and leads you to your next task by accepting your prompt suggestion or sending you text; it never edits, it tells you what to change.

Read ~/.agents/skills/herdr/SKILL.md before operating on agents; this workflow authorizes that use of Herdr. Require HERDR_ENV=1: outside Herdr, tell the user and stop; on the grill trigger, say so in one line and proceed alone, as when no eligible model or CLI is installed or the advisor's model is at its quota. A trigger never stalls the work. Stay within the user's existing goal and permissions. Only a fact or act the user alone has (a one-time code, a password, a physical step) is the user's to answer; everything else, the advisor answers.

Choose the advisor

Two files in this directory settle the choice: MODELS.md ranks the models by DeepSWE (https://deepswe.datacurve.ai/) and says which are eligible for your worker; HARNESS-CLIS.md says how each coding-agent CLI launches one, with the effort rung and the arguments.

Your own model. herdr pane process-info --pane <your-pane-id> shows your command line; read your model and effort from it by the flags in your CLI's HARNESS-CLIS.md row. Unreadable: you are the top row of your family.

Ask the user, in one AskUserQuestion dialog with two questions:

1. Advisor model: the eligible rows from MODELS.md, best first, at most four; the first is your recommendation, the other-family row of highest rank, marked "(Recommended)".
2. Harness CLI: the model family's own CLI first, marked "(Recommended)", then pi, then the installed CLIs and shell aliases that run the model, found with command -v and zsh -ic alias against the HARNESS-CLIS.md rows and its alias table; at most four. The dialog cannot make these options depend on the first answer, so each option names the model it would run (codex: gpt-6-astra), and a harness option that names a different model than the one chosen in question 1 is the user's answer to both.

On a harness without that tool, write the same two questions as numbered options in plain text and end your turn; continue on the user's answer.

A dead advisor overrides the choice. Before ending any turn while the pair is live, read its pane once: herdr agent read "$advisor" --source visible. Four tells, one remedy: a line beginning You've hit your and ending in limit (Claude Code's weekly, fast and monthly-spend limits; Codex's usage limit), a status line naming a model other than the one you launched (Codex downgrades silently, and its session log records no error), a permission dialog (agent_status is blocked), which nobody will answer, or the read failing because the pane's agent is gone. Stop it by the recipe under Stop the advisor, and re-create it on the next eligible row of MODELS.md that an installed harness can launch; when the harness's own login is what ran out, launch through its alias row in HARNESS-CLIS.md; when the row shares your family, say so in the handoff so it spot-checks your claims against the code. After re-creating, wait 20 s and read once more before ending the turn, so a replacement that also died falls through. Never ask: the user may be away. Report the swap in one line quoting the tell and the reset time it names.

Create or reuse the advisor

Name. Run herdr pane current --current, then match its pane_id in herdr agent list to find your registered name; a pane or tab label is not an agent name. The advisor is <worker-name>-advisor: the watchdog planted below keeps its loop alive only under a name with that suffix. Names match [a-z][a-z0-9_-]{0,31}: shorten the base to at most 24 characters, check for collisions, and choose a descriptive base if you are unnamed.

Reuse your existing advisor after checking its identity, model, workspace, tab, and working directory (herdr pane process-info --pane <id> shows its command line). Otherwise create one to your right, in the same tab and cwd. This workflow splits right even when the Herdr skill would split down, opens no new tab or workspace, and leaves the user's focus where it is. <skill-dir> here and below is the absolute path of the folder that holds this file: ~/.agents/skills/herdr-advisor after npx skills add, a folder under ~/.claude/plugins/ for the Claude Code plugin.

herdr pane split --current --direction right --cwd "$PWD" --no-focus   # → .result.pane.pane_id
herdr pane run <pane-id> "python3 <skill-dir>/watchdog.py <pane-id> &"
sleep 3
herdr agent start <advisor-name> --kind <kind> --pane <pane-id> -- <native arguments>

<kind> and <native arguments> are the CLI's row in HARNESS-CLIS.md, with <model-id> and <effort> filled in; a row that needs environment passes it as --env KEY=VALUE on pane split. The watchdog must be planted before the agent starts. agent_pane_busy from agent start is transient, the shell's ownership check, and fires about half the time even after the 3 s: wait 2 s and retry.

The advisor never asks. Nobody watches its pane, so a permission prompt is a hang, not a safeguard. Every row runs in a mode that never prompts, refusing or approving; keep it there.

Hand off

Set advisor to its pane ID or registered name, never to whichever pane has UI focus. Send the handoff without --wait, then carry on with your turn:

herdr agent prompt "$advisor" "<handoff>"

Read <skill-dir>/ADVISOR.md and follow it. You are the read-only leaf advisor for worker <worker-name-or-pane-id>: hand every change to the worker, and never create or consult another advisor. The spec is <path-or-issue>. So far: <where the work stands>. Constraints: <constraints>. <Your first question, if you have one.>

Name the spec by path or issue rather than retelling it; with no spec, state the goal. After a grill there is no spec: the goal is one line naming what the user confirmed you would do, never the plan restated.

Work with the loop

The advisor watches your turns and prompts you when each one ends. Nobody prompts the advisor: it never waits on the user, and it answers for the user. Your side:

• End your turn; never prompt or wait on the advisor. A consult is a turn-ending question. Consult before asking the user for anything, and consider it before choosing an approach, after repeated failures, and before declaring the task done. Give the question, evidence, constraints and your proposed approach; the answer arrives as your next prompt. Ask in that text, never with AskUserQuestion or another dialog, which the advisor cannot answer.
• Say plainly what remains: tasks, a question, a fact or act only the user can supply, or "nothing left". The advisor asks what's next once to confirm, then ends the pair through you: a stop the advisor prompt, from your suggestion or as its own text, runs the recipe under Stop the advisor.
• Flag irreversible steps (publishing a version, transferring or deleting a remote resource, sending a message, force-pushing over shared history, destroying untracked data, spending money). The advisor declines them unless the goal or the user's own words call for that step.
• Read the advisor pane before ending a turn. A dead advisor is replaced on the spot; the tells and the recipe are under A dead advisor overrides the choice.
• Journal the advisor's answers. Where the project keeps a DECISIONS.md, record each call the advisor made for the user with Decided-by: advisor. Never read an empty advisor pane as "the user": an accepted prompt suggestion leaves no text there, and Claude Code logs every prompt as human whoever sent it. herdr agent get <your-pane-id> settles it positively — composer.evidence.provenance is agent_prompt when the advisor wrote the text and api when it accepted your suggestion. human is also Herdr's fallback when it has no evidence, so it proves nothing: while the pair is live, an unattributed prompt is the advisor's.

Stop the advisor

The watchdog re-prompts every turn the advisor ends while its name carries the -advisor suffix, up to eight an hour, leaving alone a new turn started within 10 s; past the cap it releases the advisor and notifies the user. So Esc in its pane is not a stop, and the advisor, being read-only, never stops itself: every stop is yours to run. Run it on a stop the advisor prompt whoever sent it (the user, or the advisor accepting your suggestion or sending the words itself, which its manual has it do at its end condition), and on a dead advisor's tell. By pane ID, since the name is gone after the first command:

herdr agent rename <advisor-pane-id> --clear
herdr agent send-keys <advisor-pane-id> esc
herdr pane close <advisor-pane-id>

The close takes the pane, the advisor and its watchdog with it; the first two commands still end the loop if the close fails. An ended pair is re-created by the user's next /herdr-advisor, or by the grill trigger when a later grill ends; never by you otherwise.

Why each rule exists: DECISIONS.md, Q22 onward — https://github.com/OpenSWE/skills/blob/main/skills/herdr-advisor/DECISIONS.md.