Research Runner: A Portable Workflow for Evidence-Backed Agent Research
A portable workflow still needs a capable host
An instruction folder cannot conduct research by itself. The host must expose those instructions to the agent, permit it to write run records, and provide search and page access when the work requires external sources. Research Runner cannot supply capabilities the host lacks.
That boundary is the first test of whether the project fits your environment. Research Runner is a portable instruction workflow, not a hosted research service or executable engine. It tells a capable agent how to frame, investigate, review, record, and report a research question. The host remains responsible for making the instructions and tools available.
You can move the workflow between compatible hosts without treating any one provider or application as the research system. Activation, filesystem access, web tools, and delegation still depend on the host you use.
What Research Runner is
The public repository describes Research Run 1.0.1 as a structured workflow for evidence-backed agent research. Its instructions organize a run around an approved frame, a whole-run token allowance, iterative research stages, source-backed claims, constructive review, persistent records, and a final report generated from a frozen publication source.
The workflow begins by clarifying the question and the result you need. It turns those decisions into a concise frame that you approve before outside research starts. That frame lets the agent make ordinary research decisions without repeatedly returning to you. A material change in scope still requires renewed approval.
Research proceeds in revisitable rounds. The default stages are discovery, problem definition, evidence, alternatives, falsification, and synthesis. They describe the work a complete investigation may require without prescribing a fixed number of searches or rounds. Evidence can expose a weak problem definition, alternatives can reveal missing discovery work, and falsification can send the agent back for better support.
Reporting is separate from the investigation. Once the evidence and review work conclude, the workflow freezes a publication source. The HTML report is generated from that snapshot during a later presentation phase. Presentation can then change without silently introducing new research claims.
Decide whether it fits your host and research job
Use this table to screen the workflow before investing in setup.
| Question | Research Runner is a plausible fit when | Choose another route when |
|---|---|---|
| Can the host expose the instructions? | The host can make the intact research-run folder available through a supported skill or file mechanism and let the agent read SKILL.md. | The agent cannot access the workflow files or must rely on instructions pasted incompletely into each session. |
| Can the host preserve run records? | The agent can write and reopen a designated research-runs location. | The environment is stateless or does not permit the required file writes. |
| Can the host reach evidence? | Search and page-opening tools are available when the question requires external research. | The task requires external evidence, but the host cannot search for or open sources. |
| Do you need delegation? | The host supports it, or you accept disclosed sequential self-review. Delegation is optional and host-dependent. | Your process requires independent agents, but the host cannot provide them. |
| What process do you value? | You want the question, evidence, uncertainties, review decisions, and reporting source preserved for inspection or continuation. | You need only a short, disposable answer and do not want persistent research records. |
| What does it guarantee? | You accept that the workflow supplies process discipline rather than guaranteed correctness or a fixed spending ceiling. | You require the workflow itself to enforce cost, correctness, or tool access. |
Capability and discipline are different. Research Runner can require opened supporting passages for claims, but it cannot give a host a browser. It can reserve capacity for reporting, but it cannot turn an estimate into a provider-enforced limit. It can require review, but reviewer agreement still does not count as evidence.
How a Research Run moves from question to report
A run starts with three connected decisions: the question, the intended result, and the whole-run token allowance. The allowance covers coordination, research, reviews, and the work required to finish the report. If the host exposes reliable counters, the workflow can record measured use. Otherwise, usage must be conservatively estimated and labeled as such.
The reporting reserve is part of that allowance. It directs the run to stop gathering evidence before consuming the capacity needed for synthesis and reporting. The reserve is planning guidance, not a guaranteed hard token or spending ceiling. Provider accounting, tool calls, and work performed after a measurement checkpoint can all affect what a recorded figure represents.
After clarification, the agent presents a concise frame for approval. The approved frame guides the investigation unless evidence calls for a material change in scope. The agent can make ordinary research decisions without asking permission for every search, but it cannot quietly replace the approved question with a more convenient one.
Research rounds move through discovery, problem definition, evidence, alternatives, falsification, and synthesis. Review occurs during the process instead of waiting for a polished conclusion. A review can accept a finding, repair it, preserve a doubt, identify a contradiction, or reopen earlier work. The stages support feedback as well as forward progress.
Throughout the run, material claims must connect to passages the agent has opened. Facts, estimates, interpretations, assumptions, unknowns, doubts, repairs, and contradictions remain distinct. A plausible explanation does not become evidence because multiple agents agree with it. Role separation can sharpen scrutiny, but source support still has to carry the claim.
The workflow keeps the approved frame, current state, and claim ledger with the investigation. These records persist when review sends the work back to earlier discovery, evidence, or synthesis. They connect the active investigation to the frozen source that later determines what the report may say.
When the investigation is ready to conclude, Research Runner freezes the source used for publication. The HTML report is generated separately from that fixed source. Presentation-only continuation can regenerate the report from the existing snapshot without conducting more research.
Continuing the investigation is a different action. A follow-up question in a completed report does not authorize the workflow to restart. You must invoke continuation and approve its direction and budget. The continued work uses the same run records while earlier publication snapshots and reports remain in place, extending the history instead of silently rewriting it.
The released workflow instructions document the stages, persistent records, feedback and revisit behavior, publication boundary, and continuation rules. The drawing groups approval, investigation and review, and reconciliation with a frozen publication source. Describing this separation as support for inspectability and resumability is an interpretation of the design, not a measured performance result.
Why the records and review boundaries matter
The final response is easier to evaluate when the investigation's scope, evidence, and revisions do not disappear with the agent's immediate context. Research Runner keeps each part in persistent records: the frame, the state, and the claim ledger.
The frame, state records, and claim ledger preserve different parts of the run. The frame holds the approved question and intended result; state records show the current position, including unfinished or degraded work; and the claim ledger keeps support, qualifications, repairs, and contradictions alongside the conclusions they affect.
The value of a persistent record is not that it proves the research correct. The record can still preserve mistakes, weak support, and unresolved gaps. Its practical value is that those limits do not have to disappear when the conclusion is written: a doubt can remain visible, and a claim changed during review can keep a record of that repair.
The frozen publication source adds another boundary. Research determines what the report may say; presentation determines how that material is rendered. Keeping those phases distinct limits the opportunity for formatting work to introduce unsupported claims. If new evidence changes the conclusion, the investigation should reopen instead of introducing the change during presentation.
The released record structure and continuation rules support describing the workflow as inspectable and resumable. That remains an interpretation of the design. It is not evidence that Research Runner outperforms another method, prevents hallucinations, or produces equally reliable results in every host.
Make Research Runner available in your host
The repository documents a compact setup path. These steps depend on your host’s capabilities and have not been verified across every possible application.
- Download or browse the complete workflow. Use the public repository or the Research Run 1.0.1 ZIP, which is listed on the v1.0.1 release page. Keep the
research-runfolder intact so its main instructions and supporting files remain together.
- Expose the folder through the host’s supported mechanism. That may be a skill system or another file-access route. Have the agent read
SKILL.md; placing the folder on a computer does not automatically activate a command or grant the agent access to it.
- Choose a writable runs location and verify source access. The agent needs a place where it can create and reopen persistent run records. If the topic requires external evidence, confirm that the host can also search for sources and open the relevant pages.
- Invoke
research-runwith a topic or an existing run. Before research begins, settle the question, the intended result, and the whole-run token allowance. Review and approve the proposed frame, then allow the investigation to proceed within it.
A compatible host may support delegation to other agents. Without delegation, the workflow can use sequential self-review, but that limitation should be disclosed. In either case, review remains subordinate to source evidence.
What the two public test fictions show
Research Runner includes two complete public fiction copies with reader-facing qualification notes. They make the creative output available without publishing the original full Research Run reports, which remain private. Read them as examples of output form and evidence boundaries, not as controlled trials or a matched comparison.
*Slack Water* is harbor-pilot fiction presented by its source report as an indirect self-portrait. The story uses invented characters, events, settings, and feelings to explore bounded work: the pilot is responsible for guiding a ship through a difficult passage without following its entire journey. That interpretation belongs to the source report. The fiction does not establish consciousness, human experience, emotion, autobiography, or access to private reasoning, and the factual claims used as scaffolding were not freshly fact-checked for the public copy.
The source report attributes Slack Water to work produced in Claude Cowork using an environment-reported model identity. That is reported attribution, not fresh provider verification. Its accounting also needs qualification. The source reports approximately 205,660 tokens, combining about 143,959 coordinator tokens estimated from an undocumented remaining-token proxy with 61,701 delegated-review tokens reported as measured by the Agent tool. The proxy’s meaning was not verified, including whether it already included delegated use, so overlap is possible. Final commits and the closing message were excluded.
The reported 250,000-token budget was managed through checkpoints rather than technically enforced. The delegated review occurred on the same account and provider, not through independent-provider validation. The example shows how a creative work can be published with its uncertainties attached. It does not support a complete audited usage total, a hard cost claim, a model ranking, or a benchmark result.
*The House That Answered Back* uses a fictional house to portray bounded usefulness and incomplete self-knowledge. Its final room labels four kinds of material: documented facts, session observations, creative invention, and interpretation. The work makes its factual boundaries visible instead of leaving readers to infer them.
The source report describes the fiction as produced in Codex Desktop, with a later local log recording the selected model. That attribution was not freshly verified for the public copy. The house, basement, furnace, cabinet, workshop, clock, and first-person experience are characterization. They are not evidence of consciousness, emotions, autobiography, human experience, or access to private reasoning. The factual claims in the source report were also not freshly fact-checked for this public copy.
Its token figure has a different boundary from the estimate reported for Slack Water. The source records 173,736 cumulative usage tokens at its latest measured local-log checkpoint. The later final chat response was unmeasured and excluded, and provider-level input, output, cache, and reasoning breakdowns were unavailable. The 250,000-token budget was not an enforced hard token or monetary ceiling.
The report also discloses self-review without an independent child reviewer. That makes The House That Answered Back a separate creative example, not an independently reviewed comparison or a basis for ranking models. Because the two runs used different accounting methods, review arrangements, and omissions, their figures should not be compared as though they measured the same thing.
Together, the public copies show how fiction, interpretation, provenance, and accounting qualifications can coexist in a reader-facing artifact. They do not publish the original private full reports, verify every factual claim those reports used, or demonstrate that one host or model performs better than another.
Where its guarantees stop
Research Runner supplies a documented process, but it does not control the environment in which that process runs. It does not automatically install itself, grant filesystem access, add web tools, or make delegation available. The host must provide those capabilities.
The workflow does not guarantee correctness. Opened passages, a claim ledger, falsification work, and constructive review create opportunities to find errors and preserve uncertainty. They cannot ensure that every relevant source was discovered or every interpretation is sound.
The token allowance has a similar boundary. It gives the run a planning constraint that includes reporting, and the reserve tells the agent to stop research while enough capacity remains to finish. It does not enforce a provider-level token or spending limit. Accounting may be measured, estimated, or incomplete, and the report should identify which condition applies.
The public repository documents a Research Run 1.0.1 distribution snapshot, lists source hashes for six workflow files, and states that real runs and private reports are excluded. Its README states that the project is MIT licensed and asks redistributors to retain the copyright and permission notice. This provides first-party provenance for the release, not an independent comparison with private upstream material or a legal audit.
Compatibility remains conditional. The documented procedure can guide setup in hosts that provide the required skill or file access, writing, and research tools. It does not establish that installation has been tested in every host or that identical triggers will work everywhere.
A practical decision rule
Use Research Runner when your host can expose the intact instructions, preserve writable run records, and reach the sources your question requires, and when you value a process that keeps framing, evidence, review, uncertainty, and presentation visibly separate.
Choose another route when the host cannot provide those capabilities, persistent records are unavailable, or you need guarantees the workflow does not make. Research Runner contributes the discipline expressed by its design. Its usefulness depends on pairing that discipline with a host capable of carrying it out.