Overview
Orchestration is the loop that runs between a source arriving and an atom being linked, audited, and promoted. An agent can do most of it: extracting candidate atoms, proposing links, running the auditor, clustering findings. It should not do the parts that decide what is true. This page defines the loop, the handoff points, and the guardrails. The structure it operates on is set in vault-architecture, and the fixed prompts it reuses are in vault-sub-prompts.
Give the agent the spec before the notes
An agent that starts by reading notes infers the conventions and gets them subtly wrong. Load three things first: the vault spec (note types, required fields, folders), the link and tag policy, and the domain framework in play.
With those, an agent can produce a correctly shaped note on the first attempt and can tell whether an existing note is wrong. Without them, it produces plausible notes that fail the audit and quietly teach the vault a second, competing convention. This is the same principle as loading a project’s conventions before editing its code, per claude-code-claude-md.
Run the loop in five stages, with a handoff at each
- Capture. Raw material lands in
00-Inbox/unshaped. No framework, no schema. - Extract. The agent proposes atoms from a source: title as a claim, body in the user’s voice, the supporting quote with its location, a confidence rating, and candidate links. Output goes to the user, not to the vault.
- Link. The agent proposes edges against existing atom titles, each with the sentence explaining the relationship.
- Audit. The deterministic auditor runs, then the semantic pass if it is due. See vault-audit and semantic-audit.
- Promote. The user decides seedling to budding to evergreen, per atomic-notes. This is the one stage that is never delegated.
Each stage produces reviewable output. An agent that runs all five without stopping produces a vault of unverified claims that look exactly like verified ones.
Reuse fixed prompts rather than freehand asks
The recurring tasks in stages 2 through 4 are stable enough to be written once, versioned with the vault, and reused: atom extraction, link suggestion, atomicity check, map emergence, contradiction detection, audit triage, and the decision pre-mortem. The prompts themselves, with their input and output contracts, are in vault-sub-prompts.
Split the work across agents by stage, not by folder
When the work justifies more than one agent, divide by pipeline stage. An extraction agent reads sources and proposes atoms. An audit agent runs the script and triages. A synthesis agent assembles atoms into a draft.
Do not split by folder or by domain. Two agents writing atoms into the same vault will create duplicate claims under different titles, which is the vault equivalent of a duplicate key. If more than one writer is unavoidable, route new titles through one naming authority, as in team-vaults. Agent decomposition patterns are covered in multi-agent.
Guard every bulk write
An agent with file access can restructure a vault faster than anyone can review it. Three standing rules:
- Propose, then apply. Individual fixes get described and confirmed. Silence is not approval.
- Scope freeze on bulk operations. Anything touching more than a handful of files gets an explicit path list, a stated undo path, and a confirmation before execution.
- Version control is the undo. If the vault is not in Git, say so plainly and treat every bulk write as irreversible.
The agent never edits a decision’s pre-decision section, never fills a source or confidence value it cannot derive, and never resolves a contradiction on the user’s behalf.
Make the vault readable to agents that arrive cold
Keep a dashboard note with the query gates and a root map that names the domains, so an agent entering the vault has an index instead of a directory walk. Typed frontmatter, one claim per file, and explained links are what make a retrieved note useful on its own, which is the same property that makes a chunk useful in rag-retrieval.