BioCreative — The Operating System

Section 1

The Methodology — Contextual Engineering

The LLM is a processor. Our product is the software around it. What makes a processor useful is assembling, at the moment of the task, the right four things — and then writing the result back into the same system it read from. That last step is what compounds.

Context

What it must know. Authored in git, projected into SQL per tenant.

Skill

How to do it. 219 of them, composable atom → bundle → workflow.

Tools

What it acts on. 83 registered surfaces with credentials and bills.

Harness

The box it runs in. 27 patterns; process model, state, retries, cost.

→

Task, done

At the right level of autonomy for the job.

↵ And it writes back. New skills, corrected facts, proposed memory, updated registries. A system that consumes context but never returns to it degrades; one that writes back compounds. Every write path is propose-then-confirm — no agent silently edits production truth.

Read this first

METHODOLOGY.md

The full method in one document: processor patterns, the MCS git⇆SQL split, the composition ladder, knowledge-vs-memory, and the honest state of retrieval.

The front door

Read →

Before building

Capability Intake

Idea → capability or runtime → shape → harness → skills → context → memory → eval → trigger → registration. Run this before anything reusable.

The decision flow

Open the flow →

The model

Agent × Harness × Skill

The standard and its controlled vocabulary: trigger/lifecycle, loop-shape, swarm-shape, memory write-path, eval floor.

Governs every registry row

Open the standard →

Section 2

LLM as Processor — Three Access Patterns

These are access patterns, not product tiers. A "real agent" is not better than a one-shot — it is more expensive and less predictable. Choose the cheapest pattern that closes the task.

Pattern	What it is	Use when	Live at BC
One-shot	Single pass in, structured output out	The task is a function: classify, extract, render, score	Classification Edge Functions · a node in a BC Pipeline · structured `brain_chat`
Loop	Iterate until a breaker fires	The first answer is usually wrong and there is a way to check it	Grind (verify-loop, tests are the checker) · director task execution (bounded)
Agent	Reasons over tools, chooses its next step, holds state	The path cannot be enumerated in advance	Cortex Conductor (supervisor) · the directors

Depth and width are different axes. Loop = depth (does it iterate?). Swarm = width (does it parallelize?). Google's 2026 data: swarms help genuinely parallel work ~80% and degrade sequential reasoning 39–70%; a single agent tops out around 10–15 tools. Default single + one-shot; widen or deepen only with a reason you can state.

A loop without codified breakers is not finished. Required whenever the shape is not one-shot: max_turns, per-run dollar cap, duplicate-call detection, wall-clock timeout, and an explicit "I'm stuck" exit. Measured: one self-prompting run exceeded 1M tokens; one managed-agent run cost ~$12 in 28 minutes and failed its rubric.

Section 3

The MCS Spine — Git and SQL, on Purpose

The Modular Context System is the durable layer the whole fleet reads from. It exists twice, deliberately, because the two substrates are good at different things. The rule: author in files, retrieve and telemeter in a database.

Substrate A

Git — the authoring truth

Diffable, reviewable, replayable, and agent-native (LLMs grep and read files fluently). Git is the audit log. Holds methodology, skills, rules, workflows, brand bibles, positioning, canon docs.

Fails at: concurrent writes corrupt silently · grep degrades on paraphrase · no telemetry

Substrate B

SQL — the serving truth

Concurrency, row-level access, per-tenant scoping, semantic search, per-invocation analytics. Holds operational state, embeddings, CRM rows, resolved brand tokens served to apps, run logs.

Fails at: opaque without tooling · awkward to review · drifts from authored truth

Why this is commercial, not academic. Because brand bibles, ICP rules, and positioning are authored as structured files and projected into per-tenant SQL, a downstream skill can be contextually engineered for any tenant without being rewritten. That projection is what makes 87 skills templateable instead of BioCreative-specific.

Projection without validation is a slower way to be wrong. On 2026-08-03 we found CellScale had never once rendered in its own brand — the resolver silently dropped its nested colour objects and fell back to BioCreative teal for two months. Nothing errored, because silent inheritance was documented behaviour. The fix was to make a client pack with no primary colour fail loudly.

Reference

File vs DB — the field evidence

Interface-vs-substrate framing, when each wins, why hybrid is the mainstream answer, and the polyglot-persistence anti-pattern.

Read the analysis →

Reference

Knowledge ≠ Memory

Knowledge/RAG is the read path. Memory is the write path. The write-path ladder ends at dream-cycle-propose — BC's propose-then-promote default.

Read the ladder →

Section 4

Skills — the Composition Ladder

Capabilities compose upward: atom → bundle → workflow → agent → fleet. These are counted registry facts, not metaphors. Every skill carries its own classification in front-matter per the classification standard.

219

skills total

departments

108

atoms

bundles

106

composite use-cases

capability domains

client deliverable

templateable

100

BioCreative-only

out of scope

L1 starter

L4 workflow

The number that matters is 87. Templateable means one step away — a tenant binding, not a rewrite. Turning that into revenue is a binding problem (tenant spine + tools + credentials), not a build problem. Only 24 are deliverable today.

Top capability domains	Skills
`research`	34
`outreach`	29
`sales`	22
`infra`	20
`document`	17
`design`	16
`media-video`	12
`orchestration`	10

Browse

Skills Library

All 219 skills, filterable by disposition, level, composition, capability, and invocation. Shows the composition graph, the tools each skill uses, and which agents load it.

Generated from SKILLS_INDEX.md + front-matter

Open the library →

The contract

Skill Classification Standard

The front-matter contract: disposition, composition, level, capability (16 closed domains), handoff blockers, spine inputs, and the tools field.

Read the standard →

Section 5

Tools — the Fourth Piece

A skill says how. A tool is what it acts on: an external surface with an API, a credential, and usually a bill. Until 2026-08-03 there was no tool registry at all — the field existed on the skill schema and was empty on every skill.

tools registered

216

skills declaring tools

Backfill pending. 216 of 219 skills declare their tools. Until that reaches 100%, the “which skills break if this tool goes away” query is incomplete.

The honest framing, and it should stay consistent everywhere: the vendor tools are commodity subscriptions. The edge is the custom interconnection we built between them — staging pipelines, dedup, classification, message generation, reply routing, the modular context. The cost is real regardless.

Browse

Tools Library

Every tool by class, category, access surface, auth model, cost shape, host, and client-portability — each joined to the skills and agents that use it.

Generated from TOOLS_INDEX.md

Open the library →

The registry

TOOLS_INDEX.md

The authored source: controlled vocabulary, one row per tool, immutable slugs. Lint-enforced against every skill's tools field.

Read the registry →

The money

Tech Stack & Cost Buckets

Four buckets — find & enrich, hosting, outbound, build tooling — with how they interconnect and how each maps to a pricing tier.

The authority on cost

Open the buckets →

The load-bearing column is portable. A tool marked no_bc_oauth works only under BioCreative's OAuth grant, so any skill depending on it can never be client-deliverable without re-architecting per-tenant auth. That constraint — not build effort — is what caps the templateable count.

Section 6

Brand & Content Spine — Multi-Tenant

The brand bible is the immutable layer; tools and skills change constantly, the brand does not. A skill is correct for a client only when it loads that client's spine through the standard contract — never by hardcoding values.

client brand packs

yes

scaffold template

Brand Bible Spine

Immutable truth — tokens, logo, imagery, voice

→

Content OS

The bridge — per-brand routing

→

Content Skills

Brand-pluggable, never brand-hardcoded

→

Channels

Where it ships

Browse

Brand Spine Matrix

Every tenant pack graded against the standard: required files present, tier, WCAG contrast pass/fail, owned-vs-inherited tokens, and which content skills each pack can actually feed.

Computed from the packs themselves

Open the matrix →

The standard

Brand Bible Spine

The reproducible file manifest every brand gets, and the three sections the old template lacked.

Read the standard →

The standard

Content Spine

Mission, pillars, messaging, voice — the positioning half of the spine.

Read the standard →

Section 7

Harnesses & the Fleet

Once you know the context, skill, tools, and shape, the harness is the environment that runs it: process model, state, retries, credentials, observability, cost profile. We keep a build-agnostic menu — patterns you can build on, never BC's own products.

harness patterns

agents in fleet

VPS

core databases

Need	Harness
One-shot structured output	Pydantic AI single agent
Multi-step + tools + state	Pydantic AI in the brain-api pattern — the default
Long autonomous coding (>15 min)	Claude Code on `bc-ops` via `/delegate-vps`
Quality gate (verify-loop)	Grind / Claude Agent SDK
Genuine parallel width	Dynamic Workflows / Antigravity
Deterministic DAG	BC Pipelines on the Archon engine
Heartbeat / continuous	Workflow Console

The Karpathy principle governs this menu. "Six months is an eternity in this space." Default to strong, well-supported primitives and refine our own method rather than chase frameworks. Every new harness gets a 30-day skeptical window. We are building an iOS-style consistent system, not a museum of frameworks.

Browse

Methodology Map

The narrative plus the full harness menu with production status, the loop/swarm vocabulary, the intake flow, and which live agents run on which harness.

Open the map →

Browse

Agents Library

Every deployed agent and service with its harness, skills, trigger, host, and health.

Open the library →

Naming

Ours vs attributed

Coined external names stay attributed in the learning layer (Archon, Ralph, Dark Factory). What we build gets a BC name: BC Pipelines, Grind, MCS.

Read the glossary →

Section 8

Retrieval & Graph — the Honest State

This is the least-built part of the methodology and is described as such. The 2026 consensus is that retrieval is a three-stage pipeline — retrieve (BM25 + dense) → fuse (RRF) → rerank. BioCreative currently runs none of it.

