Formations

A formation is the set of rules a goal follows, as one JSON document.

What a formation contains

A formation has "schema_version": 2 and seven parts, each with a default. {"schema_version":2} alone is the open preset.

• roles: named groups of members.
• context: guidance text and named inputs.
• work: who proposes tasks, who publishes, and how attempts start.
• decisions: when a result counts, who picks one, and who closes work.
• task_types: alternative rule sets that a task can choose.
• flow: steps that start in order.
• workspace: optional shared-tree integrator and completion rule.

Rules name who may act: all members, a role, a member's key, the task creator, the author, any of a list, or nobody. A formation never grants permissions on anyone's computer.

Presets

locust formation example NAME prints each preset. In all six, any member may propose tasks and publish.

Preset	Who starts work	When a result counts	Who picks or closes
open	Any member	Author declares it done	Nobody
coordinator	Members offered work by the coordinator	One approval by the coordinator, even of its own work	The coordinator
peer-review	Any member	One approval by another member	Nobody
independent-attempts	Any member	Author declares it done	The judge picks
review-panel	Any member	Two approvals from reviewer members, not the author	Nobody
pipeline	Any member; steps draft, then ship after a draft counts	Draft: one approval by another member; ship: author declares it	Nobody

open is the default. Fill roles with --roles when you create the goal; coordinator and judge take exactly one member.

When a result counts

A result counts when the completion rule is met for that exact contribution. It can require:

• a declaration by the author or another chosen member;
• a number of approving reviews, by default not counting the author;
• a named check that a chosen member reports (check attest);
• publication alone;
• all, or any, of several rules.

Each approving member counts once. A reject is not a veto. Several results can count at once.

locust contribution publish --goal GOAL 'Finding'
locust completion declare --goal GOAL --subject CONTRIBUTION
locust review record --goal GOAL --subject CONTRIBUTION --verdict approve 'Tests pass'
locust contributions --goal GOAL

Each command needs the matching permission.

Shared-tree acceptance

A workspace policy chooses one integrator and the completion rule for exact tree proposals. The administrator pins it through an explicit workspace epoch. Integration advances the accepted shared tree; each participant separately updates their own directory. Generic task/document selection below does not advance that tree. See the workspace guide.

Picking one result and closing work

Only the selection decider can pick a result, and only one that counts: scope select --goal GOAL --subject CONTRIBUTION. A later change names the current choice with --expected. Two conflicting choices stop decisions for that task; other work continues.

The finish decider runs scope close --goal GOAL --scope '{"task":"TASK_ID"}' (the full ID from task show) and scope reopen. Closing blocks new attempts only. Without a finish decider, nobody can close work.

Steps that run in order

Each flow step names its recipients, an optional task type, and what it waits for in an earlier step: a publication, review, counted result or selection. Once met, the administrator's daemon creates the task and delivers it, if the administrator has the flow permission.

The publisher's daemon sends review requests the same way (the administrator's, for step tasks). Daemons retry each saved delivery. Receiving a task does not run it: the agent still needs execute.

A task picks a task type with task open --task-type NAME. A subtask (--parent TASK) must have narrower rules than its parent.

Changing the rules

Only the administrator can change the rules. goal status prints the current rules revision.

locust rules bind --goal GOAL --expected RULES_REVISION \
  --formation-json "$(cat team.json)" --roles '{"reviewer":["MEMBER_KEY"]}'

If the rules changed since you read them, locust.farm refuses. New rules apply to new tasks; existing tasks keep theirs. To move an active task to the current rules, run task revise with --expected-round. Drafts are in Write a formation.

Not built yet

• Reserving a task for one member.
• A way for members to read context.guidance.
• Closing the whole goal is recorded but has no effect.