herdr-orch

Files (63)

• README.org
• SKILL.md
• design.org
• traits.md · references/
• workflow-recipes.md · references/
• AGENTS.md · scripts/
• README.md · scripts/
• bb.edn · scripts/
• contract.md · scripts/docs/
• oh · scripts/
• fake-anthropic.ts · scripts/pi/
• fake-only.cjs · scripts/pi/
• fake-openai.ts · scripts/pi/
• fork-adapter.test.ts · scripts/pi/
• fork-adapter.ts · scripts/pi/
• fork-provider-context.test.ts · scripts/pi/
• measurement-adapter.test.ts · scripts/pi/
• measurement-adapter.ts · scripts/pi/
• measurement-audit.ts · scripts/pi/
• run-tests.ts · scripts/pi/
• runtime.ts · scripts/pi/
• test.sh · scripts/pi/
• cli.clj · scripts/src/herdr_orch/
• core.clj · scripts/src/herdr_orch/
• herdr.clj · scripts/src/herdr_orch/
• ledger.clj · scripts/src/herdr_orch/
• measurement.clj · scripts/src/herdr_orch/
• pi_adapter.clj · scripts/src/herdr_orch/
• smoke.clj · scripts/src/herdr_orch/
• supervisor.clj · scripts/src/herdr_orch/
• traits.clj · scripts/src/herdr_orch/
• traits_cli.clj · scripts/src/herdr_orch/
• delayed-supervisor.clj · scripts/test/fixtures/
• fake-herdr · scripts/test/fixtures/
• fake-pi · scripts/test/fixtures/
• cli_test.clj · scripts/test/herdr_orch/
• core_test.clj · scripts/test/herdr_orch/
• herdr_test.clj · scripts/test/herdr_orch/
• launcher_test.clj · scripts/test/herdr_orch/
• measurement_test.clj · scripts/test/herdr_orch/
• smoke_test.clj · scripts/test/herdr_orch/
• test_support.clj · scripts/test/herdr_orch/
• traits_cli_test.clj · scripts/test/herdr_orch/
• traits_test.clj · scripts/test/herdr_orch/
• traits · scripts/
• advisor.md · subagents/
• base-analyst.md · subagents/
• config.edn · subagents/
• planner.md · subagents/
• researcher.md · subagents/
• reviewer.md · subagents/
• scout.md · subagents/
• simplifier.md · subagents/
• visual-tester.md · subagents/
• worker.md · subagents/
• prompt.md · traits/compact/
• focused.md · traits/
• prompt.md · traits/investigate/
• prompt.md · traits/migration/
• no-bullshit.md · traits/
• …and 3 more

SKILL.md (first lines)

# Herdr subagents

Use the [Herdr skill](https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md) safety rules and verify `HERDR_ENV=1` before delegation. That skill's layout default (a sibling pane, and no new tab unless the user asks) applies to raw layout control only, not to delegation placement: the configured placement is the user's standing request, so a child that `oh` puts in its own tab obeys that rule. `oh` requires Herdr 0.9.1 or newer on both the client and the running server; its preflight reads both from `herdr status --json` and refuses an older or unknown endpoint before allocating anything. For ordinary one-child delegation use `scripts/oh`. The canonical mechanical CLI, ledger, envelope, and exit-code contract is [`scripts/docs/contract.md`](scripts/docs/contract.md), with invocation and test entry points in [`scripts/README.md`](scripts/README.md).

```sh
OH="$HOME/.agents/skills/herdr-orch/scripts/oh"
"$OH" task run scout --task 'Locate the implementation and report paths.'
"$OH" task start reviewer --task-file assignment.md
"$OH" task start --task 'Summarise the build failure.'   # persona-less fresh child
"$OH" task collect <full-task-uuid> --wait --timeout 600000
```

The CLI wraps opaque `--task`, `--task-file`, or stdin text with the persona, delegation, identity, publication, and optional retro instructions. `collect`, `status`, `prune`, `close`, and `continue` require the complete UUID that `run`/`start` emitted -- no prefix is ever resolved. Use `--prompt-extra` for exceptional constraints and `--print-prompt` to inspect the result. Do not reconstruct a raw prompt or result envelope during normal operation.

