Multi-agent work
Ank is built for several agents working one repository at once, each taking a task the others can see is taken. This page is what handing the loop to an agent involves, and what running several of them actually requires. The skills that teach an agent the loop are installed by the routes in Install, and claims and identities, which do the arbitrating, are Claims and identity.
What the agent is taught
skill/SKILL.md is the contract an agent loads, and six siblings sit beside it.
Five carry a policy each, planning, drift audit, the autonomous loop, test-first
implementation and diagnosis, loaded when the activity calls for them. The sixth,
ank-herdr, teaches the agent that runs the others from a herdr-core terminal rather than
one doing the work (below). The contract names all
six, so an agent that loaded only it knows each one exists.
One convention it carries is worth knowing before you watch an agent follow it:
.ank/ is opaque to an agent, the way .git/ is. Reading goes through
ank show, ank find and ank context; writing goes through the verbs. The CLI
knows what the files do not: the context budget, the frozen criterion, who holds
which claim. A human with an editor keeps every power they had.
What that costs a session is the frontmatter, not the page. A skill’s name
and description are always loaded, somewhere between fifty and eighty tokens
each; a body is read when its skill is invoked. Install
shows the projection per skill.
The methods a corpus uses
A task can name the sibling its work calls for with ank new task --method tdd,
and ank context prints that name beneath the criterion once the task is
claimed. A sibling that opens under a claim writes an entry saying so with
ank log --method tdd, titled with its name and kept apart from the work trace
(ADR-a8f9c603a0e7). The designation is read, never enforced, and ank skills is where it
is read: inside a corpus it prints the catalogue and then a second block. On a
corpus of three tasks – one designating tdd whose holder loaded it, one
designating diagnose whose holder never did, and one designating nothing where
tdd was loaded anyway – the block reads:
METHODS
diagnose designated 1 fired 0 undesignated 0
drift designated 0 fired 0 undesignated 0
herdr designated 0 fired 0 undesignated 0
loop designated 0 fired 0 undesignated 0
plan designated 0 fired 0 undesignated 0
tdd designated 1 fired 1 undesignated 1
designated counts the tasks naming the sibling, fired those of them carrying
its entry, and undesignated its entries on tasks naming none. ank skills --json carries the same counts as integers. The numbers are read from the
corpus, printed to whoever asks, and sent nowhere; outside a corpus the verb
prints the catalogue alone.
One agent, one working tree, one identity
The nominal case is a tree per agent, a clone or a git worktree, each on its
own branch cut fresh from the default one, and each session with an
ANK_AGENT of its own. ank status names the drift from the default branch,
and a stale base turns a green tree red elsewhere.
Several agents in one tree runs, and it is a degraded mode rather than the
design: two sessions sharing a tree and an identity share a claim instead of
arbitrating over it (Claims and identity
shows what that looks like). What arbitrates properly is a git worktree per
agent, because every worktree of a repository shares refs/ank/, so the
compare-and-swap settles them. Separate clones are arbitrated only when there is
a remote, which is what the push carries: origin, or a remote named ank
when there is one, which then carries the claims alone
(Where claims travel).
Take the task that cannot collide, or take none. status says what another
agent holds; claim names a live claim whose scope intersects yours and takes
the task anyway (ADR-052accd6e3b2), a fact to read and not an error to refuse;
graph shows what blocked_by orders. When nothing open is both unblocked and
clear, an idle session is cheaper than two agents rewriting one perimeter.
Parallel work and integration
The section above says who works where. This one assembles the whole run: several tasks, several agents, one change landing on the default branch.
Parallelism is derived, not declared. blocked_by is the only relation
between tasks, and it is the only thing that serializes work. Tasks whose
blockers are finished are ready together, and ank context computes that
mechanically: every open task in the perimeter, the ready ones first, ordered by
how many other tasks each would unblock. Do not serialize independent tasks
because they belong to the same change. If the order matters, that is a
blocked_by; if there is no blocked_by, the order is a fiction. ank graph
prints the DAG when you want the shape rather than the next move.
One branch per task. Each agent claims its task, works in its own tree on
its own branch, and finishes there. ank done proves the task in the working
tree it ran in: the verifiers ran against those files and the proof records
their hash. It does not prove the change merges, or that the combined system
works. Until the merge lands, the claim ref stands as a completion record, so no
other tree takes the task for free (Claims and
identity).
Integration is a task. When several tasks form one change, the whole is
verified the way the parts were: an ordinary task, blocked_by each part, with
its own criterion and its own verifiers. This is the spec’s model rather than a
workaround: blocked_by is a DAG with no rollup precisely because a parent
that completes when its children do is completion without proof, and the seam
between the parts is exactly where integration regressions live. The
integration task becomes ready when the last part finishes; whoever claims it
merges the branches, runs the combined verification, and records done like
any other task.
Where the branches meet is git’s business, and both shapes are legitimate:
- Independent tasks merge to the default branch directly. Two tasks that share nothing need no ceremony between them, and no integration task either.
- A multi-task change goes through an integration branch. Branch it off the default branch, merge each task’s branch into it, resolve conflicts there, and point the integration task’s verification at the combined result. The default branch receives one verified change instead of three partial ones.
What ank will not do. No verb creates a worktree, names a branch, or merges
one. Tasks, claims, criteria, dependencies and proofs are ank’s plane; branches,
worktrees, merges and history are git’s, and git is already good at them. The
one place the planes touch is accept, and it touches them by writing a ref,
refs/ank/ratify/<id>, never a branch or a commit.
Running agents from herdr
skill/herdr (ank-herdr) is the policy for running this page from a single
orchestrating agent inside a herdr-core terminal
(ADR-2fc9b88cc0bd). The orchestrator claims nothing: it reads ank context,
ank graph and ank status, names the pairs of ready tasks whose scopes
collide, gives every other ready task a worker of its own – one worktree, one
branch and one ANK_AGENT, set with TMPDIR and PATH in the command that starts the
worker, which inherits the herdr-core server’s environment – and
lands the finished branches one at a time. It teaches the ank layer only, and
leaves herdr-core’s own commands to hc --skill. Nothing in it is a verb: ank
still creates no worktree and merges nothing; the orchestrator does, with git
and hc.
Dispatching across repositories
When the work spans several repositories, a backend and the client that calls it, each one keeps its own corpus, its own claims and its own workers, and Several repositories is how one corpus reads another. An orchestrator dispatching across them runs the same loop in each repository, plus four reads that look over the boundary from the one it stands in:
ank status --peersadds each declared peer’s live claims toelsewhere, addressed<id>@<peer>, so a worker about to start inwebsees what is held inapi.ank find --peersandank context --peersadd each peer’s rows and ready tasks, read at the peer’s default branch.ank check --peersmakes an unreadable declared peer a fault, so the orchestrator learns before dispatching that a sibling checkout is missing.ank claim, run by the worker, prints the constraints a peer binds onto the task’s scope in a section of their own, andank donestates which of them moved since.
Claims and writes stay per repository: a worker claims and closes in the
repository its task lives in. A blocked_by naming a peer task releases only
once that task is done on the peer’s default branch, so the orchestrator lands
the peer’s branch first, and the waiting task becomes ready in the order the
merges arrive.