--- title: "Vault Orchestration" slug: "vault-orchestration" category: "knowledge-vaults" tags: ["knowledge-vaults", "ai-agents", "orchestration", "workflow", "automation", "prompts"] status: "stable" last_updated: 2026-08-29 summary: "The loop an agent runs against a vault: capture, extract atoms, propose links, audit, and hand judgment back, with guardrails on every bulk write." related: ["[[knowledge-vaults/vault-architecture]]", "[[knowledge-vaults/vault-audit]]", "[[knowledge-vaults/semantic-audit]]", "[[knowledge-vaults/atomic-notes]]", "[[knowledge-vaults/vault-maintenance]]", "[[ai-agents/multi-agent]]", "[[prompt-engineering/prompt-chaining]]"] --- ## 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 [[knowledge-vaults/vault-architecture]]. ## 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. Same principle as loading a project's conventions before editing its code, per [[ai-agents/claude-code-claude-md]]. ## Run the loop in five stages, with a handoff at each 1. **Capture.** Raw material lands in `00-Inbox/` unshaped. No framework, no schema. 2. **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. 3. **Link.** The agent proposes edges against existing atom titles, each with the sentence explaining the relationship. 4. **Audit.** The deterministic auditor runs, then the semantic pass if it is due. See [[knowledge-vaults/vault-audit]]. 5. **Promote.** The user decides seedling to budding to evergreen. 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. ## Write the sub-prompts once and reuse them The recurring vault tasks are stable enough to be fixed prompts rather than freehand asks. Keep them in the vault, versioned with it. - **Atom extraction:** one idea per claim, title as a full claim sentence, body of two to five sentences paraphrased, the exact supporting quote with page or timestamp, a confidence rating with a one-line rationale, and two or three candidate links from a supplied title list. - **MOC emergence:** given N atom titles, find clusters of four or more, propose a map title, and give a one-sentence rationale per member. - **Atomicity check:** given a note, name the seam if there are two claims, or say there is one. - **Link suggestion:** propose edges with the explaining sentence, never bare links. - **Contradiction detection:** given a domain's atoms, find pairs that cannot both be true and draft the tension note. - **Audit triage:** given the audit report, group findings by likely root cause and propose one batch action per cluster. - **Decision pre-mortem:** assume the decision failed, list the three likeliest causes, and turn the checkable ones into assumptions. Fixed prompts make outputs comparable across runs, which is the same reason the rubric in [[knowledge-vaults/semantic-audit]] is fixed. Chaining them is a standard prompt pipeline, per [[prompt-engineering/prompt-chaining]]. ## 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. Each has a narrow context and a reviewable output. 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 [[knowledge-vaults/team-vaults]]. Agent decomposition patterns are covered in [[ai-agents/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. Those are the fields the vault exists to protect. ## 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 [[ai-agents/rag-retrieval]]. ## Related - [[knowledge-vaults/vault-architecture]] - [[knowledge-vaults/vault-audit]] - [[knowledge-vaults/semantic-audit]] - [[knowledge-vaults/atomic-notes]] - [[knowledge-vaults/vault-maintenance]] - [[ai-agents/multi-agent]] - [[prompt-engineering/prompt-chaining]]