`oh` also wraps the raw Herdr `pane`, `tab`, `ws`, and `agent` verbs, plus `oh spawn "<shell command>"` for an ordinary command in a new tab (always unfocused; it never delegates), each returning the same JSON envelope. Run `oh --help` for the verb list. The upstream Herdr safety rules apply to those exactly as they do to direct `herdr` use. The wrapper imposes agent-facing defaults that differ from upstream -- pass the flags explicitly when upstream semantics matter ([scripts/README.md#Raw passthrough](scripts/README.md#raw-passthrough)).

An assignment never silently contradicts its persona's declared interaction model: a persona defined to work interactively (for example `planner`) keeps asking the user in its own pane. Question routing is an explicit choice the assignment states -- resolve interactively in-pane, or park questions for the parent -- and is independent of the parent's waiting policy, since every pane is interactive regardless of whether the parent blocks.

## Roster and routing

Definitions are `<name>.md` files discovered in descending precedence: `<git-root>/.agents/subagents/` (project override), then `~/.agents/subagents/` (home override), then the installed skill's `skills/herdr-orch/subagents/` (packaged default). The project copy wins. Read the selected definition. The packaged directory is never projected into `~/.agents/subagents/`, which holds only home-layer overrides.

**Harness is a deployment property. `--model` is the only per-assignment dial.** The child runs its definition's `kind:`, else the harness Herdr measured for the parent -- read that with `oh agent get "$HERDR_PANE_ID"`, never from the harness you believe you are. A `pi` parent read as `claude` declared a requested model unreachable. The four shipped weights are `heavy`, `middle`, `light`, and `feather`. `--model light` is the portable way to ask for a tier. The dial is per spawn and does not persist: a model the user named for one assignment does not carry into the next, so a later spawn takes the persona default unless the user names one again. Everything about how a weight translates lives in the [scripts/docs/contract.md#Model resolution](scripts/docs/contract.md#model-resolution) -- read it when authoring or debugging an override. When delegating, *run* the resolution instead of predicting it: pass the model and spawn, or preview with `--print-prompt`. The `task start` envelope and the ledger entry (`oh task status`) report the translated `model-args` and `effort-args` the child received, so a preview is not needed to confirm routing after the fact. `task run` returns the capture, not the entry. Config is validated before any ledger or pane mutation, so a wrong model fails loudly and costs nothing, while hand-simulating the alias hop and per-kind column lookup has produced a confident wrong answer, a refused spawn, and a routing question escalated to the user that the CLI would have settled. The same holds for every other mechanically-resolved choice -- kind, placement, the `spawns:` allow-list: invoke the resolver rather than reasoning about what it will decide.

Unknown personas require listing the roster (`oh roster`) and asking, not improvising.

Delegate only when the child saves more parent context than its assignment and result cost. Answer inline when you already know the answer or one search finds it. Do not give a `worker` a change whose files you cannot yet name: run a `scout` first, then pass the cited locations. For a broad localisation question, start two `scout` children with different angles (for example definitions and callers, or callers and tests) and combine their citations.

`base-analyst` is a directly usable, read-only analysis persona (default model `light`, a leaf by default): spawn it for an assessment that does not fit `scout`'s codebase-only remit or `researcher`'s external-facts remit. It also exists to be `extends:`-ed by a concrete analysis workflow (for example the `simplify` skill's persona) rather than repeating its assignment/evidence/uncertainty scaffold each time.

`simplifier` is that example: it extends `base-analyst` and applies the `simplify` skill to a declared range. It is not part of a `reviewer` run. When you want both correctness and over-engineering review, start one `reviewer` and one `simplifier` on the same range and collect both. Each keeps its own bar and result.

A persona body may carry `%<name>` trait tokens, substituted from the trait store at spawn into a composed persona file that the child reads instead of the definition. A persona may instead select traits by name through one-line frontmatter `traits: [name, ...]` metadata, appended after the persona body rather than substituted in place. The whole shipped roster selects this way; no packaged persona currently places an inline token, though inline placement stays supported for a directive that must land in the section it governs. Either form carries directives whose prose the persona no longer states itself, so substitution is a boundary rather than decoration. Both forms fail before any ledger or pane mutation on a name that does not resolve or cannot be substituted; they differ on a repeat, which fails inline but is deduplicated in metadata. The store, admission rules, and fragment format are in [references/traits.md](references/traits.md). The mechanics are in [scripts/docs/contract.md#Trait composition](scripts/docs/contract.md#trait-composition).

A delegation request may name a trait with `#trait` shorthand ("Spawn a light worker. #simple"): read this as an instruction to issue an explicit, resolved `--trait NAME` (or frontmatter `traits: [...]`) on the actual spawn, not as text the CLI parses itself -- there is no hashtag parser. This is a different mechanism from the pi extension's `%trait` *interactive* expansion, which rewrites a parent session's own input text in place and never targets a child. [README.org#Shared directives: traits](README.org#shared-directives-traits) has the full routing/composition distinction.

Three packaged traits fit a type of assignment, not a persona, so no persona selects them by default. Add them on the spawn: `--trait investigate` for a debugging assignment to `worker` or a debugging consult to `advisor`; `--trait migration` for a schema, data, API, protocol, configuration, or dependency migration given to `worker` or `planner`; `--trait refactor` for a refactor given to `worker`. `scout` selects `compact`. Add `--trait compact` to another read-only child when you need only locations or counts from it.

When shaping or reviewing a delegated assignment's own scope, apply the same engineering stance every `simple`-selecting persona loads rather than restating it here: [`traits/simple/prompt.md`](traits/simple/prompt.md).

Delegation capability is declared, not assumed: a persona may spawn only what its frontmatter `spawns:` allow-list grants (`planner` grants `scout researcher`; `worker` grants `scout researcher advisor`; every other persona is a leaf), and the value-bearing `--spawns` flag overrides the list for one spawn -- the literal `none` forces a leaf. Nesting is one level absolutely: anything spawned below the root is a leaf regardless of its frontmatter, and a below-root spawn stays blocking and one-at-a-time. `continue` is root-only, so a below-root child is never continued: its spawner captures its result and closes it. The CLI enforces the allow-list and the depth bound mechanically before any ledger or pane mutation.

## Executor tier and advisor strategy

`worker` is the single executor persona, parameterised by `--model`. Pick the tier with `--model` rather than reaching for a different persona. Its `advisor` is a consult-only, read-only grandchild that returns a verdict, a recommended approach, and pass/fail checks, and never spawns an advisor of its own.

**The advisor is opt-in, for a stuck worker only.** There is no routine pre-publish review. A worker consults on a debugging dead end after repeated failed attempts, or on a materially ambiguous high-stakes decision it cannot settle from source. Soft cap three consults. The advisor runs at its own `middle` default, and a caller or worker may raise a single high-stakes consult with `--model heavy`.

**Tier guidance:** light is the efficient default for well-specified implementation work. Feather is a false economy for it -- benchmarked head to head it cost more, ran slower, burned more tokens for an identical score, and accounted for every delegation-protocol failure observed. That benchmark ran feather as Claude Haiku 4.5. Feather now resolves to Claude Haiku 5.5, which has not been benchmarked for this role. Reserve middle and above for work whose difficulty is genuinely established rather than assumed. Measurements and supersession history are in [design.org#History](design.org#history).

The advisor-tier override is a convention, not a structured flag: instruct the worker (via `--prompt-extra`) to spawn its consult with `--model <tier>`, and require it to use `oh task run advisor` (see [README.org#Known gaps](README.org#known-gaps) for what a hand-rolled consult costs).

## Invocation policy

Choose explicitly:

- **Context:** `--context fresh` is the default. A request to "spawn a subagent" means fresh context. A request to "fork a subagent" means `--context fork`: the child inherits your completed earlier turns, not the current turn that delegates (Pi callers and Pi children only; it never silently becomes a fresh child). Nothing after your last completed response is inherited, including `!` command output since then. Put the request and any findings from the current turn that the child needs in the assignment. A fork from your first turn refuses; use fresh context there. A persona named with `--context fork` replaces the role the fork would inherit. Name a roster persona for a role (`task run scout ...`), or omit the persona for a persona-less fresh child that receives the assignment, any explicit `--trait` selections, and the normal launcher guidance but no synthetic role. Absence of a persona is not authority: a persona-less child is a leaf unless the root grants `--spawns`, and below root only a named allow-listed persona may be launched. `--context measurement --measurement-config PATH` runs a Pi subject headless under a detached supervisor with only the configured treatment, tools and the literal assignment: no persona, `--trait`, `--prompt-extra`, `--retro`, `--no-retro` or `--spawns`, and no pane unless `--tab` or `--split` asks for a read-only monitor. The supervisor publishes the result, so `collect`, `collect --any` and `close` work as usual; `continue` and `poke` refuse, and execution success is not an answer-quality score. Detachment is Linux-only. Its request audit covers exactly four Pi APIs (`anthropic-messages`, `openai-completions`, `openai-responses`, `openai-codex-responses`) and any other API fails closed; fresh delegation and forks are unaffected. See [scripts/docs/contract.md#Measurement launch](scripts/docs/contract.md#measurement-launch).
- **Waiting:** `run` blocks for one published item. `start` returns once the prompt is submitted, for later `collect`, or `collect --any` during fan-in. A wait timeout is non-final. Read its `child-status`, then collect again instead of concluding failure or respawning.
- **Placement:** omit `--tab` and `--split` unless the user names a placement for this spawn. An explicit `--tab` or `--split` overrides configured placement. The shipped `:tab-split` default gives a root child its own tab and splits a below-root child from its parent. See the [scripts/docs/contract.md#Placement](scripts/docs/contract.md#placement) for resolution details.
- **Cardinality:** keep at most N root children in flight (default 2). Fan in with `collect --any --wait`, then replace each captured child as capacity opens. Below root, run one blocking leaf child at a time. Its spawner captures and closes it. Run one representative child before a fan-out that shares one design or benchmark premise.
- **Isolation:** use `--worktree <path>` for an existing checkout or `--worktree new` for a managed checkout. A second concurrent write-enabled child gets a managed checkout unless `--worktree` names one; pass `--worktree <repo-root>` when siblings share a tree. Automatic isolation does not make overlapping edits compose safely. Keep sibling edit sets disjoint, name unavoidable overlap, and re-measure the combined parent tree after integration.
- **Integration:** treat a worktree publication's `CHECKPOINT` as the child's branch tip at that gate. Inspect reconciliation, resolve remaining dirt, and integrate explicitly. `oh` never merges, rebases, pushes, or deletes the branch.
- **Lifecycle:** capture closes nothing. After each capture, choose `close <full-task-uuid>` or `continue <full-task-uuid> --task '<next assignment>'`. Use `collect --close` when the close decision is already known. Whoever spawns a child closes it.

Continue when the follow-up depends on the child's existing context. Respawn for unrelated work, a different persona, or independent Class C validation. Before you continue a child, read its context use; above about 70%, close it and start a fresh worker with a handoff assignment instead. The CLI owns continuation preconditions and refuses unsafe reuse. See the [scripts/docs/contract.md#Continue](scripts/docs/contract.md#continue).

For root-owned staged delegation, repeated measurements, evidence retention and the separately approved live context smoke, use [references/workflow-recipes.md](references/workflow-recipes.md). The recipe is policy over existing lifecycle verbs, not a workflow engine.

## Process retrospectives

Use `--retro` or `--no-retro` only when overriding the persona policy for this spawn. Otherwise the CLI resolves persona frontmatter `retro:` and then its enabled default. `scout`, `researcher`, and `advisor` currently opt out. If no `retro` skill is installed, default/frontmatter enablement degrades to disabled. An explicit `--retro` fails fast.

A gated-in child applies steps 1--2 of [`retro`](../retro/SKILL.md), using that skill's threshold. Surviving one-line candidates arrive in the result's optional `PROCESS:` section and the ledger `:envelope`. No candidates is a valid result. The ledger's best-effort `:child-session` is the transcript reference for any manual follow-up after pane closure. Exact precedence, fields, limits, and section grammar belong to the [mechanical contract](scripts/docs/contract.md).

Treat process candidates as testimony and scan input for your own retro. A child must not act on its own candidates: it does not choose a destination, write to instruction files, task systems, or any other durable store, or invoke whatever persistence tooling the installation provides. The parent owns verification, deduplication, approval, and persistence.

## Completion and pane safety

A validated terminal item in the parent-chosen `RESULT` stream is the only completion signal. Never use `agent read`, terminal history, prompt text, a visible final summary, or a `WAITING` item as completion. The child publishes a terminal result with the injected launcher:

```sh
"$HERDR_ORCH_BIN" task publish --status COMPLETE --summary 'Concise result.'
```

`BLOCKED` means a genuine resumable dependency. A decision that only the parent can make is such a dependency, for example a `worker` reporting that the correct change needs more scope than the assignment allows: decide the scope, then `continue` or respawn. It is not a failure. `FAILED` means the child could not recover after reasonable retries. Read the published summary before you re-prompt or respawn.

For a settled child with no valid publication, use `oh task poke <full-task-uuid>` before you respawn. If an `invalid` capture arrives while the child is still `working`, let it settle and collect again. If a settled child's `RESULT` contains prose, capture it as invalid, then use `poke`. Never adopt that prose as the result.

To retire a newest round whose child published nothing and should *not* be resumed, use `oh task close <full-task-uuid> --abandon` on that newest round's UUID. It retires the ledger round only when the child is observed `idle`/`done` at its recorded pane or its process is proved stopped; it sends the child nothing, closes no pane, and fabricates no result. A `blocked` child is refused: dismiss its dialog or stop it yourself, then retry. A `working` or `unknown` child is refused too; wait for it to settle or use `poke` if you want it to publish. The pane stays yours to clean up ([scripts/docs/contract.md#Close](scripts/docs/contract.md#close)).

Capture before you close or continue. Never close user or other-agent panes, kill a parent, or stop the Herdr server. Use `orphans` only for children whose owning parent session has ended. Read per-child outcomes from bulk close commands instead of trusting their aggregate exit status. Guard and reason details are in the [scripts/docs/contract.md#Close](scripts/docs/contract.md#close) and [scripts/docs/contract.md#Poke](scripts/docs/contract.md#poke).

Never bulk-delete the shared ledger. Use `prune` for your stale entries, `compact` for closed-round envelope bulk, and `harvest` for this session's process candidates.

Surface validated collect-time `artifact-links` before you discard child-pane context. Advisory publication links are context, not evidence that an artifact exists.

Use explicit IDs and response IDs, never focused UI state. Labels are display metadata and never replace unique agent names.

## Assignment premises

Name the base ref or commit a review or implementation assignment is scoped against, measured with `git log`/`git status` at composition time. Asserting commit state in prose ("nothing is committed") mis-scopes the work when it is wrong, and the child has to re-derive the range anyway.

A worker whose assignment forbids parent-status changes must pass `--no-promote` to `ot status` for its scoped tasks, including `--cycle` transitions. Default STARTED transitions promote TODO ancestors; the opt-out leaves them unchanged. The worker still manages only its assigned tasks, not parent closure.

A parent assignment must not assert an unmeasured, load-bearing premise -- a baseline, failure attribution, or suspected cause -- as settled fact. Either verify it before composing the assignment, or label it `unverified:` and instruct the child to establish it empirically before adopting that framing. Measurement of mutable state is a snapshot: after intervening edits or lifecycle/configuration changes, re-measure it before reusing it as an assignment premise, review exclusion, or causal frame. A baseline is measured on the pre-change tree: a figure measured after the change is not a baseline, and a suite that is green against it evidences no failures rather than preserved coverage. This is the reciprocal of Trusting a result below: that section bounds probes on claims flowing child to parent. This bounds claims flowing parent to child.

A tool's error text naming its own cause is such a premise. Reproduce the failure with and without the suspected flag before you attribute it to an account, a provider, or a plan limit. A headless `pi --print` refusal whose message described third-party usage billing was caused by `--no-extensions` disabling the provider-auth extension. The misreading was recorded as a plan assumption and mis-scoped a full benchmark round before a later task disproved it.

## Trusting a result

Mechanical validation proves identity and envelope shape, never content truth. Weigh each claim by its consequence class.

**Class A -- transient.** A validated envelope needs no routine probe unless it conflicts with other evidence. Example: a scout's subsystem-behavior account used only to pick an in-flight approach.

**Class B -- persisted or load-bearing.** Probe up to 3 targeted checks per claim -- re-run a command, re-count a total, open a cited file -- before adopting it. Example: a claim persisted to a task, record, spec, commit message, or user report. A claim outside that budget, or genuinely uneconomical to probe, stays attributed to its source or flagged uncertain, never adopted as parent-verified fact. A failed probe stops reliance on the disputed claim. Escalate only as far as the disagreement requires, never into full re-ingestion. A figure you derive from a child's self-reported residual or proportion is a new claim, not a restatement of the child's: measure it yourself, or attribute it to the child. A density figure derived this way was persisted as measured and was wrong, because the child had reported a residual of about 15 words for a paragraph that measured 124.

**Class C -- destructive or closing.** A destructive action, feature closeout, or top-level lifecycle closure requires independent validation by the root itself or by a validator **spawned fresh for that closeout**. Never the implementing worker reaffirming its own result, and never a child continued from an earlier round of the same work: a child that already implemented or reviewed this change carries its own conclusions into the new round, which the mandatory revalidation clause in every continuation prompt mitigates but cannot remove. Independence here is a property of the spawn, not of the instruction. Example: marking a parent task DONE after a delegated implementation lands. A worker manages its own scoped plan tasks but never closes the parent task or prunes the final record.

One validator's approval is weak evidence on a subtle surface: two reviewers of this skill's own lifecycle rewrite returned opposite verdicts on an identical assignment (measurement in [`design/log/2026-08-06-herdr-orch-support-resident-reviewers-fo.org`](../../design/log/2026-08-06-herdr-orch-support-resident-reviewers-fo.org)). For a Class C closeout, prefer two independent validators and expect disjoint findings. Treat a lone APPROVED as unfalsified rather than validated. Measured again on the trait-composition closeout (2026-08-11): two reviewers on one assignment at different tiers overlapped on only 2 of 6 findings, and each uniquely caught something the other missed -- a trust-boundary bypass in one case, a test broken by a documentation edit in the other. One reviewer would have shipped whichever it missed.

From cormacc/dotagents, MIT.

More from cormacc/dotagents