manthan — Agent Protocol · AI Initiative review

manthan — Agent Protocol

What a worker agent does, step by step. This is the contract.

Inputs you receive

A worker name (e.g. worker-3, alice, claude-A).
Read access to the entire herald-protocol/ directory.
Permission to run scripts in manthan/bin/.
Permission to write to manthan/state/findings/<task-id>/ once you have a claim.

Inputs you do NOT receive

A pre-assigned task. You pick one yourself, atomically. This avoids orchestrator-bottleneck.
Authority to overwrite the main tree (SPEC.md, EXT.md, etc.) directly. Findings go to your sandbox; review happens later.

The seven steps

1. Orient yourself

Read TODO.md. Read manthan/README.md. Read whichever of SPEC.md, EXT.md, CHARTER.md, THREATS.md are relevant to the kind of task you're about to claim. Do not claim before you understand the surrounding work.

2. Pick an unclaimed task whose dependencies are done

Run manthan/bin/list. The output shows pending tasks and their dependency status. Pick one where:

Status is pending (not claimed or done).
Every entry in Depends-on is done. If any dependency is still pending or claimed, skip this task — pick a different one. (The orchestrator will spawn you again later.)

Prefer Tier 1 tasks unless the work needs you specifically.

3. Claim it

manthan/bin/claim <task-id> <your-worker-name>

If the script exits 0, the task is yours and a state/claims/<task-id>/ directory now exists with your details. If exit non-zero, someone else claimed it during your read — go back to step 2.

A claim has a 4-hour lease by default. If your work will take longer, extend with:

manthan/bin/claim <task-id> <your-worker-name> --extend 8h

4. Do the work

Work in state/findings/<task-id>/ (your sandbox). Do not modify files outside it without explicit instruction.

If the task description references documents (e.g. "implement [SPEC §3.3a]"), read those documents as written today — do not assume they match your training. Documents evolve.

If you discover the task is blocked by something not listed in dependencies — a missing primitive, an ambiguous spec sentence, a needed decision from the human — write your finding to state/findings/<task-id>/BLOCKED.md describing the blocker, and run:

manthan/bin/release <task-id> <your-worker-name> --status blocked

Releasing-as-blocked is honourable. Submitting partially-working code as done is not.

5. Self-review before submitting

Before you submit, ask yourself:

Does it match the spec section the task referenced? Quote the relevant lines in your findings.
Did I add anything not asked for? If yes, justify it in state/findings/<task-id>/NOTES.md or remove it. (See the "no scope creep" rule below.)
Are there test cases or worked examples? For code tasks, include at least three: success, failure, edge.
Would another worker be able to review and trust this? If not, your job isn't finished.

6. Submit

manthan/bin/submit <task-id> <your-worker-name> state/findings/<task-id>/

This:

Writes a submission receipt with timestamp and worker name.
Marks the task done in TODO.md (atomically — the script handles the edit).
Releases the claim.
Logs to state/log/activity.log.

After submitting, you are done with this task. Do not claim another in the same session. The orchestrator will spawn a fresh worker for the next one. (One-task-per-worker keeps work units clean and review boundaries crisp.)

7. Exit cleanly

Print a one-paragraph summary to stdout:

Task ID
What you produced
What you decided NOT to do, with reasoning
Any follow-on tasks you noticed should be added to TODO.md

Then exit. Do not continue the session.

Rules

No scope creep

If you notice something related but not requested, write it as a follow-on task in your summary. Do not silently expand your work. Scope creep makes review harder and breaks the parallelism: another worker may already be claiming the work you're inadvertently doing.

No silent reformatting

If you touch a file you weren't asked to touch — even to fix typos — note it explicitly. Reviewers care.

No deleting other workers' findings

state/findings/<other-task-id>/ is read-only to you, period. If you think another worker's submission is wrong, write a critique to your own findings; don't edit theirs.

No racing

If you find a task in claimed state and the lease is still valid, do not force-release it. Pick something else. Force-release is only for stale leases or with explicit human authorisation.

Use absolute file paths in findings

When your findings reference files, use absolute paths (/path/to/herald-protocol/...) so reviewers can copy-paste. Relative paths are ambiguous across worker workspaces.

Cite specifically

If a finding rests on something in SPEC.md or EXT.md, quote the line and the section number. "Per [SPEC §3.6]: 'All Ed25519 signatures...'" is reviewable. "I followed the spec" is not.

Output expectations by task type

Task type	What "done" looks like
Code (T-002, T-003, T-005…)	A directory with the implementation, a `README.md` explaining how to run it, at least 3 tests or worked examples, and a `RECEIPT.md` quoting the spec sections you implemented.
Test vectors (T-001)	The vectors themselves (binary or hex), a generation script that re-derives them, a verification script, and a one-page document explaining each vector's purpose.
Documentation (T-012, T-013, T-018…)	The document, plus a `RECEIPT.md` listing the source documents you read and any cross-reference checks you performed.
Research (R-201…R-213)	A markdown report with: question, what you found, citations (URLs + retrieval date), what you couldn't determine, recommended next steps.
Audit (D-301…D-305)	A markdown report with: scope, methodology, findings (numbered), severity for each, proposed remediation.

How to handle ambiguity

When the spec is unclear:

1. First, see if THREATS.md or the reviews/ directory clarifies — the original reviews captured a lot of decisions that didn't make it into prose.
2. Second, write your interpretation in a state/findings/<task-id>/INTERPRETATION.md and proceed under it. Note the ambiguity in your summary so the human can confirm.
3. Do not invent answers without flagging them. The INTERPRETATION.md is part of the deliverable, not optional.

If the ambiguity is severe enough that you can't proceed sensibly, release-as-blocked (step 4 above) and describe the ambiguity precisely.

What a good submission looks like

A reviewer skimming state/findings/T-001/ should see:

T-001/
├── RECEIPT.md           # 1 paragraph: what, why, spec sections
├── README.md            # how to use what you produced
├── NOTES.md             # decisions, surprises, follow-on tasks (if any)
├── <the actual deliverable>
└── INTERPRETATION.md    # if and only if you had to interpret an ambiguity

The reviewer reads RECEIPT first, NOTES second, then the deliverable. If they need INTERPRETATION, they read it. If they don't see RECEIPT, they bounce the submission.

What if I'm a Claude subagent specifically?

You probably are. A few extra notes:

Your context window is finite. Don't read every document; read what the task requires.
Use the Read tool with offsets for large documents (SPEC.md is ~530 lines, CHARTER.md is ~1019, EXT.md is ~920).
Use parallel tool calls when reading multiple independent files.
If you spawn sub-agents of your own, you become an orchestrator — track their claims like a coordinator would.
When you finish, your final user-facing message should be the summary from step 7. Keep it tight.

This is the contract. The work waits.

manthan — Agent Protocol