Overview
Orchestration is the loop between a source arriving and an atom being linked, audited, and promoted. An agent can do most of it: propose atoms, propose links, run the auditor, cluster findings. It should not decide what is true. This page defines the loop, the fixed prompts that run it, and the guardrails. The structure it operates on is in 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, the agent can write a correctly shaped note on the first attempt and judge whether an existing note is wrong. Without them it writes plausible notes that fail the audit and teach the vault a competing convention. The principle is the one in claude-code-claude-md: load the conventions before editing.
Run five stages with a handoff at each
- Capture. Raw material lands in
00-Inbox/unshaped. - Extract. The agent proposes atoms from a source. Output goes to the user, not the vault.
- Link. The agent proposes edges against existing titles, each with the sentence explaining it.
- Audit. The deterministic auditor runs, then the semantic pass if due (vault-audit, semantic-audit).
- Promote. The user moves seedling to budding to evergreen (atomic-notes). This stage is never delegated.
Each stage produces reviewable output. An agent that runs all five without stopping produces a vault of unverified claims that look identical to verified ones.
Keep the prompts fixed and versioned
Freehand asks (“extract the key ideas”) return a different shape every time, so runs cannot be compared or audited. Store each recurring prompt in the vault under 90-Templates/ or 99-Tools/, give it a fixed input and output contract, change it through the same review path as any vault change, and note the date. The judging rubric in semantic-audit is fixed for the same reason.
| Prompt | Input | Output | Limit |
|---|---|---|---|
| Extract atoms | Source text plus existing atom titles | Per atom: claim title, 2 to 5 sentence paraphrase, supporting quote with location, confidence with rationale, 2 or 3 candidate links from the supplied titles | Never copy text; one idea per atom |
| Emerge maps | N atom titles from one domain | Clusters of 4 or more, a map title each, one-sentence rationale per member | Clusters under 4 are not yet a map |
| Find the seam | One note | The sentence where it pivots from its first claim to a second, or “one idea” | Asks for evidence, not a verdict |
| Suggest links | New atom plus up to 50 candidate titles | 3 to 7 ranked links, each with a rationale and a type: supports, refines, contradicts, generalizes, specializes, depends on, or parallel to | Say so if fewer than 3 truly connect; padding creates the naked link dump S009 flags |
| Detect contradictions | A domain’s atoms | Pairs that cannot both be true, with a draft contradiction note and resolution criterion | Proposes, never resolves |
| Triage the audit | The auditor’s JSON | Findings grouped by root cause, one batch action per cluster, criticals listed first | Turns 30 findings into a few sessions |
| Pre-mortem | A draft decision entry | Assume failure at 18 months, the three likeliest causes, checkable ones as new key_assumptions | See decision-journals |
Chain the prompts; do not merge them
Extraction feeds link suggestion, then the atomicity check, then the audit. Each stage’s output is the next stage’s input and is reviewable alone. Merging them into one large prompt removes the handoffs that stop an agent from writing unverified claims straight into the vault. The pattern is the standard one in prompt-chaining.
Divide agents by stage, not by folder
Use an extraction agent that reads sources, an audit agent that runs the script and triages, and a synthesis agent that assembles drafts. Do not split by folder or domain: two agents writing atoms into one vault create duplicate claims under different titles, the vault equivalent of a duplicate key. If more than one writer is unavoidable, route new titles through one naming authority (team-vaults). Patterns are in multi-agent.
Guard every bulk write
- Propose, then apply. Describe and confirm individual fixes. Silence is not approval.
- Scope-freeze bulk operations. Anything touching more than a handful of files gets an explicit path list, a stated undo path, and confirmation before execution.
- Version control is the undo. If the vault is not in Git, say so and treat every bulk write as irreversible.
The agent never edits a decision’s pre-decision section, never fills a source or confidence it cannot derive, and never resolves a contradiction for the user.
Make the vault readable to a cold agent
Keep a dashboard note with the query gates and a root map naming the domains, so an agent has an index instead of a directory walk. Typed frontmatter, one claim per file, and explained links make a retrieved note useful alone, the property that makes a chunk useful in rag-retrieval.