Knowledge Workflows — the tool that returns a playbook

The single workflow MCP tool is the most interesting thing in OpenKnowledge. It is a dispatcher over four knowledge-building modes — discover, ingest, research, consolidate — and each mode, when called, returns a long block of instructional prose that the agent then follows. The tool's output is a prompt. OK uses MCP not to do work, but to hand the agent a procedure.

The design is credited in the code to Andrej Karpathy's three-layer wiki pattern (packages/server/src/mcp/tools/shared.ts:161-179).

1. The three layers

   raw sources  ──ingest──►  provisional wiki  ──consolidate──►  canonical wiki
   (immutable)               (status: provisional)               (status: canonical)
        ▲                          ▲                                   ▲
     fetched by agent         written by agent                  promoted after a
     or shared by user        with citations                    human DECISION lands

   discover ── (one-time) extract folder conventions + activate the link graph

The agent does the bookkeeping (fetch, cite, cross-link, supersede). The human stays the decision gate. That division is the whole philosophy.

2. How the dispatcher works

workflow.ts:39-114 wires each kind to a body-builder:

const ingest      = buildWorkflowHandler('ingest', deps, 'source', buildIngestBody);
const research    = buildWorkflowHandler('research', deps, 'topic', buildResearchBody);
const consolidate = buildWorkflowHandler('consolidate', deps, 'topic', buildConsolidateBody);

buildWorkflowHandler (shared.ts:187-202) wraps each body in a shared "workflow frame" (the Karpathy context + role framing) and returns it as text (textPlusStructured(body, { previewUrl: null }), shared.ts:199-200). The body files are large prose procedures, not code:

• discover-body.ts — 7 phases
• ingest-body.ts — 7 steps
• research-body.ts — 8 mandatory steps (:28-41)
• consolidate-body.ts — 6 steps

3. The four procedures (and their gates)

discover — make an existing repo navigable

Seven phases, each a STOP gate (no auto-apply): scan & classify folders → confirm scope → curate .okignore → extract per-folder conventions → activate the link graph (orphan triage, hub identification, dead-link sweep, untextualized-reference detection, vague-reference detection via LLM judgment, link-style standardization) → validate → summarize. The agent leaves the repo "more structured and more navigable than you found it" without restructuring anything the user didn't approve (discover-body.ts).

ingest — preserve a raw source, faithfully

"Raw preservation only — no summary, no analysis, no interpretation." It detects binary vs. text, hard-stops on DRM/streaming, non-http schemes, executables, and oversized files; derives a path-traversal-safe slug (^[a-z0-9][a-z0-9-]{0,99}$); downloads with constrained curl flags; wraps the artifact in a markdown file with a sha256/bytes/media_type frontmatter; and records a supersedes pointer on re-ingest when the hash changes (ingest-body.ts). The point is a closed loop: sources are pulled into the KB so downstream docs cite local paths, never bare URLs that rot.

research — investigate, provisionally

Eight hard-gated steps (research-body.ts:28-41): create checkpoint tasks → scan existing coverage (don't re-research) → collaborative scoping STOP gate → ingest 3–8 sources → read & write the article section-by-section as you go (never one final dump) → every claim cites a source → link aggressively → validate → recap. Frontmatter is status: provisional; the voice is mandated provisional ("tentative", "initial findings"). Two autonomy modes: Supervised (stop at the scoping gate) and Headless (auto-confirm scoping; other gates still hold).

consolidate — promote, only after a decision

Six steps behind one decision STOP gate: "Has a decision actually been made?" If not, do not consolidate — research stays provisional indefinitely. When it proceeds, it writes a status: canonical article in a decided voice ("we chose", not "we recommend"), adds supersedes: [research.md] to the canonical, and stamps superseded_by: canonical.md onto the research it replaces (consolidate-body.ts). The supersedes chain is an audit trail: a future reader can walk canonical → research → raw sources.

4. Why this is the clever part

Three patterns compound here, and each is independently worth stealing:

1. The tool result is the agent's procedure. Instead of encoding the workflow as orchestration code, OK encodes it as text the agent reads when it calls the tool. The "harness" is a prompt delivered just-in-time. This is the same family as markdown-as-skills and scope-injected-at-render, pushed further: the procedure is delivered per tool call, scoped to the mode requested.
2. Provisional vs. canonical is a typed, enforced distinction. A reader of a provisional doc knows uncertainty is allowed; a canonical doc is load-bearing. The consolidate STOP gate makes canonicality earned, not presumed — exactly the discipline you want when agents author and humans approve.
3. STOP gates over auto-apply. Every phase proposes and waits. The agent never silently advances the knowledge base's state of truth.

What's worth stealing (for Swisscheese & AI-Act)

1. Deliver the playbook as the tool's return value. A code-review meta-harness could expose a review tool whose result is the rubric for this diff — versioned server-side, no agent re-prompting.
2. Provisional → canonical with a human decision gate maps directly onto "draft review → approved finding". The supersedes chain is your audit log.
3. Persist as you go. Writing the article section-by-section means a crash after 5 of 8 sources leaves 5 safe — the KB is the checkpoint. For long review runs, write findings incrementally, not in one final report.
4. Evidence discipline before synthesis. "Capture raw sources first, cite every claim" is precisely the traceability an AI Act audit wants (Art. 12) — a finding with preserved sources is reviewable; one without is opinion.
5. STOP gates encode human oversight (Art. 14) as a first-class control, not an afterthought.