haksolot/ank / skill/herdr
ank-herdr
VerifiedOrchestrate several ank agents in parallel, each on its own task, worktree and branch. Use only inside a herdr-core terminal, when asked to fan ank tasks out across agents in a repository with a .ank/ directory.
ank-herdr
Several agents working one backlog finish sooner than one, and only when nothing they do collides. This file is the policy of the agent that runs the others, the orchestrator. It works no task itself.
The ank skill is the contract and applies here in full: one agent, one working
tree, one identity, and the default branch is where work arrives. This file
adds the orchestration policy only. Herdr-core, driven through hc, is the runtime it was measured on.
Before anything
test -n "$HC_TERMINAL_ID" unset outside a herdr-core terminal: stop and say so, there is no session to drive
hc --skill herdr-core's syntax, from herdr-core itself, for the version installed
This file says what to do and never how hc spells it. Its own manual and
hc <command> --help are the authority on its commands; a copy here would
drift at its next release.
Where the orchestrator stands
the orchestrator claims nothing and records no load: it reads, launches, watches and lands
A claim is the record that an agent is working a task, and the orchestrator works none. Holding one would block a worker from the task it was launched for, and would put the orchestrator's identity on work it never did.
Choosing what runs together
read ank context, ank graph and ank status before the first launch, and before every next one
only ready tasks whose scopes are disjoint run together
name each colliding pair, and keep one task of every pair for a later wave
ank context lists the ready tasks first, ordered by how many others each
would unblock. ank graph says what blocked_by orders, and ank status what
other agents already hold. Parallelism is derived from those three, never
declared: two tasks with no edge between them and no file in common can run
side by side, and nothing else can.
Compare scopes pair by pair, as wide as the criterion implies rather than as narrow as the glob reads: a criterion that speaks about the binary reaches the code that dispatches it and the tests that run it. Say which pairs collide before launching anything, so the human can disagree before the cost is paid.
Fan out no wider than the machine can run the verifiers at once. Every worker runs the full suite at its close, and workers that starve each other turn green work red.
Launching a worker
one worktree, one branch and one ANK_AGENT per worker, cut fresh from the default branch
a worker inherits the herdr-core server's environment, and nothing of the orchestrator's
set ANK_AGENT, TMPDIR and PATH in the command that starts the worker: an export in your own terminal reaches no worker
set ANK_GUARD_EDIT=claim in that command too: an edit no claim of that worker covers is refused
hand it one task to claim, by id, and nothing to land
A terminal started through hc begins from the environment the herdr-core
server was started with, often older than the shell you work in: its PATH may
lack the toolchain, and it carries no TMPDIR or ANK_AGENT of yours. Every
variable a worker needs therefore goes into the command that starts it, which
the runtime runs as a shell string.
Without an identity of its own every worker falls back to <user>@<hostname>,
and the claims of all of them become one agent's: none is arbitrated, and the
record cannot say who did what. A TMPDIR of its own keeps each worker's
scratch apart from the others'.
Disjoint scopes are the whole reason two workers may run side by side, and
under the corpus default of warn a worker editing outside its claim is only
told so, in a message it can scroll past while it rewrites another worker's
perimeter. At claim the edit is refused before it lands. The variable can
tighten what the corpus declares and never loosen it, so the launch decides
this whatever the corpus says. It reaches only a harness whose hooks
ank hooks install claude has put in place; ank help hooks says what they do.
The worker's prompt names the task, says the contract applies, and asks it to
close with ank done and push its branch. Everything else the worker reads
from the task: the criterion, the constraints ank context serves, the method
the task names.
Watching
a worker told to wait for another task stops and reports: send it a new prompt once its blocker lands
A worker does not resume on its own when the work it waits on arrives. Read
what each terminal prints rather than guessing at it, and read a worker's record
with ank log <id>: a release carries its reason, and that reason belongs to
planning, not to a second attempt by somebody else.
A worker stuck in a way its own terminal cannot clear is reported to the human. Driving it by keystrokes is a decision made on its behalf.
Landing
branches land one at a time, each onto a default branch that already holds the one before
remove a worker's worktree once its branch has landed, and not before
Two branches landed at once leave the commits between them unverified, and their conflicts resolved by whichever landed second. One at a time, the default branch is merged into the next branch, its verifiers run again, and only then does it land.
How a branch lands, by pull request, by merge commit, through review, is the repository's own rule; read it where the repository keeps it. When several tasks form one change, the integration task carries the combined verification, and its claimant is a worker like any other.
A worktree holds the only copy of whatever has not landed. Removing it once its branch is on the default branch is the clean end of that worker, and its terminal can close with it.
Ending a run
proposed ADRs and specs wait for accept, a human act, signed: a run never ends on one
The run ends when nothing ready is clear of every collision, or when the human returns. Leave the report: what landed, what was released and why, which pairs were held back for a later wave, and what waits for a human.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |