Research Scan as an agent primitive

Research Scan is not an application with an agent bolted on. It is a component that agents call, and it was designed from the start to sit underneath something else.

That is a claim about shape, not ambition. The shape is: a question goes in, an agent supplies the judgement, a deterministic engine does the retrieval and the checking, and verified evidence objects come out. Nothing in that chain assumes a chat window, a particular model, or a human waiting for prose.

The shape

question
   │
   ▼
agent            planning · screening · gap queries · reranking
   │             (your model, your rubrics, your harness)
   ▼
engine           retrieve · expand · dedupe · coverage · shortlist · verify · audit
   │             (deterministic, model-free, no LLM SDK)
   ▼
evidence objects EvidencePacket JSON + Markdown, every DOI checked

The middle two rows are replaceable independently. Swap the model and the engine does not notice. Change how the engine ranks a shortlist and the model does not notice. They meet only at the file boundary.

Why a chatbot would be the wrong shape

A chat interface makes three assumptions that are wrong for this problem.

That the answer is prose. The useful output of a literature scan is structured: papers with scores, arguments, limitations and verification records. Rendering it as a paragraph throws away everything a downstream system could act on.

That one pass is enough. A scan retrieves, judges, expands from what it kept, counts coverage, refines where coverage is thin, then verifies. Those are distinct decisions with distinct inputs. A conversation flattens them into one turn.

That a human is in the loop. Sometimes there is not. A scan can run unattended and hand structured JSON to whatever comes next.

Serving as an evidence primitive

Because the output is a schema-validated object rather than a rendering, Research Scan can serve as an evidence primitive inside larger agent workflows — the step that turns “what does the literature say” into something later steps can compute on.

Some concrete shapes that follow:

A novelty check before a project starts. The agent runs a scan against the project brief, and the top of the shortlist is the prior art. relation: contradicting papers are the ones worth reading first.

A gate in a longer pipeline. A scan returns a ScanSummary; a downstream step branches on its counts. If coverage on a criterion is thin, that is a signal about the state of the field, not just about the search.

A recurring watch. The same brief, re-run on a schedule with a moving date window, produces comparable run directories. Because clocks are injectable and stages are deterministic, differences between two runs are differences in the literature, not noise in the tool.

A source of citations another agent must not invent. The strongest property for composition is negative: a downstream model handed evidence.json has real DOIs, and any record that failed verification is already marked. It does not need to be trusted about bibliography, because it was never asked to produce one.

Running it unattended

The skill returns a ScanSummary, so a scan can run headless and hand structured JSON to the next step:

claude -p "Use the research-scan skill to scan brief.md with --slug nightly --top 5. \
           When it finishes, return its ScanSummary as your final answer." \
  --plugin-dir /path/to/research-scan \
  --allowedTools "Bash(research-scan *),Read,Write,Edit,Glob,Grep" \
  --output-format json \
  --json-schema "$(research-scan schema --name ScanSummary)" \
  > scan.json

jq '.structured_output.counts' scan.json

Two details decide whether this works, both documented in the main repo:

Ask for the skill in prose. A bare /research-scan … slash command runs entirely inside the skill’s fork, so the session returns no top-level assistant turn for --json-schema to bind to and structured_output comes back null. The scan still succeeds and writes its run directory — you just do not get the structured result. Phrasing it as an instruction makes the session invoke the skill, receive the fork’s report, and emit the ScanSummary itself.

--allowedTools must carry Glob. It is not optional: the skill globs screen-batches/ to find the batches to score.

The property that makes it composable

Everything above rests on one thing: the layer that decides what counts as a verified record contains no model.

Models improve, change price, get deprecated and get replaced. If the definition of “this paper exists and its DOI resolves” lived inside a model, every one of those events would be a change to your evidence. It does not, so they are not.

The agent changes. The evidence layer stays.

Where to go next

• Agent and tool separation — the boundary in detail.
• Custom agents — driving the pipeline from something other than Claude Code.
• MCP tools — the four decision points, as tools.