Skip to content

haksolot/ank / skill/herdr

ank-herdr

Verified

Orchestrate 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.

FileKindSize
SKILL.mdskill md6.1 KB
---
name: ank-herdr
description: Orchestrate 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.
metadata:
  revision: "0bce41153716"
---

# 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.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall