manthan — coordination system for HERALD work

manthan: the churning. From the myth of the gods and demons together churning the ocean of milk to produce the nectar of immortality. Many hands, shared output, slow-emerging substance.

A simple file-based coordination system that lets many agents (Claude Code subagents, human collaborators, scripted workers) work in parallel on HERALD tasks without stepping on each other.

System, not protocol. The system has one source of truth (TODO.md), one shared filesystem (this directory), and atomic claim semantics via filesystem operations. No daemon, no API, no auth. When this graduates to crossing trust boundaries, then it becomes a protocol — but for now, simple wins.

How it works

herald-protocol/
├── TODO.md                  # the master list — read this first
├── manthan/
│   ├── README.md            # this file
│   ├── AGENT_PROTOCOL.md    # what a worker agent should do, step-by-step
│   ├── bin/                 # five small scripts, all bash
│   │   ├── list             # show pending tasks
│   │   ├── claim            # atomically claim a task
│   │   ├── release          # release a claim back to the pool
│   │   ├── submit           # mark a task done, attach findings
│   │   └── status           # show all claims and recent activity
│   ├── state/
│   │   ├── claims/          # one dir per claimed task (atomic via mkdir)
│   │   ├── findings/        # one dir per submitted task
│   │   └── log/             # plain-text activity log (append-only)
│   └── templates/
│       └── agent-prompt.md  # boilerplate for spawning a worker agent

The atomic claim primitive

mkdir state/claims/T-001 is atomic. First caller wins; everybody else gets EEXIST and knows the task is taken. That's the whole locking scheme. No daemon, no race, no cleanup needed beyond crash recovery.

A claim contains:

owner — agent identifier (free-form: worker-a, claude-2026-05-05-1342, your initials)
claimed_at — Unix seconds
lease_until — Unix seconds (auto-renewable)

If lease_until < now, any other worker may force-release with manthan/bin/release T-001 --force.

Quick start (single human, manual)

cd learning/herald-protocol
manthan/bin/list                          # show what's available
manthan/bin/claim T-001 alice             # claim T-001
# ...do the work, produce findings...
manthan/bin/submit T-001 alice path/to/output/  # done

Multi-claim and force-release:

manthan/bin/status                        # see who's working on what
manthan/bin/release T-001 alice           # give it back to the pool
manthan/bin/release T-007 --force         # take a stale claim

Spawning N parallel workers (the manthan-100 pattern)

To run several agents in parallel from a Claude Code session, spawn them with the Agent tool, each given a copy of templates/agent-prompt.md and a worker name.

Pseudocode of the orchestrator:

for i in 1..N:
  Agent(
    description: "manthan worker {i}",
    prompt: <contents of templates/agent-prompt.md>
            + "\nYour worker name is worker-{i}."
            + "\nClaim ONE task and complete it. Do not pre-claim multiple."
            + "\nWhen done, exit; the orchestrator will spawn another."
    run_in_background: true
  )

The agents independently:

1. Run manthan/bin/list and pick a pending task whose dependencies are done.
2. Try manthan/bin/claim <task-id> <worker-name>. If it fails (someone else got it), pick another.
3. Read the task description from TODO.md. Read any documents the task references (SPEC.md, EXT.md, etc.).
4. Do the work in their own scratch space.
5. Run manthan/bin/submit <task-id> <worker-name> <findings-path>.

The orchestrator (you, or a meta-agent) checks manthan/bin/status periodically, spawns new workers when slots free, and merges findings into the main tree when satisfied.

Findings and the merge boundary

When a worker submits, their output lands in state/findings/<task-id>/. This is the handoff boundary: a worker's job ends when the findings are written there. A separate review step — by you or a reviewer agent — promotes findings to their final location in the tree (e.g. moves state/findings/T-001/ → test-vectors/v0.2/).

This separation matters: it lets workers be cheap and fast (they don't need authority to overwrite the main tree), and lets the human or a reviewer have the last word before changes land.

For really trusted tasks, the worker can be told to write directly into the final path; in that case state/findings/<task-id>/ just contains a RECEIPT.md describing what was changed.

When this should become a protocol

Right now the trust boundary is "everyone with filesystem access." If you ever want:

workers on different machines without a shared FS,
workers from outside parties whose findings you don't fully trust,
crash-resilience beyond best-effort lease expiry,

…then manthan-the-system graduates into manthan-the-protocol. Likely shape: each worker holds a sigil; claims are signed envelopes; findings carry attestations; the audit log lives in a HERALD CT log. At which point the system that built HERALD is itself a HERALD application. That recursion is intentional — it would be the first dogfood test.

For now: filesystem.

A note on the metaphor

manthan is the churning. The image: gods on one side, demons on the other, both pulling on a serpent wrapped around a mountain that pivots in the ocean. Out of the mixture come nectar, poison, gemstones, and the moon. The work is collective, the participants are not all aligned, and what emerges is more than any of them set out to make.

This is a fine model for a multi-agent project on a hard problem. The scripts below are the rope.

See AGENT_PROTOCOL.md for the worker-side instructions, and TODO.md for the work itself.

manthan — coordination system for HERALD work