workflow-herdr · diff
git:20260822.20931e4 to git:20260920.ab2f9ae
73 added, 35 removed. Audit A to A.
---
name: workflow-herdr
description: >
Start a Herdr work run for a change. Use when starting work, doing a
task in Herdr, splitting work across panes, or chatting from a Herdr
terminal - even if they just say do this. Do NOT use for a solo one-pane
edit, headless delegates, or product job queues.
---
# Workflow Herdr
- Herdr coordination lives in its own local directory. Project requirements,
- decisions, plans, and durable state stay in the systems the project already uses.
+ This is **not** the `herdr` skill. `herdr` is the multiplexer. This skill is
+ the workflow overlay: doctor, detection, graph, layout.
- - Config: [workflow.yaml](workflow.yaml)
- - Project manifest example: [assets/workflow.example.yaml](assets/workflow.example.yaml)
- - Project workflow profile: [references/project-workflow.md](references/project-workflow.md)
+ Python scripts do not loop `herdr agent prompt`. Herdr is the runtime.
+
- How to run: [references/run.md](references/run.md)
+ - Config: [workflow.yaml](workflow.yaml)
+ - Project profile: [references/project-workflow.md](references/project-workflow.md)
## Do
- Brain owns the conversation with the human: business requirements, intent,
- feedback, and authority. Repo docs are context, not the request.
+ If `HERDR_ENV` is not `1`, stop.
- If this process is not a Herdr pane, stop.
+ Brain is this chat. Intent is what the human typed here.
- Before sizing, load `.herdr/project.md`. If it is missing, build it from the
- project's instructions, templates, integrations, and representative active and
- completed work using the project workflow reference. This is a short cached
- understanding, not a new methodology. A directory name alone is not evidence
- that the project uses that directory as a current source of truth.
+ **1. Doctor first** — before sizing, before any pane/tab/workspace:
- Resolve `workflow.yaml` with the optional project manifest at
- `.herdr/workflow.yaml`. The manifest overrides global roles, CLIs, volumes,
- guards, task states, and layout for this project only. Merge mappings
- recursively; replace lists and scalars. Treat the resolved result as the run
- configuration.
+ ```text
+ python scripts/bootstrap.py --project <abs>
+ # or: python scripts/bootstrap.py --project <abs> --fresh
+ ```
- Brain chooses exactly one size before creating topology:
+ That resolves `.herdr/workflow.yaml` over the global default, then live-checks
+ every startable seat: Herdr protocol (`herdr status`: `restart_needed`,
+ `private_protocol_compatible`, `server_binary_stale`), Herdr `--kind`, CLI
+ binary, **model inventory**, **reasoning effort**. If `ok` is false, print
+ `fixes` and stop. Protocol mismatch fix is `herdr server stop` then start
+ `herdr` again. Do not invent another model. Do not reuse a random idle agent.
- - small: Brain -> Worker;
- - medium: Brain -> Orchestrator -> Dispatcher -> Worker;
- - large: Brain -> Orchestrator -> worktree N -> Dispatcher N -> Worker N.
+ Slow CLI inventories (`devin models list`) are cached under
+ `%LOCALAPPDATA%/workflow-herdr/probe-cache.json` (override
+ `WORKFLOW_HERDR_PROBE_CACHE`, TTL `WORKFLOW_HERDR_PROBE_TTL`, bypass
+ `--fresh` / `WORKFLOW_HERDR_PROBE_FRESH=1`). Codex models come from
+ `~/.codex/models_cache.json` when present, then `codex doctor`, then YAML
+ `known_models`.
- Small starts work immediately. Medium and large follow the profile's routing,
- artifact, lifecycle, hierarchy, and tooling rules. Keep Herdr coordination
- state separate from durable project state. If the profile says a system is not
- used, do not create it. If the workflow remains unclear, keep context in agent
- handoffs and ask before creating or changing project artifacts.
+ **2. Detect with your judgment, not folder names.** `bootstrap` writes a
+ heuristic `.herdr/detection.yaml` draft (`systems.*.sot` from path clues,
+ `draft: true`). It does **not** size. Read the excerpts. Confirm or correct
+ source of truth. Fill `sizing_graph` + `sizing_reason`. Low confidence → ask
+ the human. Then refresh `.herdr/project.md`.
- Resolve blocked or missing work before sizing. Count runnable workstreams, not
- issue numbers. Before creating any pane, tab, workspace, or worktree, run the
- preflight command from the run reference. If it fails, stop without mutating
- topology. Use only panes created by this run; assign role names only to agents
- started in those panes.
+ **3. Size from detection**, not vibes. `sizing_graph` + `sizing_reason` are
+ required. small / medium / large (or a custom overlay graph). Count runnable
+ workstreams. Blocked external work first.
- How to start seats, watch a worker, and move task state is in the run
- reference. Load only the section for the chosen volume. Do not open the
- agent-runtime note unless the human asked.
+ **4. Init + one-shot layout** (medium/large):
+
+ ```text
+ python scripts/init_work.py --project <abs> --change <change> --volume <graph>
+ python scripts/workflow_guard.py doctor --project <abs> --change <change> --volume <graph>
+ python scripts/layout_graph.py --project <abs> --change <change> --volume <graph>
+ ```
+
+ Do not hand-split panes. Do not `pane run` a CLI. `layout_graph` splits, records,
+ `agent start --kind`, labels, and rolls back unstarted panes. The seat brief
+ (`nodes.*.brief`) is the CLI's initial prompt, passed after `--` at start.
+ Do not `agent prompt` the brief. Codex often sits on the workspace trust
+ dialog while Herdr reports `idle`; `agent prompt` then sends Enter and Codex
+ quits. `start_seat` dismisses that dialog with `agent send-keys enter`
+ (Yes, continue) before it returns. Every later packet goes through
+ `prompt_seat.py` (one prompt, no loop): it refuses a shell pane, dismisses
+ trust, then prompts. Overlay a project brief via `.herdr/workflow.yaml`
+ `nodes.<seat>.brief`.
+
+ Small: layout worker only, no run files.
+
+ Large: `identity.streams` or `tasks.workstreams` (≥2). One Orchestrator in the
+ current workspace. Each stream gets its own worktree plus a Dispatcher+Worker
+ pair (`number` = stream index, cwd = that worktree). `layout_graph` used to
+ start a single trio in the last worktree; that was a bug.
+
+ **5. Handoff.**
+
+ ```text
+ python scripts/prompt_seat.py --project <abs> --change <change> --seat orchestrator --from brain --text "<intent>"
+ python scripts/orchestrate.py --project <abs> --change <change> --from brain --on goal_created
+ ```
+
+ `--from brain` never waits. Dispatcher/Orchestrator waits use
+ `watch.worker_timeout_ms` / `watch.dispatcher_timeout_ms` (20 min). A wait
+ timeout is not death: `prompt_seat` returns `timeout: true` and `agent_alive`
+ if the pane still hosts the agent. Stay with the human.
+
+ Never export empty `HERDR_SESSION`. Never mix `--machine` and `--session`.
+ Idle/done is not acceptance. Receipts are.