Works

Query-time retrieval Live

brain-search, brain-router, brain-recall, meeting_search. Pennies per month. /brain-query, the directors' query_brain, and the Conductor all function.

91,717 Hub + 194,932 Brain vectors retained

Frozen

All auto-embedding Frozen

Since 2026-08-03. July's Google bill was $416, of which $404 was 2.02B embedding tokens — a pagination bug re-embedded ~96% of the corpus 4×/day while logging $0.0000 from a hardcoded zero.

Six embedders now default off behind EMBED_ENABLED

Missing

Hybrid, rerank, graph-in-path Not built

No BM25, no fusion, no reranking. Cognee/Neo4j runs and syncs but no production agent traverses it. The literature's single highest-leverage component — reranking — is absent.

Found 2026-08-03: the RAG quality CI (.github/workflows/rag-quality.yml) triggers on scripts/embed_knowledge_base.py, but the embedder moved to departments/internal-ops/scripts/ in the August reorg. That trigger is dead — embedder changes no longer run the eval. A dead quality gate is worse than none, because it implies coverage we do not have.

The cheapest meaningful improvement is not a graph and not a better embedding model. It is adding BM25 + RRF + a reranker to a corpus we have already paid to embed. Benchmarks: hybrid + rerank reaches Recall@5 0.816 vs 0.695 for hybrid alone and 0.587 for dense-only. None of it requires turning embedding back on.

Research

Graph & Retrieval Engineering

The field evidence (GraphRAG vs vector, hybrid + RRF + rerank, entity resolution as the real precondition), plus BC's unflattering audit and a cheapest-first path.

Read the reference →

Section 9

Tech Stack & Infrastructure

For an agent to have a place to live, be hosted, and hold a domain, there has to be a server. Everything below is that answer.

Host	Role	Notes
`bc-ops`	Heart — heart-api, n8n, render services, ~50 containers, all static sites	Traefik on `root_default`. Claude Max — the default target for delegated work
`bc-kb`	Brain — brain-api, LiteLLM, Ollama, the director ring, Cognee+Neo4j	Metered API key — opt-in only
`bc-made` · `bc-cubicbio` · `bc-spancorr`	Client tenants	Never used for BC processing

Database

Hub — operational

CRM, campaigns, pipeline, Edge Functions, the operational spine.

mjsgtszehjltxmbxtctz

Database

Brain — reasoning

Embeddings, agent memory, council decisions, research.

sfursphaicrvazkafbdi

Per tenant

Client spokes

One database per client, hub-and-spoke sync. SpanCorr on WIIZ, CARR, Made Transfer.

One workspace per client — hard rule

n8n's actual role: the general-purpose workflow layer for automation that does not need reasoning — polling, routing, notifications, glue. It runs on the VPS, self-hosted, across three tenants. It is not the agent runtime; that is the harness layer in section 7.

Section 10

Process Traces

Worked end-to-end paths through the system — the methodology above, instantiated. These are the shipped diagrams.

Trace

End-to-end traces

The W1–W7 process traces: how a signal becomes a scored account, a message, a meeting, a deliverable.

Read the traces →

Diagram

Account & contact lifecycle

How a record enters, gets classified, scored, enriched, and routed.

Open →

Diagram

Commercial pipeline

The revenue path from signal to signed.

Open →

Diagram

Data inputs map

Every source feeding the system.

Open →

Registry

Agent Fleet Registry

The living deployment source of truth — every container × VPS with wiring and health.

Open the registry →

Registry

BC Fleet Matrix

The correlation surface: for agent X, the whole picture — harness, skills, trigger, host, usage.

Open the matrix →

Section 11

Gaps — What Is Not Built

An explicit, dated list. This section exists because a map that only shows what works is a brochure. Internal-truth audience: everything below is real.

Gap	Impact	State
Tool backfill incomplete — 216 of 219 skills declare tools	Cannot fully answer "what breaks if this vendor goes away" or "what must a client buy"	In progress
No hybrid retrieval or reranking	Likely our largest unmeasured quality loss — our corpus is full of exact rare tokens that dense retrieval handles worst	Not started
RAG quality CI trigger is dead (path moved)	Embedder changes no longer run the eval	Broken
No incremental embedder we trust	All auto-embedding frozen; corpus goes stale from 2026-08-03	Frozen
Eval measures recall only (12 queries)	No precision, no faithfulness — we can tell the right doc was retrieved, not that it was used correctly	v1 only
Knowledge graph not in the retrieval path	Multi-hop questions fall back to vector search, which the literature says loses badly on them	Runs, unused
No per-skill invocation telemetry	The Skills Library shows inventory, not usage. We cannot tell which of 219 skills are actually used	Not started
Per-tenant credential story for media tools	Media skills are wired for BC only; portability is aspirational	Not started